ln

README

ln: 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.

Current Status: Initial Development / Concept

Copyright

(c) 2015, Andrew Gwozdziewycz, BSD Licensed. See LICENSE for more info.

Documentation

Index

• Variables
• func Alert(ctx context.Context, xs ...interface{})
• func Critical(ctx context.Context, xs ...interface{})
• func Debug(ctx context.Context, xs ...interface{})
• func Emergency(ctx context.Context, xs ...interface{})
• func Error(ctx context.Context, xs ...interface{})
• func Info(ctx context.Context, xs ...interface{})
• func Notice(ctx context.Context, xs ...interface{})
• func Warning(ctx context.Context, xs ...interface{})
• type Event
• type F
  • func (f F) F() map[string]interface{}
• type Fer
• type Filter
• type FilterFunc
  • func (ff FilterFunc) Apply(ctx context.Context, e Event) bool
  • func (ff FilterFunc) Close()
  • func (ff FilterFunc) Run()
• type Formatter
  • func NewTextFormatter() Formatter
• type Logger
  • func (l *Logger) Alert(ctx context.Context, xs ...interface{})
  • func (l *Logger) Critical(ctx context.Context, xs ...interface{})
  • func (l *Logger) Debug(ctx context.Context, xs ...interface{})
  • func (l *Logger) Emergency(ctx context.Context, xs ...interface{})
  • func (l *Logger) Error(ctx context.Context, xs ...interface{})
  • func (l *Logger) Info(ctx context.Context, xs ...interface{})
  • func (l *Logger) Log(ctx context.Context, p Priority, xs ...interface{})
  • func (l *Logger) Notice(ctx context.Context, xs ...interface{})
  • func (l *Logger) Warning(ctx context.Context, xs ...interface{})
• type Priority
  • func (p Priority) String() string
• type TextFormatter
  • func (t *TextFormatter) Format(_ context.Context, e Event) ([]byte, error)
• type WriterFilter
  • func NewWriterFilter(out io.Writer, format Formatter) *WriterFilter
  • func (w *WriterFilter) Apply(ctx context.Context, e Event) bool
  • func (w *WriterFilter) Close()
  • func (w *WriterFilter) Run()

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 Alert

func Alert(ctx context.Context, xs ...interface{})

Alert sets the priority of this event to PriAlert

func Critical

func Critical(ctx context.Context, xs ...interface{})

Critical sets the priority of this event to PriCritical

func Debug

func Debug(ctx context.Context, xs ...interface{})

Debug sets the priority of this event to PriDebug

func Emergency

func Emergency(ctx context.Context, xs ...interface{})

Emergency sets the priority of this event to PriEmergency

func Error

func Error(ctx context.Context, xs ...interface{})

Error sets the priority of this event to PriError

func Info

func Info(ctx context.Context, xs ...interface{})

Info sets the priority of this event to PriInfo

func Notice

func Notice(ctx context.Context, xs ...interface{})

Notice sets the priority of this event to PriNotice

func Warning

func Warning(ctx context.Context, xs ...interface{})

Warning sets the priority of this event to PriWarning

Types

type Event

type Event struct {
	Pri     Priority
	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 (F) F

func (f F) F() map[string]interface{}

F ields for logging

type Fer

type Fer interface {
	F() map[string]interface{}
}

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 NewTextFormatter

func NewTextFormatter() Formatter

NewTextFormatter returns a Formatter that outputs as text.

type Logger

type Logger struct {
	Pri     Priority
	Filters []Filter
}

Logger holds the current priority and list of filters

var DefaultLogger *Logger

DefaultLogger is the default implementation of Logger

func (*Logger) Alert

func (l *Logger) Alert(ctx context.Context, xs ...interface{})

Alert sets the priority of this event to PriAlert

func (*Logger) Critical

func (l *Logger) Critical(ctx context.Context, xs ...interface{})

Critical sets the priority of this event to PriCritical

func (*Logger) Debug

func (l *Logger) Debug(ctx context.Context, xs ...interface{})

Debug sets the priority of this event to PriDebug

func (*Logger) Emergency

func (l *Logger) Emergency(ctx context.Context, xs ...interface{})

Emergency sets the priority of this event to PriEmergency

func (*Logger) Error

func (l *Logger) Error(ctx context.Context, xs ...interface{})

Error sets the priority of this event to PriError

func (*Logger) Info

func (l *Logger) Info(ctx context.Context, xs ...interface{})

Info sets the priority of this event to PriInfo

func (*Logger) Log

func (l *Logger) Log(ctx context.Context, p Priority, xs ...interface{})

Log is the generic logging method.

func (*Logger) Notice

func (l *Logger) Notice(ctx context.Context, xs ...interface{})

Notice sets the priority of this event to PriNotice

func (*Logger) Warning

func (l *Logger) Warning(ctx context.Context, xs ...interface{})

Warning sets the priority of this event to PriWarning

type Priority

type Priority int

Priority represents the importance of an Event.

const (
	// PriEmergency is the emergency priority, and is the highest.
	PriEmergency Priority = iota
	// PriAlert is the alert priority
	PriAlert
	// PriCritical is the critical priority
	PriCritical
	// PriError is the error priority.
	PriError
	// PriWarning is the warning priority
	PriWarning
	// PriNotice is the notice priority
	PriNotice
	// PriInfo is the info priority
	PriInfo
	// PriDebug is the debug priority.
	PriDebug
)

func (Priority) String

func (p Priority) String() string

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