log

Documentation

Overview

Package log defines the logging facade

A logger is composed of a formatter that serialises the log structure into a text line, and a log printer that outputs the formatted log lines.

Index

• func Err(ctx contextutil.ValueContext, tag, msg string, fields ...Field)
• func Trace(ctx contextutil.ValueContext, tag, msg string, fields ...Field)
• func Warn(ctx contextutil.ValueContext, tag, msg string, fields ...Field)
• func WithContext(ctx context.Context, l Logger) context.Context
• type Context
• type Field
  • func Base64(key string, val []byte) Field
  • func Bool(key string, val bool) Field
  • func Duration(key string, val time.Duration) Field
  • func Error(err error) Field
  • func Float64(key string, val float64) Field
  • func Int(key string, val int) Field
  • func Int64(key string, val int64) Field
  • func JoinFields(slices ...[]Field) []Field
  • func Nest(key string, fields ...Field) Field
  • func Object(key string, val interface{}) Field
  • func Ptr(key string, val interface{}) Field
  • func Skip() Field
  • func String(key string, val string) Field
  • func Stringer(key string, val fmt.Stringer) Field
  • func Time(key string, val time.Time) Field
  • func Type(key string, val interface{}) Field
  • func Uint(key string, val uint) Field
  • func Uint64(key string, val uint64) Field
  • func Uintptr(key string, val uintptr) Field
  • func (f Field) KV() (string, string)
• type Formatter
• type Level
  • func ParseLevel(s string) Level
  • func (l Level) String() string
• type Logger
  • func FromContext(ctx contextutil.ValueContext) Logger
  • func NopLogger() Logger
• type Printer

Functions

func Err

func Err(ctx contextutil.ValueContext, tag, msg string, fields ...Field)

Err calls `Error` on the context `Logger`

func Trace

func Trace(ctx contextutil.ValueContext, tag, msg string, fields ...Field)

Trace calls `Trace` on the context `Logger`

func Warn

func Warn(ctx contextutil.ValueContext, tag, msg string, fields ...Field)

Warn calls `Warning` on the context `Logger`

func WithContext

func WithContext(ctx context.Context, l Logger) context.Context

WithContext returns a copy of parent in which the `Logger` is stored

Types

type Context

type Context struct {
	Level     Level
	Timestamp time.Time
	Service   string
	// File name. Depending on the runtime environment, this
	// might be a simple name or a fully-qualified name.
	File string
	// Line within the source file. 1-based; 0 indicates no line number
	// available.
	Line int64
}

Context carries the log line context (level, timestamp, ...)

type Field

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

A Field is a marshaling operation used to add a key-value pair to a logger's context. Most fields are lazily marshaled, so it's inexpensive to add fields to disabled debug-level log statements.

func Base64

func Base64(key string, val []byte) Field

Base64 constructs a field that encodes the given value as a padded base64 string. The byte slice is converted to a base64 string eagerly.

func Bool

func Bool(key string, val bool) Field

Bool constructs a Field with the given key and value. Bools are marshaled lazily.

func Duration

func Duration(key string, val time.Duration) Field

Duration constructs a Field with the given key and value. It represents durations as an integer number of nanoseconds.

func Error

func Error(err error) Field

Error constructs a Field that lazily stores err.Error() under the key "error". If passed a nil error, the field is a no-op.

func Float64

func Float64(key string, val float64) Field

Float64 constructs a Field with the given key and value. The way the floating-point value is represented is encoder-dependent, so marshaling is necessarily lazy.

func Int

func Int(key string, val int) Field

Int constructs a Field with the given key and value. Marshaling ints is lazy.

func Int64

func Int64(key string, val int64) Field

Int64 constructs a Field with the given key and value. Like ints, int64s are marshaled lazily.

func JoinFields

func JoinFields(slices ...[]Field) []Field

JoinFields joins all slices into a single slice

func Nest

func Nest(key string, fields ...Field) Field

Nest takes a key and a variadic number of Fields and creates a nested namespace.

func Object

func Object(key string, val interface{}) Field

Object constructs a field with the given key and an arbitrary object. It uses an encoding-appropriate, reflection-based function to lazily serialize nearly any object into the logging context, but it's relatively slow and allocation-heavy.

If encoding fails (e.g., trying to serialize a map[int]string to JSON), Object includes the error message in the final log output.

func Ptr

func Ptr(key string, val interface{}) Field

func Skip

func Skip() Field

Skip constructs a no-op Field.

func String

func String(key string, val string) Field

String constructs a Field with the given key and value.

func Stringer

func Stringer(key string, val fmt.Stringer) Field

Stringer constructs a Field with the given key and the output of the value's String method. The Stringer's String method is called lazily.

func Time

func Time(key string, val time.Time) Field

Time constructs a Field with the given key and value. It represents a time.Time as a floating-point number of seconds since epoch. Conversion to a float64 happens eagerly.

func Type

func Type(key string, val interface{}) Field

func Uint

func Uint(key string, val uint) Field

Uint constructs a Field with the given key and value.

func Uint64

func Uint64(key string, val uint64) Field

Uint64 constructs a Field with the given key and value.

func Uintptr

func Uintptr(key string, val uintptr) Field

Uintptr constructs a Field with the given key and value.

func (Field) KV

func (f Field) KV() (string, string)

type Formatter

type Formatter interface {
	// Format formats the given log line
	Format(ctx *Context, tag, msg string, fields ...Field) (string, error)
}

Formatter converts a log line to a specific format, such as JSON

type Level

type Level int

Level defines log severity

const (
	// LevelTrace displays logs with trace level (and above)
	LevelTrace Level = iota
	// LevelWarning displays logs with warning level (and above)
	LevelWarning
	// LevelError displays only logs with error level
	LevelError
)

func ParseLevel

func ParseLevel(s string) Level

ParseLevel parses a string representation of a log level

func (Level) String

func (l Level) String() string

String returns a string representation of the given level

type Logger

type Logger interface {
	// Trace level logs are to follow the code executio step by step
	Trace(tag, msg string, fields ...Field)
	// Warning level logs are meant to draw attention above a certain threshold
	// e.g. wrong credentials, 404 status code returned, upstream node down
	Warning(tag, msg string, fields ...Field)
	// Error level logs need immediate attention
	// The 2AM rule applies here, which means that if you are on call, this log line will wake you up at 2AM
	// e.g. all critical upstream nodes are down, disk space is full
	Error(tag, msg string, fields ...Field)

	// With returns a child logger, and optionally add some context to that logger
	With(fields ...Field) Logger

	// AddCalldepth adds the given value to calldepth
	// Calldepth is the count of the number of
	// frames to skip when computing the file name and line number
	AddCalldepth(n int) Logger

	// Close implements the Closer interface
	Close() error
}

Logger is an interface for app loggers

func FromContext

func FromContext(ctx contextutil.ValueContext) Logger

FromContext returns a `Logger` instance associated with `ctx`, or `NopLogger` if no `Logger` instance could be found.

func NopLogger

func NopLogger() Logger

NopLogger returns a no-op `Logger`

type Printer

type Printer interface {
	// Print prints the given log line
	Print(ctx *Context, s string) error

	// Close implements the Closer interface
	Close() error
}

Printer outputs a log line somewhere, such as stdout, syslog, 3rd party service