log

Documentation

Overview

Package log implements a standard convention for structured logging. Log entries are formatted as K=V pairs. By default, output is written to stdout; this can be changed with SetOutput.

Index

• Constants
• func AddPrefixkv(ctx context.Context, keyval ...interface{}) context.Context
• func Error(ctx context.Context, err error, a ...interface{})
• func Fatalkv(ctx context.Context, keyvals ...interface{})
• func Printf(ctx context.Context, format string, a ...interface{})
• func Printkv(ctx context.Context, keyvals ...interface{})
• func RecoverAndLogError(ctx context.Context)
• func SetOutput(w io.Writer)
• func SetPrefix(keyval ...interface{})
• func SkipFunc(name string)

Constants

const (
	KeyCaller = "at" // location of caller
	KeyTime   = "t"  // time of call

	KeyMessage = "message" // produced by Message
	KeyError   = "error"   // produced by Error
	KeyStack   = "stack"   // used by Printkv to print stack on subsequent lines

)

Conventional key names for log entries

Functions

func AddPrefixkv

func AddPrefixkv(ctx context.Context, keyval ...interface{}) context.Context

AddPrefixkv appends keyval to any prefix stored in ctx, and returns a new context with the longer prefix.

func Error

func Error(ctx context.Context, err error, a ...interface{})

Error prints a log entry containing an error message assigned to the "error" key. Optionally, an error message prefix can be included. Prefix arguments are handled as in fmt.Print.

func Fatalkv

func Fatalkv(ctx context.Context, keyvals ...interface{})

Fatalkv is equivalent to Printkv() followed by a call to os.Exit(1).

func Printf

func Printf(ctx context.Context, format string, a ...interface{})

Printf prints a log entry containing a message assigned to the "message" key. Arguments are handled as in fmt.Printf.

func Printkv

func Printkv(ctx context.Context, keyvals ...interface{})

Printkv prints a structured log entry to stdout. Log fields are specified as a variadic sequence of alternating keys and values.

Duplicate keys will be preserved.

Two fields are automatically added to the log entry: t=[time] and at=[file:line] indicating the location of the caller. Use SkipFunc to prevent helper functions from showing up in the at=[file:line] field.

Printkv will also print the stack trace, if any, on separate lines following the message. The stack is obtained from the following, in order of preference:

• a KeyStack value with type []byte or *runtime.Frames
• a KeyError value with type error, using the result of errors.Stack

func RecoverAndLogError

func RecoverAndLogError(ctx context.Context)

RecoverAndLogError must be used inside a defer.

func SetOutput

func SetOutput(w io.Writer)

SetOutput sets the log output to w. If SetOutput hasn't been called, the default behavior is to write to stdout.

func SetPrefix

func SetPrefix(keyval ...interface{})

SetPrefix sets the global output prefix.

func SkipFunc

func SkipFunc(name string)

SkipFunc removes the named function from stack traces and at=[file:line] entries printed to the log output. The provided name should be a fully-qualified function name comprising the import path and identifier separated by a dot. For example, chain/log.Printkv. SkipFunc must not be called concurrently with any function in this package (including itself).