log

README

package log

package log provides a minimal interface for structured logging in services. It may be wrapped to encode conventions, enforce type-safety, etc. It can be used for both typical application log events, and log-structured data streams.

Rationale

TODO

Usage

Typical application logging.

import "github.com/go-kit/kit/log"

func main() {
	logger := log.NewPrefixLogger(os.Stderr)
	logger.Log("question", "what is the meaning of life?", "answer", 42)
}

Contextual logging.

func handle(logger log.Logger, req *Request) {
	logger = log.With(logger, "txid", req.TransactionID, "query", req.Query)
	logger.Log()

	answer, err := process(logger, req.Query)
	if err != nil {
		logger.Log("err", err)
		return
	}

	logger.Log("answer", answer)
}

Redirect stdlib log to gokit logger.

import (
	"os"
	stdlog "log"
	kitlog "github.com/go-kit/kit/log"
)

func main() {
	logger := kitlog.NewJSONLogger(os.Stdout)
	stdlog.SetOutput(kitlog.NewStdlibAdapter(logger))
}

Documentation

Overview

Package log provides basic interfaces for structured logging.

The fundamental interface is Logger. Loggers create log events from key/value data.

Index

• Variables
• func NewStdlibAdapter(logger Logger, options ...StdlibAdapterOption) io.Writer
• type LevelOption
  • func DebugLevelValue(value string) LevelOption
  • func ErrorLevelValue(value string) LevelOption
  • func InfoLevelValue(value string) LevelOption
  • func LevelKey(key string) LevelOption
• type Levels
  • func NewLevels(base Logger, options ...LevelOption) Levels
• type Logger
  • func NewJSONLogger(w io.Writer) Logger
  • func NewLogfmtLogger(w io.Writer) Logger
  • func With(logger Logger, keyvals ...interface{}) Logger
• type LoggerFunc
  • func (f LoggerFunc) Log(keyvals ...interface{}) error
• type StdlibAdapter
  • func (a StdlibAdapter) Write(p []byte) (int, error)
• type StdlibAdapterOption
  • func FileKey(key string) StdlibAdapterOption
  • func MessageKey(key string) StdlibAdapterOption
  • func TimestampKey(key string) StdlibAdapterOption
• type StdlibWriter
  • func (w StdlibWriter) Write(p []byte) (int, error)
• type SwapLogger
  • func (l *SwapLogger) Log(keyvals ...interface{}) error
  • func (l *SwapLogger) Swap(logger Logger)
• type Valuer
  • func Caller(depth int) Valuer
  • func Timestamp(t func() time.Time) Valuer

Variables

var (
	// DefaultCaller is a Valuer that returns the file and line where the Log
	// method was invoked. It can only be used with log.With.
	DefaultCaller = Caller(3)
)

Functions

func NewStdlibAdapter

func NewStdlibAdapter(logger Logger, options ...StdlibAdapterOption) io.Writer

NewStdlibAdapter returns a new StdlibAdapter wrapper around the passed logger. It's designed to be passed to log.SetOutput.

Types

type LevelOption

type LevelOption func(*levelOptions)

LevelOption sets a parameter for leveled loggers.

func DebugLevelValue

func DebugLevelValue(value string) LevelOption

DebugLevelValue sets the value for the field used to indicate the debug log level. By default, the value is "DEBUG".

func ErrorLevelValue

func ErrorLevelValue(value string) LevelOption

ErrorLevelValue sets the value for the field used to indicate the debug log level. By default, the value is "ERROR".

func InfoLevelValue

func InfoLevelValue(value string) LevelOption

InfoLevelValue sets the value for the field used to indicate the debug log level. By default, the value is "INFO".

func LevelKey

func LevelKey(key string) LevelOption

LevelKey sets the key for the field used to indicate log level. By default, the key is "level".

type Levels

type Levels struct {
	Debug Logger
	Info  Logger
	Error Logger
}

Levels provides a default set of leveled loggers.

func NewLevels

func NewLevels(base Logger, options ...LevelOption) Levels

NewLevels returns a new set of leveled loggers based on the base logger.

type Logger

type Logger interface {
	Log(keyvals ...interface{}) error
}

Logger is the fundamental interface for all log operations. Implementations must be safe for concurrent use by multiple goroutines. Log creates a log event from keyvals, a variadic sequence of alternating keys and values.

