frog

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 28, 2020 License: MIT Imports: 12 Imported by: 7

README

frog

Overview

Frog is a package for logging output.

When connected to a terminal, Frog allows lines to be fixed to the bottom of the output, allowing for display of data that would be surperfluous in a log file, but is really nice to have when watching the output in a terminal.

Frog uses ANSI/VT-100 commands to change colors and move the cursor. For this to work in Windows, you must either be using Windows 10 build 1511 (circa 2016) or newer, or be using a third-party terminal application like ConEmu/Cmdr or mintty. There's no planned supoprt for the native command prompts of earlier versions of Windows.

animated gif of frog in action

Features

  • Multiple logging levels
  • Fixing one or more lines in place for progress bars and real-time status displays (via ANSI commands)
  • Colorized output (via ANSI commands)
  • Detects if there's a connected terminal, and disables ANSI-based output as needed
  • Loggers target the io.Writer interface, allowing your logs to be easily sent to files, buffers, etc
  • Customizable line style, with built in styles for lines in plain text or JSON
    • Alternatively, you can write your own Printer that can generate your own custom style
  • Loggers can be written to target other loggers (see TeeLogger), allowing a single logger to target multiple outputs and/or styles simultaneously (ie plain text w/ fixed lines on stdout, while also sending json to a file on disk).

Usage

The quickest way to get started is to create one of the default Loggers via a call to frog.New:

  log := frog.New(frog.Auto)
  defer log.Close()

  log.Info("Example log line")
  log.Warning("Example warning")

  status := frog.AddFixedLine(log)
  for i := 0; i <= 100; i++ {
    status.Transient(" + complete", frog.Int("percent", n))
    time.Sleep(time.Duration(10) * time.Millisecond)
  }
  status.Info("Done", n)

The parameter frog.Auto tells New to autodetect if there's a terminal on stdout, and if so, to enable support for fixed lines and colors. There are other default styles you can pass to New as well, like frog.Basic and frog.JSON.

frog.JSON will output each log line as a single JSON object. This allows structured data to be easily consumed by a log parser that supports it (ie filebeat). A JSON logger created in this way doesn't support fixed lines, and by default will not output Transient level lines, but from the code's perspective, the API is identical, and calls to AddFixedLine and Transient continue to behave the same as before.

You can also build a custom Logger, with its own custom line printing style, and using sources other than stdout. See the implementation of the New function in frog.go for examples.

Here's a complete list of Frog's log levels, and their intended uses:

level description
Transient Output that is safe to ignore (like progress bars and estimated time remaining).
Verbose Output for debugging (disabled most of the time).
Info Normal log lines (usually enabled).
Warning Unusual events.
Error Something went wrong.
Fatal After displaying this log line, halt the entire app.

TODO

  • ✓ Write to two Loggers simultaneously
  • ✓ JSON Printer
  • ✓ rework how fixed lines are released
  • ✓ structured logging
  • ✓ NullLogger for when you want to pass a frog.Logger that nops
  • ✓ add options to frog.New() for color, timestamps, etc
  • ✓ TextLogger has min indent (greater than normal indent) for the first field
  • ✓ use colors to make difference betwen fields and msg more obvious
  • FilterLogger which can dynamically switch between logging and nopping
  • go doc pass
  • run it on other platforms
  • make some benchmarks, maybe do a pass on performance

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HasTerminal added in v0.4.1 

func HasTerminal(w io.Writer) bool

HasTerminal returns true if the passed writer is connected to a terminal

func RemoveFixedLine added in v0.3.0 

func RemoveFixedLine(log Logger)

Types

type Buffered 

type Buffered struct {
	// contains filtered or unexported fields
}

func NewBuffered 

func NewBuffered(cfg Config, prn Printer) *Buffered

func (*Buffered) AddFixedLine 

func (l *Buffered) AddFixedLine() Logger

AddFixedLine creates a Logger that, when connected to a terminal, draws over itself. Thread safe.

func (*Buffered) Close 

func (l *Buffered) Close()

Close should be called before the app exits, to ensure any buffered output is flushed. Thread safe.

func (*Buffered) Error added in v0.4.0 

func (l *Buffered) Error(format string, a ...Fielder) Logger

