lxd: github.com/lxc/lxd/shared/log15 Index | Files | Directories

package log15

import "github.com/lxc/lxd/shared/log15"


Package Files

format.go handler.go handler_other.go logger.go root.go syslog.go


var (
    StdoutHandler = StreamHandler(os.Stdout, LogfmtFormat())
    StderrHandler = StreamHandler(os.Stderr, LogfmtFormat())
var Must muster

The Must object provides the following Handler creation functions which instead of returning an error parameter only return a Handler and panic on failure: FileHandler, NetHandler, SyslogHandler, SyslogNetHandler

func Crit Uses

func Crit(msg string, ctx ...interface{})

Crit is a convenient alias for Root().Crit

func Debug Uses

func Debug(msg string, ctx ...interface{})

Debug is a convenient alias for Root().Debug

func Error Uses

func Error(msg string, ctx ...interface{})

Error is a convenient alias for Root().Error

func Info Uses

func Info(msg string, ctx ...interface{})

Info is a convenient alias for Root().Info

func Warn Uses

func Warn(msg string, ctx ...interface{})

Warn is a convenient alias for Root().Warn

type Ctx Uses

type Ctx map[string]interface{}

Ctx is a map of key/value pairs to pass as context to a log function Use this only if you really need greater safety around the arguments you pass to the logging functions.

type Format Uses

type Format interface {
    Format(r *Record) []byte

func FormatFunc Uses

func FormatFunc(f func(*Record) []byte) Format

FormatFunc returns a new Format object which uses the given function to perform record formatting.

func JsonFormat Uses

func JsonFormat() Format

JsonFormat formats log records as JSON objects separated by newlines. It is the equivalent of JsonFormatEx(false, true).

func JsonFormatEx Uses

func JsonFormatEx(pretty, lineSeparated bool) Format

JsonFormatEx formats log records as JSON objects. If pretty is true, records will be pretty-printed. If lineSeparated is true, records will be logged with a new line between each record.

func LogfmtFormat Uses

func LogfmtFormat() Format

LogfmtFormat prints records in logfmt format, an easy machine-parseable but human-readable format for key/value pairs.

For more details see: http://godoc.org/github.com/kr/logfmt

func TerminalFormat Uses

func TerminalFormat() Format

TerminalFormat formats log records optimized for human readability on a terminal with color-coded level output and terser human friendly timestamp. This format should only be used for interactive programs or while developing.

[TIME] [LEVEL] MESAGE key=value key=value ...


[May 16 20:58:45] [DBUG] remove route ns=haproxy addr=

type Handler Uses

type Handler interface {
    Log(r *Record) error

A Logger prints its log records by writing to a Handler. The Handler interface defines where and how log records are written. Handlers are composable, providing you great flexibility in combining them to achieve the logging structure that suits your applications.

func BufferedHandler Uses

func BufferedHandler(bufSize int, h Handler) Handler

BufferedHandler writes all records to a buffered channel of the given size which flushes into the wrapped handler whenever it is available for writing. Since these writes happen asynchronously, all writes to a BufferedHandler never return an error and any errors from the wrapped handler are ignored.

func CallerFileHandler Uses

func CallerFileHandler(h Handler) Handler

CallerFileHandler returns a Handler that adds the line number and file of the calling function to the context with key "caller".

func CallerStackHandler Uses

func CallerStackHandler(format string, h Handler) Handler

CallerStackHandler returns a Handler that adds a stack trace to the context with key "stack". The stack trace is formated as a space separated list of call sites inside matching []'s. The most recent call site is listed first. Each call site is formatted according to format. See the documentation of log15/stack.Call.Format for the list of supported formats.

func ChannelHandler Uses

func ChannelHandler(recs chan<- *Record) Handler

ChannelHandler writes all records to the given channel. It blocks if the channel is full. Useful for async processing of log messages, it's used by BufferedHandler.

func DiscardHandler Uses

func DiscardHandler() Handler

DiscardHandler reports success for all writes but does nothing. It is useful for dynamically disabling logging at runtime via a Logger's SetHandler method.

func FailoverHandler Uses

func FailoverHandler(hs ...Handler) Handler

A FailoverHandler writes all log records to the first handler specified, but will failover and write to the second handler if the first handler has failed, and so on for all handlers specified. For example you might want to log to a network socket, but failover to writing to a file if the network fails, and then to standard out if the file write fails:

    log.Must.NetHandler("tcp", ":9090", log.JsonFormat()),
    log.Must.FileHandler("/var/log/app.log", log.LogfmtFormat()),

All writes that do not go to the first handler will add context with keys of the form "failover_err_{idx}" which explain the error encountered while trying to write to the handlers before them in the list.

func FileHandler Uses

func FileHandler(path string, fmtr Format) (Handler, error)

FileHandler returns a handler which writes log records to the give file using the given format. If the path already exists, FileHandler will append to the given file. If it does not, FileHandler will create the file with mode 0644.

func FilterHandler Uses

func FilterHandler(fn func(r *Record) bool, h Handler) Handler

FilterHandler returns a Handler that only writes records to the wrapped Handler if the given function evaluates true. For example, to only log records where the 'err' key is not nil:

logger.SetHandler(FilterHandler(func(r *Record) bool {
    for i := 0; i < len(r.Ctx); i += 2 {
        if r.Ctx[i] == "err" {
            return r.Ctx[i+1] != nil
    return false
}, h))

func FuncHandler Uses

func FuncHandler(fn func(r *Record) error) Handler

FuncHandler returns a Handler that logs records with the given function.

func LazyHandler Uses

func LazyHandler(h Handler) Handler

LazyHandler writes all values to the wrapped handler after evaluating any lazy functions in the record's context. It is already wrapped around StreamHandler and SyslogHandler in this library, you'll only need it if you write your own Handler.

func LvlFilterHandler Uses

func LvlFilterHandler(maxLvl Lvl, h Handler) Handler

LvlFilterHandler returns a Handler that only writes records which are less than the given verbosity level to the wrapped Handler. For example, to only log Error/Crit records:

log.LvlFilterHandler(log.Error, log.StdoutHandler)

func MatchFilterHandler Uses

func MatchFilterHandler(key string, value interface{}, h Handler) Handler

MatchFilterHandler returns a Handler that only writes records to the wrapped Handler if the given key in the logged context matches the value. For example, to only log records from your ui package:

log.MatchFilterHandler("pkg", "app/ui", log.StdoutHandler)

func MultiHandler Uses

func MultiHandler(hs ...Handler) Handler

A MultiHandler dispatches any write to each of its handlers. This is useful for writing different types of log information to different locations. For example, to log to a file and standard error:

    log.Must.FileHandler("/var/log/app.log", log.LogfmtFormat()),

func NetHandler Uses

func NetHandler(network, addr string, fmtr Format) (Handler, error)

NetHandler opens a socket to the given address and writes records over the connection.

func StreamHandler Uses

func StreamHandler(wr io.Writer, fmtr Format) Handler

StreamHandler writes log records to an io.Writer with the given format. StreamHandler can be used to easily begin writing log records to other outputs.

StreamHandler wraps itself with LazyHandler and SyncHandler to evaluate Lazy objects and perform safe concurrent writes.

func SyncHandler Uses

func SyncHandler(h Handler) Handler

SyncHandler can be wrapped around a handler to guarantee that only a single Log operation can proceed at a time. It's necessary for thread-safe concurrent writes.

func SyslogHandler Uses

func SyslogHandler(tag string, fmtr Format) (Handler, error)

SyslogHandler opens a connection to the system syslog daemon by calling syslog.New and writes all records to it.

func SyslogNetHandler Uses

func SyslogNetHandler(net, addr string, tag string, fmtr Format) (Handler, error)

SyslogHandler opens a connection to a log daemon over the network and writes all log records to it.

type Lazy Uses

type Lazy struct {
    Fn interface{}

Lazy allows you to defer calculation of a logged value that is expensive to compute until it is certain that it must be evaluated with the given filters.

Lazy may also be used in conjunction with a Logger's New() function to generate a child logger which always reports the current value of changing state.

You may wrap any function which takes no arguments to Lazy. It may return any number of values of any type.

type Logger Uses

type Logger interface {
    // New returns a new Logger that has this logger's context plus the given context
    New(ctx ...interface{}) Logger

    // SetHandler updates the logger to write records to the specified handler.
    SetHandler(h Handler)

    // Log a message at the given level with context key/value pairs
    Debug(msg string, ctx ...interface{})
    Info(msg string, ctx ...interface{})
    Warn(msg string, ctx ...interface{})
    Error(msg string, ctx ...interface{})
    Crit(msg string, ctx ...interface{})

A Logger writes key/value pairs to a Handler

func New Uses

func New(ctx ...interface{}) Logger

New returns a new logger with the given context. New is a convenient alias for Root().New

func Root Uses

func Root() Logger

Root returns the root logger

type Lvl Uses

type Lvl int
const (
    LvlCrit Lvl = iota

func LvlFromString Uses

func LvlFromString(lvlString string) (Lvl, error)

Returns the appropriate Lvl from a string name. Useful for parsing command line args and configuration files.

func (Lvl) String Uses

func (l Lvl) String() string

Returns the name of a Lvl

type Record Uses

type Record struct {
    Time     time.Time
    Lvl      Lvl
    Msg      string
    Ctx      []interface{}
    CallPC   [1]uintptr
    KeyNames RecordKeyNames

A Record is what a Logger asks its handler to write

type RecordKeyNames Uses

type RecordKeyNames struct {
    Time string
    Msg  string
    Lvl  string


stackPackage stack implements utilities to capture, manipulate, and format call stacks.

Package log15 imports 18 packages (graph) and is imported by 87 packages. Updated 2019-06-14. Refresh now. Tools for package owners.