logger

README

Simple structured logger for Go

A simple logger package that provides levels, a number of output formats, and named sub-logs. Output formats include key/value, JSON, null and AMQP/RabbitMQ

Installation

Install using go get src.userspace.com.au/logger.

Documentation is available at http://godoc.org/src.userspace.com.au/logger

Usage

There is a package level logger that is set to level 'WARN'.

Create a key/value logger

log := logger.New(logger.Name("app"), logger.Level(logger.DEBUG))
log.Error("unable to do anything")

... [info] app: unable to do anything

Add structure

log.Warn("invalid something", "id", 344, "error", "generally broken")

... [warn] app: invalid something id=344 error="generally broken"

Create a named sub-logger

sublog := log.Named("database")
sublog.Info("connection initialised")

... [info] app.database: connection initialised

Create a new Logger with pre-defined values

For major sub-systems there is no need to repeat values for each log call:

reqID := "555"
msgLog := sublog.Field("request", reqID)
msgLog.Error("failed to process message")

... [info] app.database: failed to process message request=555

There is also a Log command with no defined level. These messages are always printed:

log.Log("metrics or whatnot", "something", large)

... metrics or whatnot something="12345678"

Comparison

BenchmarkCoreLogger-12           5000000               288 ns/op
BenchmarkLocal-12                2000000               654 ns/op
BenchmarkLogrus-12               1000000              1738 ns/op
BenchmarkFieldsLocal-12          1000000              1024 ns/op
BenchmarkFieldsLogrus-12         1000000              2061 ns/op

Documentation

Overview

Example (Nolevel)

keyValue, _ := kv.New(kv.SetTimeFormat(""))
log, _ := New(Writer(keyValue))
large := 12345678
log.Log("metrics or whatnot", "something", large)

Output:

metrics or whatnot something=12345678

Example (Structure)

keyValue, _ := kv.New(kv.SetTimeFormat(""))
log, _ := New(Writer(keyValue))
log.Warn("invalid something", "id", 344, "error", "generally broken")

Output:

[warn] invalid something id=344 error="generally broken"

Index

• func Debug(msg string, args ...interface{})
• func Error(msg string, args ...interface{})
• func Info(msg string, args ...interface{})
• func IsDebug() bool
• func IsInfo() bool
• func IsWarn() bool
• func SetLevel(lvl message.Level)
• func SetLevelAsString(lvl string)
• func SetWriter(w message.Writer)
• func Warn(msg string, args ...interface{})
• type Logger
  • func Field(k string, v interface{}) *Logger
  • func Named(n string) *Logger
  • func New(opts ...Option) (*Logger, error)
  • func (l *Logger) Debug(msg string, args ...interface{}) *Logger
  • func (l *Logger) Error(msg string, args ...interface{}) *Logger
  • func (l *Logger) Field(k string, v interface{}) *Logger
  • func (l *Logger) Info(msg string, args ...interface{}) *Logger
  • func (l *Logger) IsDebug() bool
  • func (l *Logger) IsInfo() bool
  • func (l *Logger) IsWarn() bool
  • func (l *Logger) Log(msg string, args ...interface{}) *Logger
  • func (l *Logger) LogAtLevel(lvl message.Level, msg string, args ...interface{}) *Logger
  • func (l *Logger) Named(n string) *Logger
  • func (l *Logger) SetLevel(lvl message.Level) *Logger
  • func (l *Logger) SetLevelAsString(lvl string) *Logger
  • func (l *Logger) Warn(msg string, args ...interface{}) *Logger
• type Option
  • func Level(lvl message.Level) Option
  • func LevelAsString(lvl string) Option
  • func Name(n string) Option
  • func Writer(f message.Writer) Option

Examples

• Package (Nolevel)
• Package (Structure)
• Field
• Level
• Named

Functions

func Debug

func Debug(msg string, args ...interface{})

Debug logs a debug message.

func Error

func Error(msg string, args ...interface{})

Error logs an error message.

func Info

func Info(msg string, args ...interface{})

Info logs an information message.

func IsDebug

func IsDebug() bool

IsDebug determines the debug status for a logger instance. Use this to conditionally execute blocks of code depending on the log verbosity.

