log

Documentation

Overview

Package log defines a consistent logging API that can be used from registered objects. This gives the component ecosystem the option to perform logging without deciding on the logger that must be used. It also allows apps to switch out loggers in different scenarios.

There are several wrapper packages builtin. Since the API is extracted from the Zap logger, a convenience Zap wrapper is provided. A wrapper for the standard log package is provided, which adds the key-value API Zap introduces. There is also a null implementation for testing and development.

There are three main opinions this API comes with:

1. Many apps will use and normalize to key-value structured logging.
2. Logging shouldn't impact control, so Fatal et al are not used.
3. Warning is a useless log level. Ideally only Debug and Info are used.

Using only Debug and Info is highly encouraged, but Error is also provided as a compromise in supporting the traditional log level model. Open source components should avoid using it. In fact, most open source libraries should just use Debug to minimize forced user-facing logs.

This leaves the semantics of Error up to the app. If used, we suggest reserving it for logging unhandled error objects.

Index

• type DebugLogger
• type ErrorLogger
• type InfoLogger
• type Logger

Types

type DebugLogger

type DebugLogger interface {
	// Debug logs with fmt.Sprint-like arguments.
	Debug(args ...interface{})

	// Debugf logs with fmt.Sprintf-like arguments.
	Debugf(template string, args ...interface{})

	// Debugw logs with additional context using variadic key-value pairs.
	Debugw(msg string, keysAndValues ...interface{})
}

DebugLogger is for developer/operator debug logs. Libraries should typically only use DebugLogger.

type ErrorLogger

type ErrorLogger interface {
	// Error logs with fmt.Sprint-like arguments.
	Error(args ...interface{})

	// Errorf logs with fmt.Sprintf-like arguments.
	Errorf(template string, args ...interface{})

	// Errorw logs with additional context using variadic key-value pairs.
	Errorw(msg string, keysAndValues ...interface{})
}

ErrorLogger is specifically for errors. Libraries should typically never use ErrorLogger.

type InfoLogger

type InfoLogger interface {
	// Info logs with fmt.Sprint-like arguments.
	Info(args ...interface{})

	// Infof logs with fmt.Sprintf-like arguments.
	Infof(template string, args ...interface{})

	// Infow logs with additional context using variadic key-value pairs.
	Infow(msg string, keysAndValues ...interface{})
}

InfoLogger is for typical user/operator logs. Libraries should avoid using InfoLogger.

type Logger

type Logger interface {
	With(args ...interface{}) Logger
	DebugLogger
	InfoLogger
	ErrorLogger
}

Logger is a full debug, info, and error logger.