log

Documentation

Index

• Variables
• func Debug(msg string, ctx ...interface{})
• func Debugf(format string, args ...any)
• func Error(msg string, ctx ...interface{})
• func Errorf(format string, args ...any)
• func Errors(err error)
• func Errorv(err error)
• func Info(msg string, ctx ...interface{})
• func Infof(format string, args ...any)
• func Trace(msg string, ctx ...interface{})
• func Tracef(format string, args ...any)
• func Warn(msg string, ctx ...interface{})
• func Warnf(format string, args ...any)
• type CallerType
• type Ctx
• type Format
  • func FormatFunc(f func(*Record) []byte) Format
  • func JsonFormat() Format
  • func JsonFormatEx(pretty, lineSeparated bool) Format
  • func LogfmtFormat() Format
• type Handler
  • func FileHandler(path string, fmtr Format) (Handler, error)
  • func FuncHandler(fn func(r *Record) error) Handler
  • func LazyHandler(h Handler) Handler
  • func MultiHandler(hs ...Handler) Handler
  • func StreamHandler(wr io.Writer, fmtr Format) Handler
  • func SyncHandler(h Handler) Handler
• type LEVEL
  • func LevelFromString(levelString string) (LEVEL, error)
  • func (l LEVEL) String() string
• type Lazy
• type Logger
  • func New(ctx ...interface{}) Logger
  • func Root() Logger
• type Record
• type RecordKeyNames
• type TerminalFormatter
  • func TerminalFormatterDefault() TerminalFormatter
  • func (t TerminalFormatter) Format(r *Record) []byte

Variables

var (
	StdoutHandler = StreamHandler(os.Stdout, LogfmtFormat())
)

Predefined handlers

Functions

func Debug

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

Debug is a convenient alias for Root().Debug

func Debugf

func Debugf(format string, args ...any)

Debugf is a convenient alias for Root().Debugf

func Error

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

Error is a convenient alias for Root().Error

func Errorf

func Errorf(format string, args ...any)

Errorf is a convenient alias for Root().Errorf

func Errors

func Errors(err error)

Errors is a convenient alias for Root().Errorf

func Errorv

func Errorv(err error)

Errorv is a convenient alias for Root().Errorf

func Info

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

Info is a convenient alias for Root().Info

func Infof

func Infof(format string, args ...any)

Infof is a convenient alias for Root().Infof

func Trace

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

Trace is a convenient alias for Root().Trace

func Tracef

func Tracef(format string, args ...any)

Tracef formats according to a format specifier and returns the resulting string.

func Warn

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

Warn is a convenient alias for Root().Warn

func Warnf

func Warnf(format string, args ...any)

Warnf is a convenient alias for Root().Warnf

Types

type CallerType

type CallerType int

CallerType is a type for predefined log levels.

const (
	CallerTypeNone CallerType = iota
	CallerTypeMethod
	CallerTypeFileLine
	CallerTypeFullPath
)

List of predefined log Levels

type Ctx

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

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

Format is the interface implemented by StreamHandler formatters.

func FormatFunc

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

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

func JsonFormat

func JsonFormat() Format

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

func JsonFormatEx

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

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

type Handler

type Handler interface {
	Log(r *Record) error
}

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

func FileHandler

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 FuncHandler

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

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

func LazyHandler

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 MultiHandler

func MultiHandler(hs ...Handler) Handler

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.MultiHandler(
    log.Must.FileHandler("/var/log/app.log", log.LogfmtFormat()),
    log.StderrHandler)

func StreamHandler

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

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.

type LEVEL

type LEVEL int

LEVEL is a type for predefined log levels.

const (
	LevelTrace LEVEL = iota
	LevelDebug
	LevelInfo
	LevelWarning
	LevelError
)

List of predefined log Levels

func LevelFromString

func LevelFromString(levelString string) (LEVEL, error)

LevelFromString returns the appropriate LEVEL from a string name. Useful for parsing command line args and configuration files.

func (LEVEL) String

func (l LEVEL) String() string

Returns the name of a LEVEL

type Lazy

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

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

	// GetHandler gets the handler associated with the logger.
	GetHandler() Handler

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

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

	Tracef(format string, a ...any)
	Debugf(format string, a ...any)
	Infof(format string, a ...any)
	Warnf(format string, a ...any)
	Errorf(format string, a ...any)
}

A Logger writes key/value pairs to a Handler

func New

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

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

func Root

func Root() Logger

Root returns the root logger

type Record

type Record struct {
	Time     time.Time
	Level    LEVEL
	Message  string
	Context  []interface{}
	Call     stack.Call
	KeyNames RecordKeyNames
}

A Record is what a Logger asks its handler to write

type RecordKeyNames

type RecordKeyNames struct {
	Time    string
	Message string
	Level   string
}

RecordKeyNames are the predefined names of the log props used by the Logger interface.

type TerminalFormatter

type TerminalFormatter struct {
	TimestampFormat string
	TermMessageJust int
	CallerLevel     CallerType
}

func TerminalFormatterDefault

func TerminalFormatterDefault() TerminalFormatter

func (TerminalFormatter) Format

func (t TerminalFormatter) Format(r *Record) []byte

Format 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] MESSAGE key=value key=value ...

Example:

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