lager

README

lager

lager is an opinionated logging library 🍺

Why?

lager only performs string formatting for log levels that you set. If you only want to log Error messages, you don't need to worry about all of your Trace or Debug strings being (costly) formatted.

Here's how the LogLager compares to log.Logger when you want to only log one level in your program instead of all.

BenchmarkLoggerOneAndAllLevels	  200000	      7842 ns/op	     605 B/op	      30 allocs/op
BenchmarkLogLagerOneLevel	 1000000	      2258 ns/op	     250 B/op	      15 allocs/op
BenchmarkLogLagerAllLevel	  200000	      7964 ns/op	     602 B/op	      35 allocs/op

Usage

The main interface that defines a logger is Lager:

type Lager interface {
	Tracef(msg string, v ...interface{})
	Debugf(msg string, v ...interface{})
	Infof(msg string, v ...interface{})
	Warnf(msg string, v ...interface{})
	Errorf(msg string, v ...interface{})
}

Lager provides logging for five levels: Trace, Debug, Info, Warn, and Error.

Currently, lager provides three Lager implementations:

• LogLager: A performant logger for logging directly to log.Logger
• BasicLager: A basic logger for log messages with customizable output
• ContextLager: A context logger for adding context to log messages with customizable output

Log outputs are defined by Drinker:

type Drinker interface {
	Drink(e interface{}) error
}

Currently, there are two Drinker implementations:

• LogDrinker: logs messages using log.Logger
• JSONDrinker: logs messages using json.Marshal

For more usage, see the tests and benchmarks.

Documentation

Index

• Variables
• func Debugf(msg string, v ...interface{})
• func Errorf(msg string, v ...interface{})
• func Infof(msg string, v ...interface{})
• func Tracef(msg string, v ...interface{})
• func Warnf(msg string, v ...interface{})
• type ContextConfig
  • func DefaultContextConfig() *ContextConfig
• type ContextLager
  • func Child() ContextLager
  • func NewContextLager(config *ContextConfig) ContextLager
  • func Set(key, value string) ContextLager
  • func SetDrinker(drinker Drinker) ContextLager
  • func SetFileType(fileType FileType) ContextLager
  • func SetLevels(levels *Levels) ContextLager
  • func SetStacktraces(on bool) ContextLager
  • func With(fields map[string]string) ContextLager
  • func WithError(err error) ContextLager
• type Drinker
  • func NewJSONDrinker(output io.Writer) Drinker
  • func NewLogDrinker(output io.Writer) Drinker
• type FileType
  • func (ft FileType) Caller(calldepth int) string
• type JSONDrinker
  • func (drkr *JSONDrinker) Drink(v map[string]interface{}) error
• type Lager
  • func NewLogLager(config *LogConfig) Lager
• type Level
  • func (i Level) String() string
• type Levels
  • func LevelsFromString(sLevels string) *Levels
  • func (lvls *Levels) All() *Levels
  • func (lvls *Levels) Contains(level Level) bool
  • func (lvls *Levels) Replace(level *Levels) *Levels
  • func (lvls *Levels) Set(level Level) *Levels
  • func (lvls *Levels) Unset(level Level) *Levels
• type LogConfig
  • func DefaultLogConfig() *LogConfig
• type LogDrinker
  • func (drkr *LogDrinker) Drink(v map[string]interface{}) error
• type LogLager
  • func (lgr *LogLager) Logf(level Level, msg string, v ...interface{})
• type NewDrinkerFunc
  • func DrinkerFromString(str string) (NewDrinkerFunc, error)

Variables

var ErrNoDrinker = errors.New("No Drinker")

ErrNoDrinker is used when a drinker cannot be returned, primarly DrinkerFromString

Functions

func Debugf

func Debugf(msg string, v ...interface{})

Debugf logs with level Debug using the package lager.

func Errorf

func Errorf(msg string, v ...interface{})

Errorf logs with level Error using the package lager.

func Infof

func Infof(msg string, v ...interface{})

Infof logs with level Info using the package lager.

func Tracef

func Tracef(msg string, v ...interface{})

Tracef logs with level Trace using the package lager.

func Warnf

func Warnf(msg string, v ...interface{})

Warnf logs with level Warn using the package lager.

Types

type ContextConfig

type ContextConfig struct {
	Levels      *Levels
	Drinker     Drinker
	Values      map[string]string
	Stacktraces bool
	FileType    FileType
}

ContextConfig is defines the configuration for ContextLager.

func DefaultContextConfig

func DefaultContextConfig() *ContextConfig

DefaultContextConfig creates a default ContextConfig

type ContextLager

type ContextLager interface {
	Lager
	With(map[string]string) ContextLager
	WithError(error) ContextLager
	Set(key, value string) ContextLager
	Child() ContextLager
}

ContextLager is a Lager that adds context to logs with key value pairs

func Child

func Child() ContextLager

