README
¶
l15h
l15h provides some useful Handlers and logging methods for use with log15: https://github.com/inconshreveable/log15
log15 is a levelled logger with these levels:
Debug("debug msg")Info("info msg")Warn("warning msg")Error("error msg")Crit("critical msg")
l15h provides these convenience methods which log at the Crit level:
Panic("panic msg")PanicContext(logger, "panic msg")Fatal("fatal msg")FatalContext(logger, "fatal msg")
log15 log messages can have structure by supplying key/value pairs to the above
methods, eg. Debug("my msg", "url", "google.com", "retries", 3, "err", err)
log15 loggers can have and inherit key/value context:
pkgLog := log15.New("pkg", "mypkg")
structLog := pkgLog.New("struct", "mystruct", "id", struct.ID)
structLog.Info("started", "foo", "bar")
Which would give output like:
INFO[06-17|21:58:10] started pkg=mypkg struct=mystruct id=1 foo=bar
One of log15's best features is the ability to set composable Handlers that determine where log output goes and what it looks like. l15h provides these additional handlers:
- StoreHandler
- CallerInfoHandler
- ChangeableHandler
l15h also provides a convenience method for adding a new handler to a logger's existing handler(s):
AddHandler(logger, newHandler)
See the GoDoc for usage examples.
Installation
go get github.com/sb10/l15h
Importing
import "github.com/sb10/l15h"
Versioning
The API of the master branch of l15h will probably remain backwards compatible, but this is not guaranteed. If you want to rely on a stable API, you must vendor the library.
Documentation
¶
Overview ¶
Package l15h provides some useful Handlers for use with log15: https://github.com/inconshreveable/log15.
Usage ¶
import (
log "github.com/inconshreveable/log15"
"github.com/sb10/l15h"
)
// Store logs in memory for dealing with later
store := l15h.NewStore()
h := log.MultiHandler(
l15h.StoreHandler(store, log.LogfmtFormat()),
log.StderrHandler,
)
log.Root().SetHandler(h)
log.Debug("debug")
log.Info("info")
logs := store.Logs() // logs is a slice of your 2 log messages as strings
// Always annotate your logs (other than Info()) with some caller
// information, with Crit() getting a stack trace
h = l15h.CallerInfoHandler(log.StderrHandler)
log.Root().SetHandler(h)
log.Debug("debug") // includes a caller=
log.Info("info") // nothing added
log.Crit("crit") // includes a stack=
// Combine the above together
h = l15h.CallerInfoHandler(
log.MultiHandler(
l15h.StoreHandler(store, log.LogfmtFormat()),
log.StderrHandler,
)
)
//...
// Have child loggers that change how they log when their parent's Handler
// changes
changer := l15h.NewChanger(log15.DiscardHandler())
log.Root().SetHandler(l15h.ChangeableHandler(changer))
log.Info("discarded") // nothing logged
childLogger := log.New("child", "context")
store = l15h.NewStore()
l15h.AddHandler(childLogger, l15h.StoreHandler(store, log.LogfmtFormat()))
childLogger.Info("one") // len(store.Logs()) == 1
changer.SetHandler(log15.StderrHandler)
log.Info("logged") // logged to STDERR
childLogger.Info("two") // logged to STDERR and len(store.Logs()) == 2
// We have Panic and Fatal methods
l15h.Panic("msg")
l15h.Fatal("msg")
Index ¶
- func AddHandler(l log15.Logger, h log15.Handler)
- func CallerInfoHandler(h log15.Handler) log15.Handler
- func ChangeableHandler(changer *Changer) log15.Handler
- func Fatal(msg string, ctx ...interface{})
- func FatalContext(l log15.Logger, msg string, ctx ...interface{})
- func Panic(msg string, ctx ...interface{})
- func PanicContext(l log15.Logger, msg string, ctx ...interface{})
- func SetExitFunc(ef func(code int))
- func StoreHandler(store *Store, fmtr log15.Format) log15.Handler
- type Changer
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddHandler ¶
AddHandler is a convenience for adding an additional handler to a logger, keeping any existing ones. Note that this simply puts the existing handler and the new handler within a MultiHandler, so you should probably avoid calling this too many times on the same logger (or its descendants).
func CallerInfoHandler ¶
CallerInfoHandler returns a Handler that, at the Debug, Warn and Error levels, adds the file and line number of the calling function to the context with key "caller". At the Crit levels it instead adds a stack trace to the context with key "stack". The stack trace is formatted as a space separated list of call sites inside matching []'s. The most recent call site is listed first.
func ChangeableHandler ¶
ChangeableHandler is for use when you your library will start with a base logger and create New() loggers from that, inheriting its Handler and possibly adding its own (eg. with AddHandler()) such as the StoreHandler. But you want a user of your library to be able to change the Handler for all your loggers. You can do this by setting a ChangeableHandler on your base logger, and giving users of your library access to your Changer, which they can call SetHandler() on to define how things are logged any way they like.
func Fatal ¶
func Fatal(msg string, ctx ...interface{})
Fatal logs a message at the Crit level with key/val fatal=true added to the context and then calls os.Exit(1). Operates on the root Logger. The exit is not recoverable and deferred functions do not get called.
func FatalContext ¶
FatalContext is like Fatal(), but also takes a Logger if you want to log to something other than root.
func Panic ¶
func Panic(msg string, ctx ...interface{})
Panic logs a message at the Crit level with key/val panic=true added to the context and then calls panic(msg). Operates on the root Logger. The panic will send a complete stack trace to STDERR and cause the application to terminate after calling deferred functions unless recovered.
func PanicContext ¶
PanicContext is like Panic(), but also takes a Logger if you want to log to something other than root.
func SetExitFunc ¶
func SetExitFunc(ef func(code int))
SetExitFunc should typically only be used if you're testing a place where your code should call Fatal() or FatalContext() but don't want your test script to actually exit. Your supplied function will be called at the end of those methods instead of os.Exit(1).
Types ¶
type Changer ¶
type Changer struct {
// contains filtered or unexported fields
}
Changer struct lets you dynamically change the Handler of all loggers that inherit from a logger that uses a ChangeableHandler, which takes one of these. A Changer is safe for concurrent use.
func NewChanger ¶
NewChanger creates a Changer for supplying to ChangeableHandler and keeping for later use.
func (*Changer) GetHandler ¶
GetHandler returns the previously set Handler.
func (*Changer) SetHandler ¶
SetHandler sets a new Handler on the Changer, so that any logger that is using a ChangeableHandler with this Changer will now log to this new Handler.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store struct is used for passing to StoreHandler. Create one, pass it to StoreHandler and set that handler on your logger, then log messages. Store.Logs() will then give you access to everything that was logged.
func NewStore ¶
func NewStore() *Store
NewStore creates a Store for supplying to StoreHandler and keeping for later use.
Source Files