README
¶
log
The log package provides a simple leveled logger for use in Cobalt's applications and libraries. See package documentation.
Documentation
¶
Overview ¶
Package log provides a Logger interface that may be used in libaries to allow four logging levels: Error, Info, Debug, and Trace. It also provides two implementations of that interface. The LeveledLogger and DiscardLogger. The LevelLogger is meant to be initialized by main packages and registered with imported packages. The DiscardLogger is meant to be initialized in libraries as a no-op logger in case the main package never provides any logger.
Example ¶
package main
import (
"github.com/cobaltspeech/log"
"github.com/cobaltspeech/log/pkg/level"
)
func main() {
// Create a leveled logger
logger := log.NewLeveledLogger()
// Provide the logger to library functions
Divide(logger, 5, 0)
// Change the logging level at runtime
logger.SetFilterLevel(level.Debug | level.Info | level.Error)
// Create a contextual logger to automatically add keyval pairs for all log messages
engLogger := log.With(logger, "module", "engine")
// Provide the logger to constructors that support the Logger interface
e := NewEngine(engLogger)
e.Run()
}
// Divide supports the Logger interface and uses it to report events when
// performing the division of given arguments. It uses the DiscardLogger if a
// valid logger was not provided. Library functions can use such a signature to
// support the logger.
func Divide(l log.Logger, a, b int) int {
if l == nil {
l = log.NewDiscardLogger()
}
l.Trace("msg", "entering Divide()")
defer l.Trace("msg", "exiting Divide()")
if b == 0 {
l.Error(
"msg", "attempt to divide by zero",
"a", a,
"b", b)
return 0
}
return a / b
}
// Engine is an example type that supports the logging interface for use it its methods.
type Engine struct {
log log.Logger
}
// NewEngine returns an initialized Engine configured with the provided logger.
// If a nil logger is provided, it uses the DiscardLogger.
func NewEngine(l log.Logger) *Engine {
if l == nil {
l = log.NewDiscardLogger()
}
return &Engine{l}
}
// Run uses the configured logger to report events.
func (e *Engine) Run() {
e.log.Debug("msg", "running engine")
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DiscardLogger ¶
type DiscardLogger struct{}
DiscardLogger implements the Logger interface and ignores all logging messages.
func NewDiscardLogger ¶
func NewDiscardLogger() *DiscardLogger
func (*DiscardLogger) Debug ¶
func (l *DiscardLogger) Debug(keyvals ...interface{})
func (*DiscardLogger) Error ¶
func (l *DiscardLogger) Error(keyvals ...interface{})
func (*DiscardLogger) Info ¶
func (l *DiscardLogger) Info(keyvals ...interface{})
func (*DiscardLogger) Trace ¶
func (l *DiscardLogger) Trace(keyvals ...interface{})
type LeveledLogger ¶
type LeveledLogger struct {
// contains filtered or unexported fields
}
LeveledLogger implements the Logger interface and uses the go stdlib log package to perform logging. Each log message has a level prefix followed by JSON representation of the data being logged.
func NewLeveledLogger ¶
func NewLeveledLogger(opts ...Option) *LeveledLogger
NewLeveledLogger returns a new Leveledlogger that writes Error and Info messages to stderr. These defaults can be changed by providing Options.
func (*LeveledLogger) Debug ¶
func (l *LeveledLogger) Debug(keyvals ...interface{})
Debug sends the given key value pairs to the debug logger.
func (*LeveledLogger) Error ¶
func (l *LeveledLogger) Error(keyvals ...interface{})
Error sends the given key value pairs to the error logger.
func (*LeveledLogger) Info ¶
func (l *LeveledLogger) Info(keyvals ...interface{})
Info sends the given key value pairs to the info logger.
func (*LeveledLogger) SetFilterLevel ¶
func (l *LeveledLogger) SetFilterLevel(lvl level.Level)
SetFilterLevel changes the level of the given logger, at runtime, to the provided level. An application may want to do this to enable debugging messages in production, without shutting down and reconfiguring the logger.
This method is expected to be called rarely, and it does not use mutexes to lock the level change operations. Applications may observe temporarily indeterminate filtering behavior when this method is called concurrently with other logging methods.
func (*LeveledLogger) Trace ¶
func (l *LeveledLogger) Trace(keyvals ...interface{})
Trace sends the given key value pairs to the trace logger.
type Logger ¶
type Logger interface {
Error(keyvals ...interface{})
Info(keyvals ...interface{})
Debug(keyvals ...interface{})
Trace(keyvals ...interface{})
}
Logger allows imported Cobalt packages to write logs of the standard four levels to a logger provided by the main package. This interface means that the logger may be any implementation of logger so long as it provides--or is wrapped by a struct that provides--these four functions.
type Option ¶
type Option func(*LeveledLogger)
func WithFilterLevel ¶
WithFilterLevel configures the new LeveledLogger being created to only log messages with the specified logging levels.
func WithLogger ¶
WithLogger returns an Option that configures the LeveledLogger to use the provided log.Logger from go's stdlib package. Do not combine with WithOutput.
func WithOutput ¶
WithOutput returns an Option that configures the LeveledLogger to write all log messages to the given Writer. Do not combine with WithLogger.
Source Files
Directories