README
¶
ln: The Natural Logger for Go
ln provides a simple interface to contextually aware structured logging.
The design of ln centers around the idea of key-value pairs, which
can be interpreted on the fly, but "Filters" to do things such as
aggregated metrics, and report said metrics to, say Librato, or
statsd.
"Filters" are like WSGI, or Rack Middleware. They are run "top down"
and can abort an emitted log's output at any time, or continue to let
it through the chain. However, the interface is slightly different
than that. Rather than encapsulating the chain with partial function
application, we utilize a simpler method, namely, each plugin defines
an Apply function, which takes as an argument the log event, and
performs the work of the plugin, only if the Plugin "Applies" to this
log event.
If Apply returns false, the iteration through the rest of the
filters is aborted, and the log is dropped from further processing.
Examples
type User struct {
ID int
Username string
}
func (u User) F() ln.F {
return ln.F{
"user_id": u.ID,
"user_username": u.Username,
}
}
// in some function
u, err := CreateUser(ctx, "Foobar")
if err != nil {
ln.Error(ctx, err) // errors can also be Fers
return
}
ln.Log(ctx, ln.Info("created new user"), u) // -> user_id=123 user_username=Foobar msg="created new user"
Current Status: Known Stable
Copyright
(c) 2015-2019, Andrew Gwozdziewycz, Christine Dodrill, BSD Licensed. See LICENSE for more info.
This library was forked from apg's ln. This library is not the official ln (though it is mostly compatible with it), but it is at least what I think a logger should be.
Documentation
¶
Overview ¶
Package ln is the Natural Logger for Go
`ln` provides a simple interface to logging, and metrics, and obviates the need to utilize purpose built metrics packages, like `go-metrics` for simple use cases.
The design of `ln` centers around the idea of key-value pairs, which can be interpreted on the fly, but "Filters" to do things such as aggregated metrics, and report said metrics to, say Librato, or statsd.
"Filters" are like WSGI, or Rack Middleware. They are run "top down" and can abort an emitted log's output at any time, or continue to let it through the chain. However, the interface is slightly different than that. Rather than encapsulating the chain with partial function application, we utilize a simpler method, namely, each plugin defines an `Apply` function, which takes as an argument the log event, and performs the work of the plugin, only if the Plugin "Applies" to this log event.
If `Apply` returns `false`, the iteration through the rest of the filters is aborted, and the log is dropped from further processing.
Deprecated: use log/slog instead.
Index ¶
- Variables
- func AddFilter(f Filter)
- func Error(ctx context.Context, err error, xs ...Fer)
- func Fatal(ctx context.Context, xs ...Fer)
- func FatalErr(ctx context.Context, err error, xs ...Fer)
- func Log(ctx context.Context, xs ...Fer)
- func WithF(ctx context.Context, f F) context.Context
- type Event
- type F
- type Fer
- type Filter
- type FilterFunc
- type Formatter
- type Logger
- type TextFormatter
- type WriterFilter
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultTimeFormat represents the way in which time will be formatted by default DefaultTimeFormat = time.RFC3339 )
var NilFilter = FilterFunc(func(_ context.Context, e Event) bool { return true })
NilFilter is safe to return as a Filter, but does nothing
Functions ¶
func AddFilter ¶ added in v0.3.0
func AddFilter(f Filter)
AddFilter adds a filter to the beginning of the default logger stack.
Types ¶
type F ¶
type F map[string]interface{}
F is a key-value mapping for structured data.
func FFromContext ¶
FFromContext fetches the `F` out of the context if it exists.
type Fer ¶
type Fer interface {
F() F
}
Fer allows any type to add fields to the structured logging key->value pairs.
func Action ¶
Action is a convenience helper for logging the "action" being performed as part of a log line.
It is a convenience wrapper for the following:
ln.Log(ctx, fer, f, ln.Action("writing frozberry sales reports to database"))
type FilterFunc ¶
FilterFunc allows simple functions to implement the Filter interface
type Formatter ¶
Formatter defines the formatting of events
var DefaultFormatter Formatter
DefaultFormatter is the default way in which to format events
func JSONFormatter ¶ added in v0.3.0
func JSONFormatter() Formatter
JSONFormatter outputs json lines for use with tools like https://github.com/koenbollen/jl.
func NewTextFormatter ¶
func NewTextFormatter() Formatter
NewTextFormatter returns a Formatter that outputs as text.
type Logger ¶
type Logger struct {
Filters []Filter
}
Logger holds the current priority and list of filters
var DefaultLogger *Logger
DefaultLogger is the default implementation of Logger
type TextFormatter ¶
type TextFormatter struct {
TimeFormat string
}
TextFormatter formats events as key value pairs. Any remaining text not wrapped in an instance of `F` will be placed at the end.
type WriterFilter ¶
WriterFilter implements a filter, which arbitrarily writes to an io.Writer
func NewWriterFilter ¶
func NewWriterFilter(out io.Writer, format Formatter) *WriterFilter
NewWriterFilter creates a filter to add to the chain
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ex is a set of extensions and middleware for ln.
|
Package ex is a set of extensions and middleware for ln. |
|
Package opname contains an extensible "operation name" construct for go applications.
|
Package opname contains an extensible "operation name" construct for go applications. |