func (*Buffered) Fatal added in v0.4.0 

func (l *Buffered) Fatal(format string, a ...Fielder)

func (*Buffered) Info added in v0.4.0 

func (l *Buffered) Info(format string, a ...Fielder) Logger

func (*Buffered) Log added in v0.4.0 

func (l *Buffered) Log(level Level, format string, fields ...Fielder) Logger

func (*Buffered) SetMinLevel 

func (l *Buffered) SetMinLevel(level Level) Logger

func (*Buffered) Transient added in v0.4.0 

func (l *Buffered) Transient(format string, a ...Fielder) Logger

func (*Buffered) Verbose added in v0.4.0 

func (l *Buffered) Verbose(format string, a ...Fielder) Logger

func (*Buffered) Warning added in v0.4.0 

func (l *Buffered) Warning(format string, a ...Fielder) Logger

type ChildLogger added in v0.2.0 

type ChildLogger interface {
	// Parent returns the parent Logger, or nil if it has no parent.
	Parent() Logger
}

ChildLogger is the interface for loggers that feed back to a parent.

type Config 

type Config struct {
	Writer   io.Writer
	UseColor bool
}

type Field added in v0.4.0 

type Field struct {
	IsJSONString bool // if true, the string in Value should be bookended by double quotes to be valid JSON
	IsJSONSafe   bool // if true, this string only contains alpha-numerics, spaces, and safe punctuation
	Name         string
	Value        string
}

type FieldBool added in v0.4.0 

type FieldBool struct {
	Name  string
	Value bool
}

func Bool added in v0.4.0 

func Bool(name string, value bool) FieldBool

Bool adds a field whose value will be true or false

func (FieldBool) Field added in v0.4.0 

func (f FieldBool) Field() Field

type FieldDuration added in v0.4.0 

type FieldDuration struct {
	Name  string
	Value time.Duration
}

func Dur added in v0.4.0 

func Dur(name string, value time.Duration) FieldDuration

Dur adds a time.Duration field

func Duration added in v0.4.0 

func Duration(name string, value time.Duration) FieldDuration

Duration adds a time.Duration field

func (FieldDuration) Field added in v0.4.0 

func (f FieldDuration) Field() Field

type FieldError added in v0.4.0 

type FieldError struct {
	Name  string
	Value error
}

func Err added in v0.4.0 

func Err(value error) FieldError

Err adds an error field named "error"

func (FieldError) Field added in v0.4.0 

func (f FieldError) Field() Field

type FieldFloat64 added in v0.4.0 

type FieldFloat64 struct {
	Name  string
	Value float64
}

func Float32 added in v0.4.0 

func Float32(name string, value float32) FieldFloat64

Float32 adds a 32-bit floating point number field

func Float64 added in v0.4.0 

func Float64(name string, value float64) FieldFloat64

Float64 adds a 64-bit floating point number field

func (FieldFloat64) Field added in v0.4.0 

func (f FieldFloat64) Field() Field

type FieldInt64 added in v0.4.0 

type FieldInt64 struct {
	Name  string
	Value int64
}

func Int added in v0.4.0 

func Int(name string, value int) FieldInt64

Int adds a signed integer field

func Int8 added in v0.4.0 

func Int8(name string, value int8) FieldInt64

Int8 adds an 8-bit signed integer field

func Int16 added in v0.4.0 

func Int16(name string, value int16) FieldInt64

Int16 adds a 16-bit signed integer field

func Int32 added in v0.4.0 

func Int32(name string, value int32) FieldInt64

Int32 adds a 32-bit signed integer field

func Int64 added in v0.4.0 

func Int64(name string, value int64) FieldInt64

Int64 adds a 64-bit signed integer field

func (FieldInt64) Field added in v0.4.0 

func (f FieldInt64) Field() Field

type FieldString added in v0.4.0 

type FieldString struct {
	Name  string
	Value string
}

func String added in v0.4.0 

func String(name string, value string) FieldString

String adds an escaped and quoted string field

func (FieldString) Field added in v0.4.0 

func (f FieldString) Field() Field

type FieldTimeFormat added in v0.4.0 