func NewJSONLogger

func NewJSONLogger(w io.Writer) Logger

NewJSONLogger returns a Logger that encodes keyvals to the Writer as a single JSON object.

func NewLogfmtLogger

func NewLogfmtLogger(w io.Writer) Logger

NewLogfmtLogger returns a logger that encodes keyvals to the Writer in logfmt format. The passed Writer must be safe for concurrent use by multiple goroutines if the returned Logger will be used concurrently.

func With

func With(logger Logger, keyvals ...interface{}) Logger

With returns a new Logger that includes keyvals in all log events. The returned Logger replaces all value elements (odd indexes) containing a Valuer with their generated value for each call to its Log method.

type LoggerFunc

type LoggerFunc func(...interface{}) error

LoggerFunc is an adapter to allow use of ordinary functions as Loggers. If f is a function with the appropriate signature, LoggerFunc(f) is a Logger object that calls f.

func (LoggerFunc) Log

func (f LoggerFunc) Log(keyvals ...interface{}) error

Log implements Logger by calling f(keyvals...).

type StdlibAdapter

type StdlibAdapter struct {
	Logger
	// contains filtered or unexported fields
}

StdlibAdapter wraps a Logger and allows it to be passed to the stdlib logger's SetOutput. It will extract date/timestamps, filenames, and messages, and place them under relevant keys.

func (StdlibAdapter) Write

func (a StdlibAdapter) Write(p []byte) (int, error)

type StdlibAdapterOption

type StdlibAdapterOption func(*StdlibAdapter)

StdlibAdapterOption sets a parameter for the StdlibAdapter.

func FileKey

func FileKey(key string) StdlibAdapterOption

FileKey sets the key for the file and line field. By default, it's "file".

func MessageKey

func MessageKey(key string) StdlibAdapterOption

MessageKey sets the key for the actual log message. By default, it's "msg".

func TimestampKey

func TimestampKey(key string) StdlibAdapterOption

TimestampKey sets the key for the timestamp field. By default, it's "ts".

type StdlibWriter

type StdlibWriter struct{}

StdlibWriter implements io.Writer by invoking the stdlib log.Print. It's designed to be passed to a gokit logger as the writer, for cases where it's necessary to redirect all gokit log output to the stdlib logger.

If you have any choice in the matter, you shouldn't use this. Prefer to redirect the stdlib log to the gokit logger via NewStdlibAdapter.

func (StdlibWriter) Write

func (w StdlibWriter) Write(p []byte) (int, error)

Write implements io.Writer.

type SwapLogger

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

SwapLogger wraps another logger that may be safely replaced while other goroutines use the SwapLogger concurrently. The zero value for a SwapLogger will discard all log events without error.

SwapLogger serves well as a package global logger that can be changed by importers.

func (*SwapLogger) Log

func (l *SwapLogger) Log(keyvals ...interface{}) error

Log implements the Logger interface by forwarding keyvals to the currently wrapped logger. It does not log anything if the wrapped logger is nil.

func (*SwapLogger) Swap

func (l *SwapLogger) Swap(logger Logger)

Swap replaces the currently wrapped logger with logger. Swap may be called concurrently with calls to Log from other goroutines.

type Valuer

type Valuer func() interface{}

A Valuer generates a log value. When passed to With in a value element (odd indexes), it represents a dynamic value which is re-evaluated with each log event.

var (
	// DefaultTimestamp is a Valuer that returns the current wallclock time,
	// respecting time zones, when bound.
	DefaultTimestamp Valuer = func() interface{} { return time.Now().Format(time.RFC3339) }

	// DefaultTimestampUTC is a Valuer that returns the current time in UTC
	// when bound.
	DefaultTimestampUTC Valuer = func() interface{} { return time.Now().UTC().Format(time.RFC3339) }
)

func Caller

func Caller(depth int) Valuer

Caller returns a Valuer that returns a file and line from a specified depth in the callstack. Users will probably want to use DefaultCaller.

func Timestamp

func Timestamp(t func() time.Time) Valuer

Timestamp returns a Valuer that invokes the underlying function when bound, returning a time.Time. Users will probably want to use DefaultTimestamp or DefaultTimestampUTC.