README
¶
Structured log interface
Package log provides the separation of the logging interface from its
implementation and decouples the logger backend from your application. It defines
a simple, lightweight and comprehensive Logger and Factory interfaces which
can be used through your applications without any knowledge of the particular
implemeting backend and can be configured at the application wiring point to
bind a particular backend, such as Go's standard logger, apex/log, logrus,
with ease.
To complement the facade, the package github.com/teris-io/log/std provides an
implementation using the standard Go logger. The default log formatter for
this implementation uses colour coding for log levels and logs the date
leaving out the month and the year on the timestamp. However, the formatter
is fully configurable.
Similarly, the package github.com/teris-io/log/apex provides and implementation
using the apex/log logger backend.
Interface details
The Logger interface defines a facade for a structured leveled log:
type Logger interface {
Level(lvl LogLevel) Logger
Field(k string, v interface{}) Logger
Fields(data map[string]interface{}) Logger
Error(err error) Logger
Log(msg string) Tracer
Logf(format string, v ...interface{}) Tracer
}
The Factory defines a facade for the creation of logger instances and setting the
log output threshold for newly created instances:
type Factory interface {
New() Logger
Threshold(min LogLevel)
}
The package further defines three log levels differentiating between the (normally hidden)
Debug, (default) Info and (erroneous) Error.
Usage
The log can be used both statically by binding a particular logger factory:
func init() {
std.Use(os.Stderr, log.InfoLevel, std.DefaultFmtFun)
}
// elsewhere
logger := log.Level(log.InfoLevel).Field("key", "value")
logger.Log("message")
and dynamically by always going via a factory:
factory := std.NewFactory(os.Stderr, log.InfoLevel, std.DefaultFmtFun)
logger := factory.Level(log.InfoLevel).Field("key", "value")
logger.Log("message")
By default a NoOp (no-operation) implementation is bound to the static factory.
Tracing
To simplify debugging with execution time tracing, the Log and Logf methods
return a tracer that can be used to measure and log the execution time:
logger := log.Level(log.DebugLevel).Field("key", "value")
defer logger.Log("start").Trace()
// code to trace the execution time of
The above code snippet would output two log entries (provided the threshold permits)
the selected Debug level (her for the default formatter of the std logger):
08 16:31:42.023798 DBG start {key: value}
08 16:31:45.127619 DBG traced {duration: 3.103725832}, {key: value}
License and copyright
Copyright (c) 2017. Oleg Sklyar and teris.io. MIT license applies. All rights reserved.
Documentation
¶
Overview ¶
Package log defines the Logger interface for a structured leveled log, the Factory interface to create instances of the Logger and the Tracer interface used to trace and log the execution time since last Log.
The package further defines three log levels differentiating between the (normally hidden) Debug, (default) Info and (erroneous) Error.
The log can be used both statically by binding a particular logger factory, as in
std.Use(os.Stderr, log.Info, std.DefaultFmtFun)
logger := log.Level(log.Info).Field("key", "value")
logger.Log("message")
and dynamically by always going via a factory, as in
factory := std.NewFactory(os.Stderr, log.Info, std.DefaultFmtFun)
logger := factory.Level(log.Info).Field("key", "value")
logger.Log("message")
Index ¶
Constants ¶
const ( // UnsetLevel should not be output by logger implementation. UnsetLevel = iota - 2 // DebugLevel marks detailed output for design purposes. DebugLevel // InfoLevel is the default log output marker. InfoLevel // ErrorLevel marks an error output. ErrorLevel )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Factory ¶
type Factory interface {
//New creates a new logger.
New() Logger
// Threshold sets the minimum logger level threshold for messages to be output.
Threshold(min LoggerLevel)
}
Factory defines a utility to create new loggers and set the log level threshold.
type Logger ¶
type Logger interface {
// Level creates a new logger instance from the current one setting its log level to the value supplied.
Level(lvl LoggerLevel) Logger
// Field creates a new logger instance from the current one adding a new field value.
Field(k string, v interface{}) Logger
// Fields creates a new logger instance from the current one adding a collection of field values.
Fields(data map[string]interface{}) Logger
// Error creates a new logger instance from the current one adding an error
// and setting the level to ErrorLevel.
Error(err error) Logger
// Log outputs the log structure along with a message if the logger level is above or matching
// the threshold set in the factory.
Log(msg string) Tracer
// Logf outputs the log structure along with a formatted message if the logger level is above or
// matching the threshold set in the factory.
Logf(format string, v ...interface{}) Tracer
}
Logger defines the logger interface.
func Field ¶
Field returns a new logger instance from the factory setting a field value as supplied.
func Fields ¶
Fields returns a new logger instance from the factory setting field values as supplied.
func Level ¶
func Level(lvl LoggerLevel) Logger
Level returns a new logger instance from the factory setting its log level to the value supplied.
type Tracer ¶
type Tracer interface {
// Trace computes the time elapsed since the tracer was created. It then logs an entry
// with message "traced" and field "duration" amounting to the execution duration in seconds.
Trace() float64
}
Tracer defines a utility to trace execution time as returned by the logger Log and Logf methods.
func Log ¶
Log constructs a new logger instance from the factory with no context and logs a message.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apex provides a logger implementation using the github.com/apex/log backends.
|
Package apex provides a logger implementation using the github.com/apex/log backends. |
|
Package std provides a logger implementation via the Go built-in logger.
|
Package std provides a logger implementation via the Go built-in logger. |