ln: within.website/ln Index | Files | Directories

package ln

import "within.website/ln"

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

Package Files

action.go context.go doc.go errors_hack.go filter.go formatter.go logger.go message.go stack.go

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

func AddFilter Uses

func AddFilter(f Filter)

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

func Error Uses

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

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

func Fatal Uses

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

Fatal logs this set of values, then panics.

func FatalErr Uses

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

FatalErr combines Fatal and Error.

func Log Uses

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

Log is the generic logging method.

func WithF Uses

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

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

type Event Uses

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

Event represents an event

type F Uses

type F map[string]interface{}

F is a key-value mapping for structured data.

func FFromContext Uses

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

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

func (F) Extend Uses

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

Extend concatentates one F with one or many Fer instances.

func (F) F Uses

func (f F) F() F

F makes F an Fer

type Fer Uses

type Fer interface {
    F() F
}

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

func Action Uses

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 Uses

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 Uses

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 Uses

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

Filter interface for defining chain filters

type FilterFunc Uses

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

FilterFunc allows simple functions to implement the Filter interface

func (FilterFunc) Apply Uses

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

Apply implements the Filter interface

func (FilterFunc) Close Uses

func (ff FilterFunc) Close()

Close implements the Filter interface

func (FilterFunc) Run Uses

func (ff FilterFunc) Run()

Run implements the Filter interface

type Formatter Uses

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 Uses

func JSONFormatter() Formatter

JSONFormatter outputs json lines for use with tools like https://github.com/koenbollen/jl.

func NewTextFormatter Uses

func NewTextFormatter() Formatter

NewTextFormatter returns a Formatter that outputs as text.

type Logger Uses

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 Uses

func (l *Logger) AddFilter(f Filter)

AddFilter adds a filter to the beginning of the stack.

func (*Logger) Error Uses

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 Uses

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

Fatal logs this set of values, then panics.

func (*Logger) FatalErr Uses

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

FatalErr combines Fatal and Error.

func (*Logger) Log Uses

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

Log is the generic logging method.

type TextFormatter Uses

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 Uses

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

Format implements the Formatter interface

type WriterFilter Uses

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

WriterFilter implements a filter, which arbitrarily writes to an io.Writer

func NewWriterFilter Uses

func NewWriterFilter(out io.Writer, format Formatter) *WriterFilter

NewWriterFilter creates a filter to add to the chain

func (*WriterFilter) Apply Uses

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

Apply implements the Filter interface

func (*WriterFilter) Close Uses

func (w *WriterFilter) Close()

Close implements the Filter interface

func (*WriterFilter) Run Uses

func (w *WriterFilter) Run()

Run implements the Filter interface

Directories

PathSynopsis
exPackage ex is a set of extensions and middleware for ln.
opnamePackage opname contains an extensible "operation name" construct for go applications.

Package ln imports 13 packages (graph) and is imported by 35 packages. Updated 2019-07-07. Refresh now. Tools for package owners.