level

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 27, 2022 License: MIT Imports: 3 Imported by: 2,925

Documentation

Overview

Package level implements leveled logging on top of Go kit's log package. To use the level package, create a logger as per normal in your func main, and wrap it with level.NewFilter.

var logger log.Logger
logger = log.NewLogfmtLogger(os.Stderr)
logger = level.NewFilter(logger, level.AllowInfo()) // <--
logger = log.With(logger, "ts", log.DefaultTimestampUTC)

It's also possible to configure log level from a string. For instance from a flag, environment variable or configuration file.

fs := flag.NewFlagSet("myprogram")
lvl := fs.String("log", "info", "debug, info, warn, error")

var logger log.Logger
logger = log.NewLogfmtLogger(os.Stderr)
logger = level.NewFilter(logger, level.Allow(level.ParseDefault(*lvl, level.InfoValue()))) // <--
logger = log.With(logger, "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)
}

NewFilter allows precise control over what happens when a log event is emitted without a level key, or if a squelched level is used. Check the Option functions for details.

Example (Basic)
package main

import (
	"os"

	"github.com/go-kit/log"
	"github.com/go-kit/log/level"
)

func main() {
	logger := log.NewLogfmtLogger(os.Stdout)
	level.Debug(logger).Log("msg", "this message is at the debug level")
	level.Info(logger).Log("msg", "this message is at the info level")
	level.Warn(logger).Log("msg", "this message is at the warn level")
	level.Error(logger).Log("msg", "this message is at the error level")

}
Output:

level=debug msg="this message is at the debug level"
level=info msg="this message is at the info level"
level=warn msg="this message is at the warn level"
level=error msg="this message is at the error level"
Example (Filtered)
package main

import (
	"errors"
	"os"

	"github.com/go-kit/log"
	"github.com/go-kit/log/level"
)

func main() {
	// Set up logger with level filter.
	logger := log.NewLogfmtLogger(os.Stdout)
	logger = level.NewFilter(logger, level.AllowInfo())
	logger = log.With(logger, "caller", log.DefaultCaller)

	// Use level helpers to log at different levels.
	level.Error(logger).Log("err", errors.New("bad data"))
	level.Info(logger).Log("event", "data saved")
	level.Debug(logger).Log("next item", 17) // filtered

}
Output:

level=error caller=example_test.go:33 err="bad data"
level=info caller=example_test.go:34 event="data saved"
Example (Parsed)
package main

import (
	"errors"
	"flag"
	"os"

	"github.com/go-kit/log"
	"github.com/go-kit/log/level"
)

func main() {
	fs := flag.NewFlagSet("example", flag.ExitOnError)
	lvl := fs.String("log-level", "", `"debug", "info", "warn" or "error"`)
	fs.Parse([]string{"-log-level", "info"})

	// Set up logger with level filter.
	logger := log.NewLogfmtLogger(os.Stdout)
	logger = level.NewFilter(logger, level.Allow(level.ParseDefault(*lvl, level.DebugValue())))
	logger = log.With(logger, "caller", log.DefaultCaller)

	// Use level helpers to log at different levels.
	level.Error(logger).Log("err", errors.New("bad data"))
	level.Info(logger).Log("event", "data saved")
	level.Debug(logger).Log("next item", 17) // filtered

}
Output:

level=error caller=example_test.go:53 err="bad data"
level=info caller=example_test.go:54 event="data saved"

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrInvalidLevelString = errors.New("invalid level string")

ErrInvalidLevelString is returned whenever an invalid string is passed to Parse.

Functions

func Debug

func Debug(logger log.Logger) log.Logger

Debug returns a logger that includes a Key/DebugValue pair.

func Error

func Error(logger log.Logger) log.Logger

Error returns a logger that includes a Key/ErrorValue pair.

func Info

func Info(logger log.Logger) log.Logger

Info returns a logger that includes a Key/InfoValue pair.

func Key

func Key() interface{}

Key returns the unique key added to log events by the loggers in this package.

func NewFilter

func NewFilter(next log.Logger, options ...Option) log.Logger

NewFilter wraps next and implements level filtering. See the commentary on the Option functions for a detailed description of how to configure levels. If no options are provided, all leveled log events created with Debug, Info, Warn or Error helper methods are squelched and non-leveled log events are passed to next unmodified.

func NewInjector

func NewInjector(next log.Logger, level Value) log.Logger

NewInjector wraps next and returns a logger that adds a Key/level pair to the beginning of log events that don't already contain a level. In effect, this gives a default level to logs without a level.

func Warn

func Warn(logger log.Logger) log.Logger

Warn returns a logger that includes a Key/WarnValue pair.

Types

type Option

type Option func(*logger)

Option sets a parameter for the leveled logger.

func Allow added in v0.2.1

func Allow(v Value) Option

Allow the provided log level to pass.

func AllowAll

func AllowAll() Option

AllowAll is an alias for AllowDebug.

func AllowDebug

func AllowDebug() Option

AllowDebug allows error, warn, info and debug level log events to pass.

func AllowError

func AllowError() Option

AllowError allows only error level log events to pass.

func AllowInfo

func AllowInfo() Option

AllowInfo allows error, warn and info level log events to pass.

func AllowNone

func AllowNone() Option

AllowNone allows no leveled log events to pass.

func AllowWarn

func AllowWarn() Option

AllowWarn allows error and warn level log events to pass.

func ErrNoLevel

func ErrNoLevel(err error) Option

ErrNoLevel sets the error to return from Log when it squelches a log event with no level. By default, ErrNoLevel is nil; in this case the log event is squelched with no error.

func ErrNotAllowed

func ErrNotAllowed(err error) Option

ErrNotAllowed sets the error to return from Log when it squelches a log event disallowed by the configured Allow[Level] option. By default, ErrNotAllowed is nil; in this case the log event is squelched with no error.

func SquelchNoLevel

func SquelchNoLevel(squelch bool) Option

SquelchNoLevel instructs Log to squelch log events with no level, 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, the error value configured with ErrNoLevel is returned to the caller.

type Value

type Value interface {
	String() string
	// contains filtered or unexported methods
}

Value is the interface that each of the canonical level values implement. It contains unexported methods that prevent types from other packages from implementing it and guaranteeing that NewFilter can distinguish the levels defined in this package from all other values.

func DebugValue

func DebugValue() Value

DebugValue returns the unique value added to log events by Debug.

func ErrorValue

func ErrorValue() Value

ErrorValue returns the unique value added to log events by Error.

func InfoValue

func InfoValue() Value

InfoValue returns the unique value added to log events by Info.

func Parse added in v0.2.1

func Parse(level string) (Value, error)

Parse a string to its corresponding level value. Valid strings are "debug", "info", "warn", and "error". Strings are normalized via strings.TrimSpace and strings.ToLower.

func ParseDefault added in v0.2.1

func ParseDefault(level string, def Value) Value

ParseDefault calls Parse and returns the default Value on error.

func WarnValue

func WarnValue() Value

WarnValue returns the unique value added to log events by Warn.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL