frog

package module
v0.10.2 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2024 License: MIT Imports: 13 Imported by: 7

README

frog

Overview

Frog is a package for structured logging that is fast, easy to use, good looking, and customizable.

Frog includes:

  • Built-in support for plain text or JSON output.
  • Plain text output optinally supports ANSI colors per log level, including user-defined palettes.
  • Anchoring of log lines to the bottom of the terminal output, for progress bars and real-time status updates.
  • Detection of terminal/tty and disabling of ANSI/anchoring when none is found.
  • Nesting of Loggers to add fields, anchored lines, custom line rendering settings, and other custom behavior.
    • Each additional nested layer adds context without altering its parent(s).
  • User-customizable line rendering via the Printer interface.
  • Five log levels:
level description
Transient Output that is safe to ignore (like progress bars and estimated time remaining).
Verbose Output for debugging (disabled by default).
Info Normal events.
Warning Unusual events.
Error Something went wrong.

Anchoring

animated gif of anchoring in action

Anchors require an ANSI-compatible terminal connected to the output.

To add an anchored Logger, call frog.AddAnchor() and pass in an existing Logger, and it will return a Logger whose Transient log lines will target a newly created anchored line.

Behind the scenes, AddAnchor is looking to see if the given Logger or any of its ancestors implement the AnchorAdder interface. Currently Buffered is the only included Logger that supports anchors, and its AddAnchor returns an instance of AnchoredLogger that wraps the given Logger. If their is no Buffered/AnchorAdder in the ancestry, then it will use NoAnchorLogger instead.

Anchored lines are drawn to the terminal using ANSI escape codes for manipulating the cursor. Because the Buffered logger serializes logging from any number of goroutines, it provides a safe environment in which to manipulate cursor position temporarily, and to re-draw anchored lines as needed when they get blown away by non-Transient log lines.

Note that sending a Verbose, Info, Warning, or Error log line via an AnchoredLogger will not target the anchored line, but will log the results as if you had sent the log lines through the parent that was passed into frog.AddAnchor in the first place.

When you are done with an anchored line and wish to have it stop redrawing itself at the bottom of the output, just call frog.RemoveAnchor() on the logger that was returned from frog.AddAnchor. At that point you can keep using the logger if you wish, or discard it.

Calling RemoveAnchor is optional.

You are free to AddAnchor and RemoveAnchor at any time and in any order.

The code that generated the example shown output is here: cmd/anchors/main.go, but the core of what it is doing is:

func main() {
	log := frog.New(frog.Auto)
	defer log.Close()

	wg := new(sync.WaitGroup)
	wg.Add(3)
	for i := 0; i < 3; i++ {
		go func(log frog.Logger, n int) {
			defer wg.Done()
			defer frog.RemoveAnchor(log)
			for j := 0; j <= 100; j++ {
				log.Transient(" + Status", frog.Int("thread", n), frog.Int("percent", j))
				time.Sleep(time.Duration(50) * time.Millisecond)
			}
		}(frog.AddAnchor(log), i)
	}
	wg.Wait()
}

Note that frog.New(frog.Auto) automatically detects if a terminal is connected to the output, and if not, it turns off anchors. To see this in action, you can try piping the output of running the previous demo into a file. For example:

$ go run ./cmd/anchors/ -> out.txt && cat out.txt
2023.04.21-03:49:13 [nfo] Spawning example threads...   count=3
2023.04.21-03:49:15 [nfo] waited for one second...
2023.04.21-03:49:16 [WRN] waited for two seconds...
2023.04.21-03:49:17 [ERR] BORED OF WAITING
2023.04.21-03:49:19 [nfo] All threads done!

You can see that no ANSI escape sequences or transient log lines ended up in the resulting file.

Nesting

TODO: build nested loggers, then draw graph to illustrate the parent/child relationships that are formed

Windows compatibility

