logging

Documentation

Index

• Variables
• func LeveledFormatterGlog(file string, line int, ts time.Time, severity Severity, msg string) string
• type FunctionBackend
  • func NewFunctionBackend(fn func(severity Severity, msg string)) *FunctionBackend
  • func (w *FunctionBackend) Error(args ...any)
  • func (w *FunctionBackend) Errorf(format string, args ...any)
  • func (w *FunctionBackend) Fatal(args ...any)
  • func (w *FunctionBackend) Fatalf(format string, args ...any)
  • func (w *FunctionBackend) Info(args ...any)
  • func (w FunctionBackend) Infof(format string, args ...any)
  • func (w *FunctionBackend) V(level VerbosityLevel) VerboseLeveled
  • func (w *FunctionBackend) Warning(args ...any)
  • func (w *FunctionBackend) Warningf(format string, args ...any)
  • func (w *FunctionBackend) WithAddedStackDepth(depth int) Leveled
• type Leveled
• type LeveledFormatter
• type Severity
  • func (s Severity) AtLeast(other Severity) bool
  • func (s Severity) Valid() bool
• type VerboseLeveled
• type VerbosityLevel
• type WriterBackend
  • func NewWriterBackend(w io.Writer) *WriterBackend

Variables

var (
	// SeverityAtLeast maps a given severity to a list of severities that at that
	// severity or higher. In other words, SeverityAtLeast[X] returns a list of
	// severities that might be seen in a log at severity X.
	SeverityAtLeast = map[Severity][]Severity{
		INFO:    {INFO, WARNING, ERROR, FATAL},
		WARNING: {WARNING, ERROR, FATAL},
		ERROR:   {ERROR, FATAL},
		FATAL:   {FATAL},
	}
)

Functions

func LeveledFormatterGlog

func LeveledFormatterGlog(file string, line int, ts time.Time, severity Severity, msg string) string

LeveledFormatterGlog implements LeveledFormatter in a glog/klog-compatible way.

Types

type FunctionBackend

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

FunctionBackend is the simplest Backend (Leveled implementation). It synchronously forwards logged entries to a function.

func NewFunctionBackend

func NewFunctionBackend(fn func(severity Severity, msg string)) *FunctionBackend

NewFunctionBackend returns a FunctionBackend (Leveled implementation) which will call the given function on every log entry synchronously.

func (*FunctionBackend) Error

func (w *FunctionBackend) Error(args ...any)

func (*FunctionBackend) Errorf

func (w *FunctionBackend) Errorf(format string, args ...any)

func (*FunctionBackend) Fatal

func (w *FunctionBackend) Fatal(args ...any)

func (*FunctionBackend) Fatalf

func (w *FunctionBackend) Fatalf(format string, args ...any)

func (*FunctionBackend) Info

func (w *FunctionBackend) Info(args ...any)

func (FunctionBackend) Infof

func (w FunctionBackend) Infof(format string, args ...any)

func (*FunctionBackend) V

func (w *FunctionBackend) V(level VerbosityLevel) VerboseLeveled

func (*FunctionBackend) Warning

func (w *FunctionBackend) Warning(args ...any)

func (*FunctionBackend) Warningf

func (w *FunctionBackend) Warningf(format string, args ...any)

func (*FunctionBackend) WithAddedStackDepth

func (w *FunctionBackend) WithAddedStackDepth(depth int) Leveled

type Leveled