type FieldTimeFormat struct {
	Name   string
	Value  time.Time
	Format string
}

func Time added in v0.4.0 

func Time(name string, value time.Time) FieldTimeFormat

Time adds a time.Time field that will output a string formatted using RFC 3339 (ISO 8601)

func TimeNano added in v0.4.0 

func TimeNano(name string, value time.Time) FieldTimeFormat

TimeNano adds a time.Time field that will output a string formatted using RFC 3339 with nanosecond precision

func (FieldTimeFormat) Field added in v0.4.0 

func (f FieldTimeFormat) Field() Field

type FieldTimeUnix added in v0.4.0 

type FieldTimeUnix struct {
	Name  string
	Value time.Time
	Nano  bool
}

func TimeUnix added in v0.4.0 

func TimeUnix(name string, value time.Time) FieldTimeUnix

TimeUnix adds a time.Time field that outputs as a unix epoch (unsigned integer)

func TimeUnixNano added in v0.4.0 

func TimeUnixNano(name string, value time.Time) FieldTimeUnix

TimeUnixNano adds a time.Time field that outputs as a unix epoch with nanosecond precision (unsigned integer)

func (FieldTimeUnix) Field added in v0.4.0 

func (f FieldTimeUnix) Field() Field

type FieldUint64 added in v0.4.0 

type FieldUint64 struct {
	Name  string
	Value uint64
}

func Byte added in v0.4.0 

func Byte(name string, value byte) FieldUint64

Byte adds an 8-bit unsigned integer field

func Uint added in v0.4.0 

func Uint(name string, value uint) FieldUint64

Uint adds an unsigned integer field

func Uint8 added in v0.4.0 

func Uint8(name string, value uint8) FieldUint64

Uint8 adds an 8-bit unsigned integer field

func Uint16 added in v0.4.0 

func Uint16(name string, value uint16) FieldUint64

Uint16 adds a 16-bit unsigned integer field

func Uint32 added in v0.4.0 

func Uint32(name string, value uint32) FieldUint64

Uint32 adds a 32-bit unsigned integer field

func Uint64 added in v0.4.0 

func Uint64(name string, value uint64) FieldUint64

Uint64 adds a 64-bit unsigned integer field

func (FieldUint64) Field added in v0.4.0 

func (f FieldUint64) Field() Field

type Fielder added in v0.4.0 

type Fielder interface {
	Field() Field
}

Fielder is an interface used to add structured logging to calls to Logger methods

type FixedLine 

type FixedLine struct {
	// contains filtered or unexported fields
}

FixedLine is a Logger that treats Transient level log data in a special way: - Transient level is never ignored, and always overwrites the same output line. - Non-Transient level is sent to the parent logger.

func (*FixedLine) Close 

func (l *FixedLine) Close()

func (*FixedLine) Error added in v0.4.0 

func (l *FixedLine) Error(msg string, fields ...Fielder) Logger

func (*FixedLine) Fatal added in v0.4.0 

func (l *FixedLine) Fatal(msg string, fields ...Fielder)

func (*FixedLine) Info added in v0.4.0 

func (l *FixedLine) Info(msg string, fields ...Fielder) Logger

func (*FixedLine) Log added in v0.4.0 

func (l *FixedLine) Log(level Level, msg string, fields ...Fielder) Logger

func (*FixedLine) Parent added in v0.2.0 

func (l *FixedLine) Parent() Logger

func (*FixedLine) RemoveFixedLine added in v0.3.0 

func (l *FixedLine) RemoveFixedLine()

func (*FixedLine) SetMinLevel 

func (l *FixedLine) SetMinLevel(level Level) Logger

func (*FixedLine) Transient added in v0.4.0 

func (l *FixedLine) Transient(msg string, fields ...Fielder) Logger

func (*FixedLine) Verbose added in v0.4.0 

func (l *FixedLine) Verbose(msg string, fields ...Fielder) Logger

func (*FixedLine) Warning added in v0.4.0 

func (l *FixedLine) Warning(msg string, fields ...Fielder) Logger

type FixedLineAdder added in v0.3.0 

type FixedLineAdder interface {
	AddFixedLine() Logger
}

FixedLineAdder is the interface for loggers that support fixing a line in place, for progress bars or other transient status messages.