Frog uses ANSI/VT-100 commands to change colors and move the cursor, and for this to display properly, you must 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.

Windows Terminal also works great, but has problems with ANSI before the 1.17.1023 Preview build (released on Jan 1, 2023).

Usage

The quickest way to get started is to create one of the default Loggers via a call to frog.New. The parameter frog.Auto tells New to autodetect if there's a terminal on stdout, and if so, to enable support for colors and anchored lines. There are other default styles you can pass to New as well, like frog.Basic and frog.JSON. See the implementation of the New function in frog.go for details.

The JSON output from using 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 (e.g. filebeat).

TODO

  • handle dicritics in uicode on long transient lines
  • go doc pass
  • test on linux and mac
  • handle terminal width size changing while an app is running (for anchored lines)

Known Issues

  • When using anchored lines, if you resize the terminal to be narrowing than when frog was initialized, lines won't be properly cropped, and a long enough line could cause extra wrapping that would break the anchored line's ability to redraw itself. The result would be slightly garbled output. See the TODO in the previous section about this.
  • A single log line will print out all given fields, even if multiple fields use the same name. When outputting JSON, this can result in a JSON object that has multiple fields with the same name. This is not necessarily considered invalid, but it can result in ambiguous behavior.
    • Frog will output the field names in the same order as they are passed to Log/Transient/Verbose/Info/Warning/Error (even when outputting JSON).
    • When there are parent/child relationships, the fields are printed starting with the parent, and then each child's static fields (if any) are added in order as you traverse down, child to child. Any fields passed with the log line itself are added last.

Release Notes

0.9.5
  • Added Path and PathAbs fields ("path" and "path_abs", respectively).
    • PathAbs calls filepath.Abs(), which will have to touch the file system to do its work, so make sure you want that.
    • Both normalize path separators to '/'. This is still a valid path on Windows, and it avoids escaping '\' characters.
0.9.4
  • Fixed long standing issue where adding two anchors, removing the first, then adding a third, would result in the second and third anchors both updating the same line in the terminal, instead of two different lines.
0.9.3
  • Improved JSONPrinter performance by switching to StringBuilder
0.9.2
  • API BREAKING CHANGES
  • Changed frog.Palette from an enum to an array of frog.Color, which allows customizing colors used for each log level.
  • TextPrinter no longer exports any of its fields, and instead users should use the printer options, e.g. POPalette(...)
  • Logger interface changes:
    • Log() re-added, is just a passthrough to LogImpl
    • LogImpl() arguments re-ordered, and anchored line moved to new ImplData, which also handles min levels
  • Added NoAnchorLogger to ensure consistent nesting behavior when the RootLogger does not support anchors.
  • Removed the "buffered log closing" Debug log line that was previously sent when a Buffered Logger was closed.
0.9.0
  • API BREAKING CHANGES
  • Logger interface: removed Log(), added LogImpl().
    • It is likely the signature of LogImpl will change in the near future.
  • This is fallout from a large refactor to fix a bug when an AnchoredLogger wraps a CustomizerLogger
    • AnchoredLogger was written back when it was the only child logger, and it did dumb things like traverse up the parent chain until it found a Buffered, then set that as its parent (ignoring anything between it and the Buffered). Also it kept a copy of the Buffered's Printer.
    • Now all Loggers that wrap other loggers are expected to know their parent and pass through requests, making modifications as needed, until the request hits the root Logger. This is why LogImpl currently has the anchored line as a parameter. I hope to obfuscate this in the future.
  • Added an extra Customizer to the relevant tests, so going forward this case will be tested.
0.8.4
  • Handle anchored lines that are longer than the terminal width more gracefully
    • New behavior is that we detect the terminal width when frog comes up, then crops transient lines to that width
    • Can be manually set with printer option POTransientLineLength(len)
