package
5.6.3-darwinv2-rc0+incompatible
Repository: https://github.com/scroll-tech/go-ethereum.git
Documentation: pkg.go.dev
# README
log15 
Package log15 provides an opinionated, simple toolkit for best-practice logging in Go (golang) that is both human and machine readable. It is modeled after the Go standard library's io and net/http packages and is an alternative to the standard library's log package.
Features
- A simple, easy-to-understand API
- Promotes structured logging by encouraging use of key/value pairs
- Child loggers which inherit and add their own private context
- Lazy evaluation of expensive operations
- Simple Handler interface allowing for construction of flexible, custom logging configurations with a tiny API.
- Color terminal support
- Built-in support for logging to files, streams, syslog, and the network
- Support for forking records to multiple handlers, buffering records for output, failing over from failed handler writes, + more
Versioning
The API of the master branch of log15 should always be considered unstable. If you want to rely on a stable API, you must vendor the library.
Importing
import log "github.com/inconshreveable/log15"
Examples
// all loggers can have key/value context
srvlog := log.New("module", "app/server")
// all log messages can have key/value context
srvlog.Warn("abnormal conn rate", "rate", curRate, "low", lowRate, "high", highRate)
// child loggers with inherited context
connlog := srvlog.New("raddr", c.RemoteAddr())
connlog.Info("connection open")
// lazy evaluation
connlog.Debug("ping remote", "latency", log.Lazy{pingRemote})
// flexible configuration
srvlog.SetHandler(log.MultiHandler(
log.StreamHandler(os.Stderr, log.LogfmtFormat()),
log.LvlFilterHandler(
log.LvlError,
log.Must.FileHandler("errors.json", log.JSONFormat()))))
Will result in output that looks like this:
WARN[06-17|21:58:10] abnormal conn rate module=app/server rate=0.500 low=0.100 high=0.800
INFO[06-17|21:58:10] connection open module=app/server raddr=10.0.0.1
Breaking API Changes
The following commits broke API stability. This reference is intended to help you understand the consequences of updating to a newer version of log15.
- 57a084d014d4150152b19e4e531399a7145d1540 - Added a
Get()method to theLoggerinterface to retrieve the current handler - 93404652ee366648fa622b64d1e2b67d75a3094a -
RecordfieldCallchanged tostack.Callwith switch togithub.com/go-stack/stack - a5e7613673c73281f58e15a87d2cf0cf111e8152 - Restored
syslog.Priorityargument to theSyslogXxxhandler constructors
FAQ
The varargs style is brittle and error prone! Can I have type safety please?
Yes. Use log.Ctx:
srvlog := log.New(log.Ctx{"module": "app/server"})
srvlog.Warn("abnormal conn rate", log.Ctx{"rate": curRate, "low": lowRate, "high": highRate})
License
Apache
# Functions
BufferedHandler writes all records to a buffered channel of the given size which flushes into the wrapped handler whenever it is available for writing.
CallerFileHandler returns a Handler that adds the line number and file of the calling function to the context with key "caller".
CallerFuncHandler returns a Handler that adds the calling function name to the context with key "fn".
CallerStackHandler returns a Handler that adds a stack trace to the context with key "stack".
ChannelHandler writes all records to the given channel.
Crit is a convenient alias for Root().Crit.
Debug is a convenient alias for Root().Debug.
DiscardHandler reports success for all writes but does nothing.
Error is a convenient alias for Root().Error.
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.
FileHandler returns a handler which writes log records to the give file using the given format.
FilterHandler returns a Handler that only writes records to the wrapped Handler if the given function evaluates true.
FormatFunc returns a new Format object which uses the given function to perform record formatting.
FormatLogfmtInt64 formats n with thousand separators.
FormatLogfmtUint64 formats n with thousand separators.
FuncHandler returns a Handler that logs records with the given function.
Info is a convenient alias for Root().Info.
JSONFormat formats log records as JSON objects separated by newlines.
JSONFormatEx formats log records as JSON objects.
JSONFormatOrderedEx formats log records as JSON arrays.
LazyHandler writes all values to the wrapped handler after evaluating any lazy functions in the record's context.
LogfmtFormat prints records in logfmt format, an easy machine-parseable but human-readable format for key/value pairs.
LvlFilterHandler returns a Handler that only writes records which are less than the given verbosity level to the wrapped Handler.
LvlFromString returns the appropriate Lvl from a string name.
MatchFilterHandler returns a Handler that only writes records to the wrapped Handler if the given key in the logged context matches the value.
MultiHandler dispatches any write to each of its handlers.
NetHandler opens a socket to the given address and writes records over the connection.
New returns a new logger with the given context.
NewGlogHandler creates a new log handler with filtering functionality similar to Google's glog logger.
Output is a convenient alias for write, allowing for the modification of the calldepth (number of stack frames to skip).
PrintOrigins sets or unsets log location (file:line) printing for terminal format output.
Root returns the root logger.
StreamHandler writes log records to an io.Writer with the given format.
SyncHandler can be wrapped around a handler to guarantee that only a single Log operation can proceed at a time.
SyslogHandler opens a connection to the system syslog daemon by calling syslog.New and writes all records to it.
SyslogNetHandler opens a connection to a log daemon over the network and writes all log records to it.
TerminalFormat formats log records optimized for human readability on a terminal with color-coded level output and terser human friendly timestamp.
Trace is a convenient alias for Root().Trace.
Warn is a convenient alias for Root().Warn.
# Variables
Must 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.
No description provided by the author
No description provided by the author
# Structs
GlogHandler is a log handler that mimics the filtering features of Google's glog logger: setting global log levels; overriding with callsite pattern matches; and requesting backtraces at certain positions.
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.
A Record is what a Logger asks its handler to write.
RecordKeyNames gets stored in a Record when the write function is executed.
# Interfaces
No description provided by the author
Handler defines where and how log records are written.
A Logger writes key/value pairs to a Handler.
TerminalStringer is an analogous interface to the stdlib stringer, allowing own types to have custom shortened serialization formats when printed to the screen.