type FixedLineRemover added in v0.3.0 

type FixedLineRemover interface {
	RemoveFixedLine()
}

FixedLineRemover is the interface that a fixed line logger must implement in order for the fixed line to be removed before app end.

type JSONPrinter added in v0.2.1 

type JSONPrinter struct {
	TimeOverride time.Time
}

func (*JSONPrinter) Render added in v0.2.1 

func (p *JSONPrinter) Render(useColor bool, level Level, msg string, fields ...Fielder) string

type Level 

type Level byte
const (
	Transient Level = iota // strictly unimportant, ie progress bars, real-time byte counts, estimated time remaining, etc
	Verbose                // debugging info
	Info                   // normal message
	Warning                // something unusual happened
	Error                  // something bad happened
	Fatal                  // stop everything right now

)

func (Level) String added in v0.2.1 

func (l Level) String() string

type Logger 

type Logger interface {
	// Close ensures any buffers are flushed and any resources released.
	// It is safe to call Close more than once (but consecutive calls do nothing).
	Close()

	// SetMinLevel sets the lowest Level that will be logged.
	SetMinLevel(level Level) Logger

	// Log is how all log lines are added.
	Log(level Level, format string, a ...Fielder) Logger

	// Transient et al are just shortcuts for calling Log with specific levels.
	// Note that Fatal will never return, as it flushes any buffers then calls os.Exit(-1).
	Transient(format string, a ...Fielder) Logger
	Verbose(format string, a ...Fielder) Logger
	Info(format string, a ...Fielder) Logger
	Warning(format string, a ...Fielder) Logger
	Error(format string, a ...Fielder) Logger
	Fatal(format string, a ...Fielder)
}

func AddFixedLine added in v0.2.0 

func AddFixedLine(log Logger) Logger

AddFixedLine adds a new logger on a fixed line, if supported. Else, returns passed in Logger.

func New 

func New(t NewLogger, opts ...Option) Logger

New creates a Logger that writes to os.Stdout, depending on the NewLogger type passed to it: - Auto - if terminal detected on stdout, then colors and fixed lines are supported (else, uses Basic) - Basic - no colors or fixed lines, no buffering - JSON - no colors or fixed lines, no buffering, and each line is a valid JSON object Resulting Logger can be modified by including 1 or more NewOpts after the NewLogger type. The caller is responsible for calling Close() when done with the returned Logger.

func Parent added in v0.2.0 

func Parent(log Logger) Logger

func ParentOrSelf added in v0.2.0 

func ParentOrSelf(log Logger) Logger

type NewLogger added in v0.2.0 

type NewLogger byte
const (
	Auto NewLogger = iota
	Basic
	JSON
)

type NullLogger added in v0.6.0 

type NullLogger struct {
}

func (*NullLogger) Close added in v0.6.0 

func (n *NullLogger) Close()

func (*NullLogger) Error added in v0.6.0 

func (n *NullLogger) Error(format string, a ...Fielder) Logger

func (*NullLogger) Fatal added in v0.6.0 

func (n *NullLogger) Fatal(format string, a ...Fielder)

func (*NullLogger) Info added in v0.6.0 

func (n *NullLogger) Info(format string, a ...Fielder) Logger

func (*NullLogger) Log added in v0.6.0 

func (n *NullLogger) Log(level Level, format string, a ...Fielder) Logger

func (*NullLogger) SetMinLevel added in v0.6.0 

func (n *NullLogger) SetMinLevel(level Level) Logger

func (*NullLogger) Transient added in v0.6.0 

func (n *NullLogger) Transient(format string, a ...Fielder) Logger

func (*NullLogger) Verbose added in v0.6.0 

func (n *NullLogger) Verbose(format string, a ...Fielder) Logger

func (*NullLogger) Warning added in v0.6.0 

func (n *NullLogger) Warning(format string, a ...Fielder) Logger

type Option added in v0.6.0 