Child creates a child ContextLager using the package lager as the parent. The child inherits all the parent values.

func NewContextLager

func NewContextLager(config *ContextConfig) ContextLager

NewContextLager creates a JSONLager

func Set

func Set(key, value string) ContextLager

Set sets a key to value in the lager map using the package lager.

func SetDrinker

func SetDrinker(drinker Drinker) ContextLager

SetDrinker sets the drinker of the package lager.

func SetFileType

func SetFileType(fileType FileType) ContextLager

SetFileType sets the fileType that is used for logs.

func SetLevels

func SetLevels(levels *Levels) ContextLager

SetLevels sets the levels of the package lager.

func SetStacktraces

func SetStacktraces(on bool) ContextLager

SetStacktraces sets whether stacktraces are captured on error.

func With

func With(fields map[string]string) ContextLager

With adds key values to the returned lager using the package lager.

func WithError

func WithError(err error) ContextLager

WithError adds an error key value to the returned lager if non nil, using the package lager.

type Drinker

type Drinker interface {
	Drink(v map[string]interface{}) error
}

Drinker will drink logs and output them

func NewJSONDrinker

func NewJSONDrinker(output io.Writer) Drinker

NewJSONDrinker creates a new JSON Drinker

func NewLogDrinker

func NewLogDrinker(output io.Writer) Drinker

NewLogDrinker creates a new Log Drinker

type FileType

type FileType uint8

FileType represents values for including file information of logs

const (
	// NoFile does not include the file name or line number of the log
	NoFile FileType = iota
	// ShortFile includes the file name and line number of the log
	ShortFile
	// PackageFile includes the file name, including package, and line number of the log
	PackageFile
	// FullFile includes the absolute file path and line number of the log
	FullFile
)

func (FileType) Caller

func (ft FileType) Caller(calldepth int) string

Caller returns the appropriate filename and line number of the file type

type JSONDrinker

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

JSONDrinker Drinks logs by outputting them to JSON

func (*JSONDrinker) Drink

func (drkr *JSONDrinker) Drink(v map[string]interface{}) error

Drink drinks logs

type Lager

type Lager interface {
	Tracef(msg string, v ...interface{})
	Debugf(msg string, v ...interface{})
	Infof(msg string, v ...interface{})
	Warnf(msg string, v ...interface{})
	Errorf(msg string, v ...interface{})
	SetLevels(levels *Levels)
	Levels() *Levels
}

Lager is a Lager that explicitly defines all of the log levels as log methods.

func NewLogLager

func NewLogLager(config *LogConfig) Lager

NewLogLager creates a new LogLager

type Level

type Level uint

Level represents a logging level

const (
	// Trace = a log level for tracing
	Trace Level = 1 << 5
	// Debug = a log level for debugging
	Debug Level = 1 << 4
	// Info = a log level for informational messages
	Info Level = 1 << 3
	// Warn = a log level for warnings
	Warn Level = 1 << 2
	// Error = a log level for errors
	Error Level = 1
)

func (Level) String

func (i Level) String() string

type Levels

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

Levels contains the log levels a logger will write to a Drinker

func LevelsFromString

func LevelsFromString(sLevels string) *Levels

LevelsFromString creates a levels object from a string Levels are specified using a capital letter corresponding to the first level of the desired level.

func (*Levels) All

func (lvls *Levels) All() *Levels

All sets all levels

func (*Levels) Contains

func (lvls *Levels) Contains(level Level) bool

Contains checks to see if a log level is contained in a logger

func (*Levels) Replace

func (lvls *Levels) Replace(level *Levels) *Levels

Replace changes it's value to match level

func (*Levels) Set

func (lvls *Levels) Set(level Level) *Levels

Set sets a log level

func (*Levels) Unset

func (lvls *Levels) Unset(level Level) *Levels

Unset removes a log level

type LogConfig

type LogConfig struct {
	Levels *Levels
	Output io.Writer
}

LogConfig represents for a Lager

func DefaultLogConfig

func DefaultLogConfig() *LogConfig

DefaultLogConfig is the default config

type LogDrinker

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

LogDrinker is a Drinker that uses log.Logger

func (*LogDrinker) Drink

func (drkr *LogDrinker) Drink(v map[string]interface{}) error

Drink drinks logs

type LogLager

type LogLager struct {
	Lager
	// contains filtered or unexported fields
}

LogLager implements Logger using *log.Logger

func (*LogLager) Logf

func (lgr *LogLager) Logf(level Level, msg string, v ...interface{})

Logf will log the given msg formatted with v if min is greater than or equal to the log level of LogLager

type NewDrinkerFunc

type NewDrinkerFunc func(output io.Writer) Drinker

NewDrinkerFunc creates a new drinker

func DrinkerFromString

func DrinkerFromString(str string) (NewDrinkerFunc, error)

DrinkerFromString provides a way to get a NewDrinkerFunc using a string. Useful for deciding on a Drinker using the environment.