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 Error(ctx context.Context, err error, a ...interface{})
• func Fatal(ctx context.Context, keyvals ...interface{})
• func Messagef(ctx context.Context, format string, a ...interface{})
• func RecoverAndLogError(ctx context.Context)
• func SetOutput(w io.Writer)
• func SetPrefix(keyval ...interface{})
• func Write(ctx context.Context, keyvals ...interface{})

Constants

const (
	KeyCaller   = "at"       // location of caller
	KeyTime     = "t"        // time of call
	KeyReqID    = "reqid"    // request ID from context
	KeyCoreID   = "coreid"   // core ID from context
	KeySubReqID = "subreqid" // potential sub-request ID from context

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

)

Conventional key names for log entries

Functions

func Error

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

Error writes 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 Fatal

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

Fatal is equivalent to Write() followed by a call to os.Exit(1).

func Messagef

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

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

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 output prefix.

func Write

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

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

Duplicate keys will be preserved.

Several fields are automatically added to the log entry: a timestamp, a string indicating the file and line number of the caller, and a request ID taken from the context.

As a special case, the auto-generated caller may be overridden by passing in a new value for the KeyCaller key as the first key-value pair. The override feature should be reserved for custom logging functions that wrap Write.

Write 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 []errors.StackFrame
• a KeyError value with type error, using the result of errors.Stack