0.8.0
  • Re-worked printer options to be algebraic data types (see printeroptions.go and printer.go)
  • Allow overriding printer options per log line (see changes to the Printer's Render method and Logger's Log method).
  • frog.WithFields(parent, fields...) allows creating a logger that is a pass-through to parent, but always adds the specified fields to each log line.
  • frog.WithPrinterOptions(parent, opts...) allows creating a logger is a pass-through to parent, but always sets the specified PrinterOptions on each log line.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DarkPalette = Palette{
	{DarkGray, DarkGray},
	{DarkGray, DarkGray},
	{DarkGray, DarkGray},
	{DarkGray, DarkGray},
	{DarkGray, DarkGray},
}
View Source 
var DefaultPalette = Palette{
	{DarkGreen, DarkGray},
	{Cyan, DarkCyan},
	{White, LightGray},
	{Yellow, DarkYellow},
	{Red, DarkRed},
}
View Source 
var POFieldsLeftMsgRight poFieldsLeftMsgRight
View Source 
var POMsgLeftFieldsRight poMsgLeftFieldsRight

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 POFieldIndent added in v0.8.0 

func POFieldIndent(indent int) poFieldIndent

func POLevel added in v0.8.0 

func POLevel(visible bool) poLevel

func POTime added in v0.8.0 

func POTime(visible bool) poTime

func POTransientLineLength added in v0.8.4 

func POTransientLineLength(cols int) poTransientLineLength

func RemoveAnchor added in v0.7.1 

func RemoveAnchor(log Logger)

RemoveAnchor needs to be passed the logger that was returned by AddAnchor. It can also work by being passed a child of that Logger.

Types

type AnchorAdder added in v0.7.1 

type AnchorAdder interface {
	AddAnchor(parent Logger) Logger
}

AnchorAdder is the interface for loggers that support anchoring a line to the bottom of the output, for progress bars or other transient status messages.

type AnchorRemover added in v0.7.1 

type AnchorRemover interface {
	RemoveAnchor()
}

AnchorRemover is the interface that an anchor logger must implement in order for the anchor to be removed before app end.

type AnchoredLogger added in v0.7.1 

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

AnchoredLogger 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 (*AnchoredLogger) Error added in v0.7.1 

func (l *AnchoredLogger) Error(msg string, fielders ...Fielder) Logger

func (*AnchoredLogger) Info added in v0.7.1 

func (l *AnchoredLogger) Info(msg string, fielders ...Fielder) Logger

func (*AnchoredLogger) Log added in v0.7.1 

func (l *AnchoredLogger) Log(level Level, msg string, fielders ...Fielder) Logger

func (*AnchoredLogger) LogImpl added in v0.9.0 

func (l *AnchoredLogger) LogImpl(level Level, msg string, fielders []Fielder, opts []PrinterOption, d ImplData)

func (*AnchoredLogger) MinLevel added in v0.9.2 

func (l *AnchoredLogger) MinLevel() Level

func (*AnchoredLogger) Parent added in v0.7.1 

func (l *AnchoredLogger) Parent() Logger

func (*AnchoredLogger) RemoveAnchor added in v0.7.1 

func (l *AnchoredLogger) RemoveAnchor()

func (*AnchoredLogger) SetMinLevel added in v0.7.1 

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

func (*AnchoredLogger) Transient added in v0.7.1 

func (l *AnchoredLogger) Transient(msg string, fielders ...Fielder) Logger

func (*AnchoredLogger) Verbose added in v0.7.1 

func (l *AnchoredLogger) Verbose(msg string, fielders ...Fielder) Logger

func (*AnchoredLogger) Warning added in v0.7.1 

func (l *AnchoredLogger) Warning(msg string, fielders ...Fielder) Logger

type Buffered 

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

func NewBuffered 

func NewBuffered(writer io.Writer, requestTerminalSize bool, prn Printer) *Buffered

func (*Buffered) AddAnchor added in v0.7.1 

func (l *Buffered) AddAnchor(parent Logger) Logger