type Option byte
const (
	// UseStdout sends all output to stdout (default).
	UseStdout Option = iota
	// UseStderr sends all output to stderr.
	UseStderr
	// Color enables use of ANSI commands to add color (default). Note that colors cannot be enabled when
	// using the Basic or JSON logger types, or if a NO_COLOR environment variable is present.
	Color
	// NoColor disables use of ANSI commands to add color.
	NoColor
	// ShowTimestamps enables the inclusion of time/date (default). Note that JSON type always adds timestamps.
	ShowTimestamps
	// HideTimestamps disables the inclusion of time/date.
	HideTimestamps
	// ShowLevel enables the inclusion of the log level of each log line (ie "[nfo]", "[WRN]", "[ERR]", etc).
	ShowLevel
	// HideLevel disables the inclusion of the log level with each log line. Note that JSON type always adds log level.
	HideLevel
)

type Printer 

type Printer interface {
	Render(useColor bool, level Level, format string, fields ...Fielder) string
}

type TeeLogger added in v0.2.0 

type TeeLogger struct {
	Primary   Logger
	Secondary Logger
}

TeeLogger directs all traffic to both a primary and secondary logger

func (*TeeLogger) AddFixedLine added in v0.2.0 

func (l *TeeLogger) AddFixedLine() Logger

func (*TeeLogger) Close added in v0.2.0 

func (l *TeeLogger) Close()

func (*TeeLogger) Error added in v0.4.0 

func (l *TeeLogger) Error(msg string, fields ...Fielder) Logger

func (*TeeLogger) Fatal added in v0.4.0 

func (l *TeeLogger) Fatal(msg string, fields ...Fielder)

func (*TeeLogger) Info added in v0.4.0 

func (l *TeeLogger) Info(msg string, fields ...Fielder) Logger

func (*TeeLogger) Log added in v0.4.0 

func (l *TeeLogger) Log(level Level, msg string, fields ...Fielder) Logger

func (*TeeLogger) RemoveFixedLine added in v0.3.0 

func (l *TeeLogger) RemoveFixedLine()

func (*TeeLogger) SetMinLevel added in v0.2.0 

func (l *TeeLogger) SetMinLevel(level Level) Logger

func (*TeeLogger) Transient added in v0.4.0 

func (l *TeeLogger) Transient(msg string, fields ...Fielder) Logger

func (*TeeLogger) Verbose added in v0.4.0 

func (l *TeeLogger) Verbose(msg string, fields ...Fielder) Logger

func (*TeeLogger) Warning added in v0.4.0 

func (l *TeeLogger) Warning(msg string, fields ...Fielder) Logger

type TextPrinter added in v0.2.1 

type TextPrinter struct {
	PrintTime  bool
	PrintLevel bool
}

func (*TextPrinter) Render added in v0.2.1 

func (p *TextPrinter) Render(useColor bool, level Level, msg string, fields ...Fielder) string

type Unbuffered added in v0.2.0 

type Unbuffered struct {
	// contains filtered or unexported fields
}

func NewUnbuffered added in v0.2.0 

func NewUnbuffered(cfg Config, prn Printer) *Unbuffered

func (*Unbuffered) Close added in v0.2.0 

func (l *Unbuffered) Close()

func (*Unbuffered) Error added in v0.4.0 

func (l *Unbuffered) Error(msg string, fields ...Fielder) Logger

func (*Unbuffered) Fatal added in v0.4.0 

func (l *Unbuffered) Fatal(msg string, fields ...Fielder)

func (*Unbuffered) Info added in v0.4.0 

func (l *Unbuffered) Info(msg string, fields ...Fielder) Logger

func (*Unbuffered) Log added in v0.4.0 

func (l *Unbuffered) Log(level Level, msg string, fields ...Fielder) Logger

func (*Unbuffered) SetMinLevel added in v0.2.0 

func (l *Unbuffered) SetMinLevel(level Level) Logger

func (*Unbuffered) Transient added in v0.4.0 

func (l *Unbuffered) Transient(msg string, fields ...Fielder) Logger

func (*Unbuffered) Verbose added in v0.4.0 

func (l *Unbuffered) Verbose(msg string, fields ...Fielder) Logger

func (*Unbuffered) Warning added in v0.4.0 

func (l *Unbuffered) Warning(msg string, fields ...Fielder) Logger

Source Files

View all Source files

Directories

Path Synopsis
cmd
colortest command
example command
example2 command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.