log

package module
Version: v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2017 License: MIT Imports: 1 Imported by: 2

README

Build status Coverage GoReportCard API documentation

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}
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

View Source
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

func SetFactory

func SetFactory(f Factory)

SetFactory sets the static logger factory.

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 Error

func Error(err error) Logger

Error returns a new logger instance from the factory setting the error as supplied.

func Field

func Field(k string, v interface{}) Logger

Field returns a new logger instance from the factory setting a field value as supplied.

func Fields

func Fields(data map[string]interface{}) Logger

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.

func New

func New() Logger

New returns a new logger instance from the static factory.

type LoggerLevel

type LoggerLevel int

LoggerLevel defines level markers for log entries.

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

func Log(msg string) Tracer

Log constructs a new logger instance from the factory with no context and logs a message.

func Logf

func Logf(format string, v ...interface{}) Tracer

Logf constructs a new logger instance from the factory with no context and logs a formatted message.

func NewTracer

func NewTracer(logger Logger, start time.Time) Tracer

NewTracer creates a new tracer instance: assumed to be used by logger implementations when implementing the Log and Logf methods only.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL