level

Documentation

Overview

Package level is an EXPERIMENTAL levelled logging package. The API will definitely have breaking changes and may be deleted altogether. Be warned!

To use the level package, create a logger as per normal in your func main, and wrap it with level.New.

var logger log.Logger
logger = log.NewLogfmtLogger(os.Stderr)
logger = level.New(logger, level.Config{Allowed: level.AllowInfoAndAbove}) // <--
logger = log.NewContext(logger).With("ts", log.DefaultTimestampUTC)

Then, at the callsites, use one of the level.Debug, Info, Warn, or Error helper methods to emit leveled log events.

logger.Log("foo", "bar") // as normal, no level
level.Debug(logger).Log("request_id", reqID, "trace_data", trace.Get())
if value > 100 {
    level.Error(logger).Log("value", value)
}

The leveled logger allows precise control over what should happen if a log event is emitted without a level key, or if a squelched level is used. Check the Config struct for details. And, you can easily use non-default level values: create new string constants for whatever you want to change, pass them explicitly to the Config struct, and write your own level.Foo-style helper methods.

Index

• func AllowAll() []string
• func AllowDebugAndAbove() []string
• func AllowErrorOnly() []string
• func AllowInfoAndAbove() []string
• func AllowNone() []string
• func AllowWarnAndAbove() []string
• func Debug(logger log.Logger) log.Logger
• func Error(logger log.Logger) log.Logger
• func Info(logger log.Logger) log.Logger
• func New(next log.Logger, config Config) log.Logger
• func Warn(logger log.Logger) log.Logger
• type Config

Functions

func AllowAll

func AllowAll() []string

AllowAll is an alias for AllowDebugAndAbove.

func AllowDebugAndAbove

func AllowDebugAndAbove() []string

AllowDebugAndAbove allows all of the four default log levels. Its return value may be provided as the Allowed parameter in the Config.

func AllowErrorOnly

func AllowErrorOnly() []string

AllowErrorOnly allows only the default error log level. Its return value may be provided as the Allowed parameter in the Config.

func AllowInfoAndAbove

func AllowInfoAndAbove() []string

AllowInfoAndAbove allows the default info, warn, and error log levels. Its return value may be provided as the Allowed parameter in the Config.

func AllowNone

func AllowNone() []string

AllowNone allows none of the default log levels. Its return value may be provided as the Allowed parameter in the Config.

func AllowWarnAndAbove

func AllowWarnAndAbove() []string

AllowWarnAndAbove allows the default warn and error log levels. Its return value may be provided as the Allowed parameter in the Config.

func Debug

func Debug(logger log.Logger) log.Logger

Debug returns a logger with the level key set to DebugLevelValue.

func Error

func Error(logger log.Logger) log.Logger

Error returns a logger with the level key set to ErrorLevelValue.

func Info

func Info(logger log.Logger) log.Logger

Info returns a logger with the level key set to InfoLevelValue.

func New

func New(next log.Logger, config Config) log.Logger

New wraps the logger and implements level checking. See the commentary on the Config object for a detailed description of how to configure levels.

func Warn

func Warn(logger log.Logger) log.Logger

Warn returns a logger with the level key set to WarnLevelValue.

Types

type Config

type Config struct {
	// Allowed enumerates the accepted log levels. If a log event is encountered
	// with a level key set to a value that isn't explicitly allowed, the event
	// will be squelched, and ErrNotAllowed returned.
	Allowed []string

	// ErrNotAllowed is returned to the caller when Log is invoked with a level
	// key that hasn't been explicitly allowed. By default, ErrNotAllowed is
	// nil; in this case, the log event is squelched with no error.
	ErrNotAllowed error

	// SquelchNoLevel will squelch log events with no level key, so that they
	// don't proceed through to the wrapped logger. If SquelchNoLevel is set to
	// true and a log event is squelched in this way, ErrNoLevel is returned to
	// the caller.
	SquelchNoLevel bool

	// ErrNoLevel is returned to the caller when SquelchNoLevel is true, and Log
	// is invoked without a level key. By default, ErrNoLevel is nil; in this
	// case, the log event is squelched with no error.
	ErrNoLevel error
}

Config parameterizes the leveled logger.