AddAnchor creates a Logger that is "achored" to the bottom of the output. This "anchoring" is achieved by using ANSI to re-draw the anchored line at the bottom as the output scrolls up. 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(msg string, fielders ...Fielder) Logger

func (*Buffered) Info added in v0.4.0 

func (l *Buffered) Info(msg string, fielders ...Fielder) Logger

func (*Buffered) Log added in v0.4.0 

func (l *Buffered) Log(level Level, msg string, fielders ...Fielder) Logger

func (*Buffered) LogImpl added in v0.9.0 

func (l *Buffered) LogImpl(level Level, msg string, fielders []Fielder, opts []PrinterOption, d ImplData)

func (*Buffered) MinLevel 

func (l *Buffered) MinLevel() Level

func (*Buffered) SetMinLevel 

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

func (*Buffered) Transient added in v0.4.0 

func (l *Buffered) Transient(msg string, fielders ...Fielder) Logger

func (*Buffered) Verbose added in v0.4.0 

func (l *Buffered) Verbose(msg string, fielders ...Fielder) Logger

func (*Buffered) Warning added in v0.4.0 

func (l *Buffered) Warning(msg string, fielders ...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 Color added in v0.6.0 

type Color byte

Color is the public interface to the underlying ANSI colors. 

const (
	Black Color = iota
	DarkRed
	DarkGreen
	DarkYellow
	DarkBlue
	DarkMagenta
	DarkCyan
	LightGray
	DarkGray
	Red
	Green
	Yellow
	Blue
	Magenta
	Cyan
	White
)

type CustomizerLogger added in v0.8.0 

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

CustomizerLogger is a Logger that adds specific fields and/or sets specific printer options for each line it logs

func (*CustomizerLogger) Error added in v0.8.0 

func (l *CustomizerLogger) Error(msg string, fielders ...Fielder) Logger

func (*CustomizerLogger) Info added in v0.8.0 

func (l *CustomizerLogger) Info(msg string, fielders ...Fielder) Logger

func (*CustomizerLogger) Log added in v0.8.0 

func (l *CustomizerLogger) Log(level Level, msg string, fielders ...Fielder) Logger

func (*CustomizerLogger) LogImpl added in v0.9.0 

func (l *CustomizerLogger) LogImpl(level Level, msg string, fielders []Fielder, opts []PrinterOption, d ImplData)

func (*CustomizerLogger) MinLevel added in v0.9.2 

func (l *CustomizerLogger) MinLevel() Level

func (*CustomizerLogger) Parent added in v0.8.0 

func (l *CustomizerLogger) Parent() Logger

func (*CustomizerLogger) SetMinLevel added in v0.8.0 

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

func (*CustomizerLogger) Transient added in v0.8.0 

func (l *CustomizerLogger) Transient(msg string, fielders ...Fielder) Logger

func (*CustomizerLogger) Verbose added in v0.8.0 

func (l *CustomizerLogger) Verbose(msg string, fielders ...Fielder) Logger

func (*CustomizerLogger) Warning added in v0.8.0 

func (l *CustomizerLogger) Warning(msg string, fielders ...Fielder) Logger

type Field added in v0.4.0 

type Field struct {
	Name         string
	Value        string
	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
}

func Fieldify added in v0.9.3 

func Fieldify(f []Fielder) []Field

Fieldify takes a slice of Fielders and calls Field() on each, resulting in a slice of Fields

func FieldifyAndAppend added in v0.9.3 

func FieldifyAndAppend(fields []Field, fielders []Fielder) []Field

FieldifyAndAppend returns a slice of Fields that starts with a copy the passed in []Field, and then appends the passed in []Fielder, after first rendering them to Fields.

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 FieldFloat32 added in v0.9.3 

type FieldFloat32 struct {
	Name  string
	Value float32
}

func Float32 added in v0.4.0 

func Float32(name string, value float32) FieldFloat32

Float32 adds a 32-bit floating point number field

func (FieldFloat32) Field added in v0.9.3 

func (f FieldFloat32) Field() Field

type FieldFloat64 added in v0.4.0 

type FieldFloat64 struct {
	Name  string
	Value float64
}

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 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 Int8 added in v0.4.0 

func Int8(name string, value int8) FieldInt64

Int8 adds an 8-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 Path added in v0.9.5 

func Path(path string) FieldString

Path adds a field named "path" with the value of the passed in path, with '/' as the path separator ('/' is valid on Windows, and avoids escaping '\\' characters)

func PathAbs added in v0.9.5 

func PathAbs(path string) FieldString

PathAbs adds a field named "path_abs" that contains the result of passing the given path to filepath.Abs(). Similar to Path, '/' is used as the path separator.

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
}

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 (FieldTimeUnix) Field added in v0.4.0 

