Back to godoc.org
within.website/ln

Package ln

v0.9.1
Latest Go to latest

The latest major version is .

Published: Jun 3, 2020 | License: BSD-2-Clause | Module: within.website/ln

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

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

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.

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

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier