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.

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

    View Source
    var (
    	// DefaultTimeFormat represents the way in which time will be formatted by default
    	DefaultTimeFormat = time.RFC3339
    )
    View Source
    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
                                                                                    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.