func (f FieldTimeUnix) Field() Field

type FieldTimeUnixNano added in v0.9.3 

type FieldTimeUnixNano struct {
	Name  string
	Value time.Time
}

func TimeUnixNano added in v0.4.0 

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

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

func (FieldTimeUnixNano) Field added in v0.9.3 

func (f FieldTimeUnixNano) 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 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 Uint8 added in v0.4.0 

func Uint8(name string, value uint8) FieldUint64

Uint8 adds an 8-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 ImplData added in v0.9.2 

type ImplData struct {
	// AnchoredLine should be 0 to indicate no anchor, or any number > 0 to uniquely identify a given
	// anchored line
	AnchoredLine int32

	// MinLevel is passed up to the RootLogger, where it is used to decide if this message should be
	// processed or not.
	// Each child that is passed this MinLevel should update it (e.g. via MergeMinLevel) to be the
	// max of the passed MinLevel and its own internal MinLevel.
	MinLevel Level

	// Fields holds Fielders that have already been turned into Fields. This is used by
	// CustomizerLoggers to cache the fields that will be included with every log message.
	Fields []Field
}

ImplData is additional data required to pass from child to parent in order for advanced features like anchoirng to function properly.

func (*ImplData) MergeFields added in v0.9.3 

func (d *ImplData) MergeFields(fields []Field)

MergeFields adds any passed in fields before the existing fields

func (*ImplData) MergeMinLevel added in v0.9.2 

func (d *ImplData) MergeMinLevel(min Level)

MergeMinLevel sets MinLevel to the max of its own MinLevel and the passed in Level.

type JSONPrinter added in v0.2.1 

type JSONPrinter struct {
	TimeOverride time.Time // TODO: only tests use this currently, can we instead support POTime for tests?
}

func (*JSONPrinter) Render added in v0.2.1 

func (p *JSONPrinter) Render(level Level, opts []PrinterOption, msg string, fields []Field) string

func (*JSONPrinter) SetOptions added in v0.8.0 

func (p *JSONPrinter) SetOptions(opts ...PrinterOption) Printer

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

)

func (Level) String added in v0.2.1 

func (l Level) String() string

type Logger 

type Logger interface {
	// MinLevel gets the minimum level that is filtered by this Logger instance.
	// If this Logger is part of a chain of nested Loggers, note that that this only returns the min
	// level of this link in the chain. This Logger's parents may have more restrictive min levels
	// that prevent log lines from being displayed.
	MinLevel() Level
	// SetMinLevel sets the lowest Level that will be accepted by this Logger.
	// If this Logger has parent(s), the effective MinLevel will be the max of each logger's min level.
	SetMinLevel(level Level) Logger

	// Transient logs a string (with optional fielders) with the log level set to Transient.
	Transient(msg string, fielders ...Fielder) Logger
	// Verbose logs a string (with optional fielders) with the log level set to Verbose.
	Verbose(msg string, fielders ...Fielder) Logger
	// Info logs a string (with optional fielders) with the log level set to Info.
	Info(msg string, fielders ...Fielder) Logger
	// Warning logs a string (with optional fielders) with the log level set to Warning.
	Warning(msg string, fielders ...Fielder) Logger
	// Error logs a string (with optional fielders) with the log level set to Error.
	Error(msg string, fielders ...Fielder) Logger
	// Log logs a string (with optional fielders) with the log level set to the passed in value.
	Log(level Level, msg string, fielders ...Fielder) Logger

	// LogImpl is called by children to pass up log events to the root Logger.
	LogImpl(level Level, msg string, fielders []Fielder, opts []PrinterOption, d ImplData)
}

