README

ln: The Natural Logger for Go

License GoDoc Build Status Go Report Card

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

(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.

Expand ▾ Collapse ▴

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.

Index

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

func AddFilter(f Filter)

AddFilter adds a filter to the beginning of the default logger stack.

func Error

func Error(ctx context.Context, err error, xs ...Fer)

Error logs an error and information about the context of said error.

func Fatal

func Fatal(ctx context.Context, xs ...Fer)

Fatal logs this set of values, then panics.

func FatalErr

func FatalErr(ctx context.Context, err error, xs ...Fer)

FatalErr combines Fatal and Error.

func Log

func Log(ctx context.Context, xs ...Fer)

Log is the generic logging method.

func WithF

func WithF(ctx context.Context, f F) context.Context

WithF stores or appends a given F instance into a context.

Types

type Event

type Event struct {
	Time    time.Time
	Data    F
	Message string
}

Event represents an event

type F

type F map[string]interface{}

F is a key-value mapping for structured data.

func FFromContext

func FFromContext(ctx context.Context) (F, bool)

FFromContext fetches the `F` out of the context if it exists.

func Fmt

func Fmt(format string, args ...interface{}) F

Fmt formats a string like sprintf.

func (F) Extend

func (f F) Extend(other ...Fer)

Extend concatentates one F with one or many Fer instances.

func (F) F

func (f F) F() F

F makes F an Fer

type Fer

type Fer interface {
	F() F
}

Fer allows any type to add fields to the structured logging key->value pairs.

func Action

func Action(act string) Fer

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"))

func Debug

func Debug(format string, args ...interface{}) Fer

Debug adds a debugging connotation to this log line. This may be ignored or aggressively sampled in order to save ram.

func Info

func Info(format string, args ...interface{}) Fer

Info adds an informational connotation to this log line. This is the "default" state for things that can be ignored.

type Filter

type Filter interface {
	Apply(ctx context.Context, e Event) bool
	Run()
	Close()
}

Filter interface for defining chain filters

type FilterFunc

type FilterFunc func(ctx context.Context, e Event) bool

FilterFunc allows simple functions to implement the Filter interface

func (FilterFunc) Apply

func (ff FilterFunc) Apply(ctx context.Context, e Event) bool

Apply implements the Filter interface

func (FilterFunc) Close

func (ff FilterFunc) Close()

Close implements the Filter interface

func (FilterFunc) Run

func (ff FilterFunc) Run()

Run implements the Filter interface

type Formatter

type Formatter interface {
	Format(ctx context.Context, e Event) ([]byte, error)
}

Formatter defines the formatting of events

var DefaultFormatter Formatter

DefaultFormatter is the default way in which to format events

func JSONFormatter

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

func (*Logger) AddFilter

func (l *Logger) AddFilter(f Filter)

AddFilter adds a filter to the beginning of the stack.

func (*Logger) Error

func (l *Logger) Error(ctx context.Context, err error, xs ...Fer)

Error logs an error and information about the context of said error.

func (*Logger) Fatal

func (l *Logger) Fatal(ctx context.Context, xs ...Fer)

Fatal logs this set of values, then panics.

func (*Logger) FatalErr

func (l *Logger) FatalErr(ctx context.Context, err error, xs ...Fer)

FatalErr combines Fatal and Error.

func (*Logger) Log

func (l *Logger) Log(ctx context.Context, xs ...Fer)

Log is the generic logging method.

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.

func (*TextFormatter) Format

func (t *TextFormatter) Format(ctx context.Context, e Event) ([]byte, error)

Format implements the Formatter interface

type WriterFilter

type WriterFilter struct {
	sync.Mutex
	Out       io.Writer
	Formatter Formatter
}

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

func (*WriterFilter) Apply

func (w *WriterFilter) Apply(ctx context.Context, e Event) bool

Apply implements the Filter interface

func (*WriterFilter) Close

func (w *WriterFilter) Close()

Close implements the Filter interface

func (*WriterFilter) Run

func (w *WriterFilter) Run()

Run implements the Filter interface

Directories

Path Synopsis
ex Package ex is a set of extensions and middleware for ln.
opname Package opname contains an extensible "operation name" construct for go applications.