slog

README

The reference SLF implementation for Go

The module ventu-io/slog provides a reference implementation of the structured logging facade (SLF) for Go. The following are the main characteristics of this implementation:

• log levels can be set per context, to the root context or to all context;
• defines generic Entry and EntryHandler interfaces enabling adding arbitrary handlers;
• permits concurrent (default) or sequential processing of each log entry by each entry handler;
• defines a basic entry handler for logging into text files or terminal, which is fully parametrisable via a template (via the standard Go text/template)
• defines a JSON log entry handler for formatting JSON into a consumer (io.Writer)
• delivers about 1mil log entries to log entry handlers on conventional hardware concurrently or sequentially
• handles locking of contexts and handlers

More handlers will follow in due course.

The factory API

The factory API is fairly straightforward and self explanatory. It is based on the slf.LogFactory adding just a few convenience method to set the level and define handers:

type LogFactory interface {
    slf.LogFactory

    // SetLevel sets the logging slf.Level to given contexts, all loggers if no 
    // context given, or the root logger when context defined as "root".
    SetLevel(level slf.Level, contexts ...string)

    // SetCallerInfo sets the logging slf.CallerInfo to given contexts, all loggers if no context given,
    // or the root logger when context defined as "root".
    SetCallerInfo(callerInfo slf.CallerInfo, contexts ...string)

    // AddEntryHandler adds a handler for log entries that are logged at or above 
    // the set log slf.Level.
    AddEntryHandler(handler EntryHandler)

    // SetEntryHandlers sets a collection of handlers for log entries that are logged 
    // at or above the set log slf.Level.
    SetEntryHandlers(handlers ...EntryHandler)

    // Contexts retruns the currently defined collection of context loggers.
    Contexts() map[string]slf.StructuredLogger

    // SetConcurrent toggles concurrent execution of handler methods on log entries. 
    // Default is to log each entry non-concurrently, one after another.
    SetConcurrent(conc bool)
}

Usage

This covers the initialisation only, otherwise see slf. At the application initialisation:

func init() {
    // define a basic stderr log entry handler
    bh := basic.New()
    // optionally define the format (this here is the default one)
    bh.SetTemplate("{{.Time}} [\033[{{.Color}}m{{.Level}}\033[0m] {{.Context}}{{if .Caller}} ({{.Caller}}){{end}}: {{.Message}}{{if .Error}} (\033[31merror: {{.Error}}\033[0m){{end}} {{.Fields}}")


			// initialise and configure the SLF implementation
    lf := slog.New()
    // set common log level to INFO
    lf.SetLevel(slf.LevelInfo)
    // set log level for specific contexts to DEBUG
    lf.SetLevel(slf.LevelDebug, "app.package1", "app.package2")
    lf.AddEntryHandler(bh)
    lf.AddEntryHandler(json.New(os.Stderr))

    // make this into the one used by all the libraries
    slf.Set(lf) 
}

Output of the basic and json handlers

Given the above setup the log output of the application can look like this:

• for the JSON logger:

    {
      "timestamp": "2016-03-26T17:41:14.5517",
      "level": "WARN",
      "message": "Error while subscribing. Retrying in 30s",
      "error": "read: connection reset by peer",
      "fields": {
        "context": "probe.agent.task.Subscribe"
      }
    } 
  

• for the basic text logger (with coloured INFO if output to a terminal):

    17:41:14.551 [WARN] probe.agent.task.Subscribe: Error while subscribing. Retrying in 30s (error: read: connection reset by peer)
  

  

 Changelog

• 26.03.2016: Initial release
• 30.04.2016:
  • API: Added Fatal and Fatalf (matches SLF)
  • API: Added SetCallerInfo as the top-level initialization for all or selected loggers
  • Behaviour: concurrent=false by default
  • Fix: Log(LevelPanic, ...) triggers panic just as Panic and Panicf
  • Fix: Stopped JSON handler from outputting error: "null" on no error

License

Copyright (c) 2016 Ventu.io, Oleg Sklyar, contributors.

Distributed under a MIT style license found in the LICENSE file.

Documentation

Index

• Constants
• Variables
• type Entry
• type EntryHandler
• type LogFactory
  • func New() LogFactory

Constants

const (
	// TraceField defined the key for the field to store trace duration.
	TraceField = "trace"

	// CallerField defines the key for the caller information.
	CallerField = "caller"

	// ErrorField can be used by handlers to represent the error in the data field collection.
	ErrorField = "error"
)

const (
	// ContextField defines the field name to store context.
	ContextField = "context"
)

Variables

var (

	// ExitProcessor is executed on Log(LevelFatal) to terminate the application.
	ExitProcessor = func(message string) {
		os.Exit(1)
	}
)

Types

type Entry

type Entry interface {

	// Time represents entry time stamp.
	Time() time.Time

	// Level represents the log level.
	Level() slf.Level

	// Message reresents the log formatted message.
	Message() string

	// Error, if present, represents the error to be logged along with the message and the fields.
	Error() error

	// Fields represents structured log information.
	Fields() map[string]interface{}
}

Entry represents a log entry for structured logging. Entries are only created when the requested level is same or above the minimum log level of the context root.

type EntryHandler

type EntryHandler interface {

	// Handle processes a filtered log entry (must not write to the entry field map, which is
	// read concurrently by all handlers).
	Handle(Entry) error
}

EntryHandler processes filtered log entries in independent go-routines.

type LogFactory

type LogFactory interface {
	slf.LogFactory
	SetLevel(level slf.Level, contexts ...string)
	SetCallerInfo(callerInfo slf.CallerInfo, contexts ...string)
	AddEntryHandler(handler EntryHandler)
	SetEntryHandlers(handlers ...EntryHandler)
	Contexts() map[string]slf.StructuredLogger
	SetConcurrent(conc bool)
}

LogFactory extends the SLF LogFactory interface with a series of methods specific to the slog implementation.

func New

func New() LogFactory

New constructs a new logger conforming with SLF.