func AddAnchor added in v0.7.1 

func AddAnchor(log Logger) Logger

AddAnchor adds a new logger on an anchored line (if supported). Else, returns passed in Logger.

func Parent added in v0.2.0 

func Parent(log Logger) Logger

func WithFields added in v0.8.0 

func WithFields(log Logger, fielders ...Fielder) Logger

WithFields creates a new Logger that wraps the parent logger, adding the specified fields when the returned Logger is used, but leaving the parent unmodified.

func WithOptions added in v0.8.0 

func WithOptions(log Logger, opts ...PrinterOption) Logger

WithOptions creates a new Logger that wraps the passed Logger, adding the specified PrinterOptions when the returned Logger is used, but leaving the parent unmodified.

func WithOptionsAndFields added in v0.8.0 

func WithOptionsAndFields(log Logger, opts []PrinterOption, fielders []Fielder) Logger

WithOptionsAndFields creates a new Logger that wraps the passed Logger, adding the specified fields and PrinterOptions when the return Logger is used, but leaving the parent unmodified.

type NewLogger added in v0.2.0 

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

type NoAnchorLogger added in v0.9.2 

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

NoAnchorLogger is a Logger that is returned from AddAnchor when the RootLogger doesn't support anchors. NoAnchorLogger allows changing the min level, just like an AnchorLogger, but otherwise does nothing but pass through to the parent.

func (*NoAnchorLogger) Error added in v0.9.2 

func (l *NoAnchorLogger) Error(msg string, fielders ...Fielder) Logger

func (*NoAnchorLogger) Info added in v0.9.2 

func (l *NoAnchorLogger) Info(msg string, fielders ...Fielder) Logger

func (*NoAnchorLogger) Log added in v0.9.2 

func (l *NoAnchorLogger) Log(level Level, msg string, fielders ...Fielder) Logger

func (*NoAnchorLogger) LogImpl added in v0.9.2 

func (l *NoAnchorLogger) LogImpl(level Level, msg string, fielders []Fielder, opts []PrinterOption, d ImplData)

func (*NoAnchorLogger) MinLevel added in v0.9.2 

func (l *NoAnchorLogger) MinLevel() Level

func (*NoAnchorLogger) Parent added in v0.9.2 

func (l *NoAnchorLogger) Parent() Logger

func (*NoAnchorLogger) RemoveAnchor added in v0.9.2 

func (l *NoAnchorLogger) RemoveAnchor()

func (*NoAnchorLogger) SetMinLevel added in v0.9.2 

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

func (*NoAnchorLogger) Transient added in v0.9.2 

func (l *NoAnchorLogger) Transient(msg string, fielders ...Fielder) Logger

func (*NoAnchorLogger) Verbose added in v0.9.2 

func (l *NoAnchorLogger) Verbose(msg string, fielders ...Fielder) Logger

func (*NoAnchorLogger) Warning added in v0.9.2 

func (l *NoAnchorLogger) Warning(msg string, fielders ...Fielder) Logger

type NullLogger added in v0.6.0 

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

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, fielders ...Fielder) Logger

func (*NullLogger) Info added in v0.6.0 

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

func (*NullLogger) Log added in v0.6.0 

func (n *NullLogger) Log(level Level, msg string, fielders ...Fielder) Logger