func IsInfo

func IsInfo() bool

IsInfo determines the info status for a logger instance. Use this to conditionally execute blocks of code depending on the log verbosity.

func IsWarn

func IsWarn() bool

IsWarn determines the info status for a logger instance. Use this to conditionally execute blocks of code depending on the log verbosity.

func SetLevel

func SetLevel(lvl message.Level)

SetLevel enables changing the minimum level for a logger instance.

func SetLevelAsString

func SetLevelAsString(lvl string)

SetLevelAsString enables changing the minimum level for a logger instance.

func SetWriter

func SetWriter(w message.Writer)

SetWriter sets the writer for the default logger.

func Warn

func Warn(msg string, args ...interface{})

Warn logs an information message.

Types

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger is a simple levelled logger.

func Field

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

Field enables changing the default fields for a logger instance.

Example

jsonWriter, _ := json.New(json.SetTimeFormat(""))
log, _ := New(Name("app.database"), Writer(jsonWriter))
// Create a new Logger with pre-defined values
reqID := "555"
msgLog := log.Field("request", reqID)
msgLog.Error("failed to process message")

Output:

{"_level":"error","_message":"failed to process message","_name":"app.database","_time":"","request":"555"}

func Named

func Named(n string) *Logger

Named creates a new instance of a logger with a new name.

Example

keyValue, _ := kv.New(kv.SetTimeFormat(""))
log, _ := New(
	Name("database"),
	Writer(keyValue),
)
log.Error("connection initialised")

Output:

[error] database: connection initialised

func New

func New(opts ...Option) (*Logger, error)

New creates a new logger instance

func (*Logger) Debug

func (l *Logger) Debug(msg string, args ...interface{}) *Logger

Debug logs a debug message.

func (*Logger) Error

func (l *Logger) Error(msg string, args ...interface{}) *Logger

Error logs an error message.

func (*Logger) Field

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

Field enables changing the default fields for a logger instance.

func (*Logger) Info

func (l *Logger) Info(msg string, args ...interface{}) *Logger

Info logs an information message.

func (*Logger) IsDebug

func (l *Logger) IsDebug() bool

IsDebug determines the debug status for a logger instance. Use this to conditionally execute blocks of code depending on the log verbosity.

func (*Logger) IsInfo

func (l *Logger) IsInfo() bool

IsInfo determines the info status for a logger instance. Use this to conditionally execute blocks of code depending on the log verbosity.

func (*Logger) IsWarn

func (l *Logger) IsWarn() bool

IsWarn determines the info status for a logger instance. Use this to conditionally execute blocks of code depending on the log verbosity.

func (*Logger) Log

func (l *Logger) Log(msg string, args ...interface{}) *Logger

Log a message with no level.

func (*Logger) LogAtLevel

func (l *Logger) LogAtLevel(lvl message.Level, msg string, args ...interface{}) *Logger

LogAtLevel logs a message with a specified level.

func (*Logger) Named

func (l *Logger) Named(n string) *Logger

Named creates a new instance of a logger with a new name.

func (*Logger) SetLevel

func (l *Logger) SetLevel(lvl message.Level) *Logger

SetLevel enables changing the minimum level for a logger instance.

func (*Logger) SetLevelAsString

func (l *Logger) SetLevelAsString(lvl string) *Logger

SetLevelAsString enables changing the minimum level for a logger instance.

func (*Logger) Warn

func (l *Logger) Warn(msg string, args ...interface{}) *Logger

Warn logs an information message.

type Option

type Option func(*Logger) error

An Option configures a logger

func Level

func Level(lvl message.Level) Option

Level configures the minimum level to log.

Example

keyValue, _ := kv.New(kv.SetTimeFormat(""))
log, _ := New(
	Name("app"),
	Level(message.DEBUG),
	Writer(keyValue),
)
log.Error("unable to do anything")

Output:

[error] app: unable to do anything

func LevelAsString

func LevelAsString(lvl string) Option

LevelAsString configures the minimum level to log.

func Name

func Name(n string) Option

Name configures the name of the logger.

func Writer

func Writer(f message.Writer) Option

Writer add an output formatter for the logger.