type Leveled interface {
	// Info logs at the INFO severity. Arguments are handled in the manner of
	// fmt.Print, a terminating newline is added if missing.
	Info(args ...any)
	// Infof logs at the INFO severity. Arguments are handled in the manner of
	// fmt.Printf, a terminating newline is added if missing.
	Infof(format string, args ...any)

	// Warning logs at the WARNING severity. Arguments are handled in the manner of
	// fmt.Print, a terminating newline is added if missing.
	Warning(args ...any)
	// Warningf logs at the WARNING severity. Arguments are handled in the manner of
	// fmt.Printf, a terminating newline is added if missing.
	Warningf(format string, args ...any)

	// Error logs at the ERROR severity. Arguments are handled in the manner of
	// fmt.Print, a terminating newline is added if missing.
	Error(args ...any)
	// Errorf logs at the ERROR severity. Arguments are handled in the manner of
	// fmt.Printf, a terminating newline is added if missing.
	Errorf(format string, args ...any)

	// Fatal logs at the FATAL severity and aborts the current program. Arguments are
	// handled in the manner of fmt.Print, a terminating newline is added if missing.
	Fatal(args ...any)
	// Fatalf logs at the FATAL severity and aborts the current program. Arguments are
	// handled in the manner of fmt.Printf, a terminating newline is added if missing.
	Fatalf(format string, args ...any)

	// V returns a VerboseLeveledLogger at a given verbosity level. These verbosity
	// levels can be dynamically set and unset on a package-granular level by consumers
	// of the LeveledLogger logs. The returned value represents whether logging at the
	// given verbosity level was active at that time, and as such should not be a long-
	// lived object in programs. This construct is further refered to as 'V-logs'.
	V(level VerbosityLevel) VerboseLeveled

	// WithAddedStackDepth returns the same LeveledLogger, but adjusted with an
	// additional 'extra stack depth' which will be used to skip a given number of
	// stack/call frames when determining the location where the error originated.
	// For example, WithStackDepth(1) will return a logger that will skip one
	// stack/call frame. Then, with function foo() calling function helper() which
	// in turns call l.Infof(), the log line will be emitted with the call site of
	// helper() within foo(), instead of the default behaviour of logging the
	// call site of Infof() within helper().
	//
	// This is useful for functions which somehow wrap loggers in helper functions,
	// for example to expose a slightly different API.
	WithAddedStackDepth(depth int) Leveled
}

Leveled is a generic interface for glog-style logging. There are four hardcoded log severities, in increasing order: INFO, WARNING, ERROR, FATAL. Logging at a certain severity level logs not only to consumers expecting data at that severity level, but also all lower severity levels. For example, an ERROR log will also be passed to consumers looking at INFO or WARNING logs.

type LeveledFormatter

type LeveledFormatter func(file string, line int, time time.Time, severity Severity, msg string) string

LeveledFormatter is a function to turn a leveled log entry into a string which can be output to a user.

type Severity

type Severity string

Severity is one of the severities as described in LeveledLogger.

const (
	INFO    Severity = "I"
	WARNING Severity = "W"
	ERROR   Severity = "E"
	FATAL   Severity = "F"
)

func (Severity) AtLeast

func (s Severity) AtLeast(other Severity) bool

func (Severity) Valid

func (s Severity) Valid() bool

Valid returns whether true if this severity is one of the known levels (INFO, WARNING, ERROR or FATAL), false otherwise.

type VerboseLeveled

type VerboseLeveled interface {
	// Enabled returns if this level was enabled. If not enabled, all logging into this
	// logger will be discarded immediately. Thus, Enabled() can be used to check the
	// verbosity level before performing any logging:
	//    if l.V(3).Enabled() { l.Info("V3 is enabled") }
	// or, in simple cases, the convenience function .Info can be used:
	//    l.V(3).Info("V3 is enabled")
	// The second form is shorter and more convenient, but more expensive, as its
	// arguments are always evaluated.
	Enabled() bool
	// Info is the equivalent of a LeveledLogger's Info call, guarded by whether this
	// VerboseLeveledLogger is enabled.
	Info(args ...any)
	// Infof is the equivalent of a LeveledLogger's Infof call, guarded by whether this
	// VerboseLeveledLogger is enabled.
	Infof(format string, args ...any)
}

type VerbosityLevel

type VerbosityLevel int32

VerbosityLevel is a verbosity level defined for V-logs. This can be changed programmatically per Go package. When logging at a given VerbosityLevel V, the current level must be equal or higher to V for the logs to be recorded. Conversely, enabling a V-logging at a VerbosityLevel V also enables all logging at lower levels [Int32Min .. (V-1)].

type WriterBackend

type WriterBackend struct {
	FunctionBackend
	// Formatter is used to turn a log entry alongside metadata into a string. By
	// default, it's set to LeveledFormatterGlog.
	Formatter LeveledFormatter

	MinimumSeverity Severity
	// contains filtered or unexported fields
}

WriterBackend is a Backend (Leveled implementation) which outputs log entries to a writer using a given Formatter.

func NewWriterBackend

func NewWriterBackend(w io.Writer) *WriterBackend

NewWriterBackend constructs a WriterBackend (Leveled implementation) which writes glog/klog-style entries to the given Writer.