func (*NullLogger) LogImpl added in v0.9.0 

func (n *NullLogger) LogImpl(level Level, msg string, fielders []Fielder, opts []PrinterOption, d ImplData)

func (*NullLogger) MinLevel added in v0.9.2 

func (n *NullLogger) MinLevel() Level

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, fielders ...Fielder) Logger

func (*NullLogger) Verbose added in v0.6.0 

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

func (*NullLogger) Warning added in v0.6.0 

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

type Palette added in v0.8.0 

type Palette [levelMax][2]Color

Palette is the primary (0) and secondary (1) colors for each log level

type Printer 

type Printer interface {
	Render(Level, []PrinterOption, string, []Field) string
	SetOptions(...PrinterOption) Printer
}

type PrinterOption added in v0.8.0 

type PrinterOption interface {
	String() string
	// contains filtered or unexported methods
}

func POPalette added in v0.8.0 

func POPalette(p Palette) PrinterOption

type RootLogger added in v0.9.2 

type RootLogger interface {
	Logger

	// 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()
}

func New 

func New(t NewLogger, opts ...PrinterOption) RootLogger

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 anchored lines are supported (else, uses Basic) - Basic - no colors or anchored lines, no buffering - JSON - no colors or anchored 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.

type TeeLogger added in v0.2.0 

type TeeLogger struct {
	Primary   Logger // Anchors are only supported though this logger
	Secondary Logger
	// contains filtered or unexported fields
}

TeeLogger directs all traffic to both a primary and secondary logger Note that of if one of your loggers supports anchor, make sure that is the Primary anchor.

func NewRootTee added in v0.9.2 

func NewRootTee(a RootLogger, b RootLogger) (*TeeLogger, func())

func (*TeeLogger) Error added in v0.4.0 

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

func (*TeeLogger) Info added in v0.4.0 

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

func (*TeeLogger) Log added in v0.4.0 

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

func (*TeeLogger) LogImpl added in v0.9.0 

func (l *TeeLogger) LogImpl(level Level, msg string, fielders []Fielder, opts []PrinterOption, d ImplData)

func (*TeeLogger) MinLevel added in v0.9.2 

func (n *TeeLogger) MinLevel() Level

func (*TeeLogger) Parent added in v0.9.0 

func (l *TeeLogger) Parent() Logger

func (*TeeLogger) SetMinLevel added in v0.2.0 

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

func (*TeeLogger) Transient added in v0.4.0 

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

func (*TeeLogger) Verbose added in v0.4.0 

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

func (*TeeLogger) Warning added in v0.4.0 

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

type TextPrinter added in v0.2.1 

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

func (*TextPrinter) Render added in v0.2.1 

func (p *TextPrinter) Render(level Level, opts []PrinterOption, msg string, fields []Field) string

func (*TextPrinter) SetOptions added in v0.8.0 

func (p *TextPrinter) SetOptions(opts ...PrinterOption) Printer

type Unbuffered added in v0.2.0 

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

func NewUnbuffered added in v0.2.0 

func NewUnbuffered(writer io.Writer, 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, fielders ...Fielder) Logger

func (*Unbuffered) Info added in v0.4.0 

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

func (*Unbuffered) Log added in v0.4.0 

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

func (*Unbuffered) LogImpl added in v0.9.0 

func (l *Unbuffered) LogImpl(level Level, msg string, fielders []Fielder, opts []PrinterOption, d ImplData)

func (*Unbuffered) MinLevel added in v0.9.2 

func (l *Unbuffered) MinLevel() Level

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, fielders ...Fielder) Logger

func (*Unbuffered) Verbose added in v0.4.0 

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

func (*Unbuffered) Warning added in v0.4.0 

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

Source Files

View all Source files

Directories

Path Synopsis
cmd
anchors
colortest
demo
lengthtest
sizetest
internal
terminal

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.