README
¶
logfmtr
An implementation of the logr minimal logging API that writes in logfmt style.
Getting Started
This is a no frills logging package that follows the logr minimal logging API and by default writes logs in logfmt format, a line of space delimited key/value pairs.
level=0 logger=MyName ts=2020-09-20T14:31:10.905267839Z msg=hello user=you val1=1 val2=map[k:1]
level=1 logger=MyName ts=2020-09-20T14:31:10.905279546Z msg="you should see this" user=you
level=0 logger=MyName ts=2020-09-20T14:31:10.905288008Z msg="uh oh" error=<nil> user=you trouble=true reasons="[0.1 0.11 3.14]"
level=0 logger=MyName ts=2020-09-20T14:31:10.905291479Z msg=goodbye error="an error occurred" user=you code=-1
A more human friendly output format is also provided which can be configured using the humanize option:
0 info | 14:31:10.905297 | hello logger=MyName user=you val1=1 val2=map[k:1]
1 info | 14:31:10.905302 | you should see this logger=MyName user=you
0 error | 14:31:10.905307 | uh oh logger=MyName error=<nil> user=you trouble=true reasons="[0.1 0.11 3.14]"
0 error | 14:31:10.905311 | goodbye logger=MyName error="an error occurred" user=you code=-1
Loggers defer applying their configuration until they are used. The logger is instantiated when either Info, Error or Enabled is called. At that point the logger will read and use any options set from a prior call to UseOptions.
package main
import (
"github.com/iand/logfmtr"
)
func main() {
// Set options that all loggers will be based on
opts := logfmtr.DefaultOptions()
opts.Humanize = true
opts.AddCaller = true
logfmtr.UseOptions(opts)
}
Any new loggers will use the options set in main when they first start logging.
package worker
import (
"github.com/iand/logfmtr"
)
// Create the logger
var logger = logfmtr.New().WithName("worker")
func doWork() }
// Logger is instantiated with the options set earlier
logger.Info("the sun is shining")
}
Loggers can be created with specific configuration by using NewWithOptions:
func otherWork() }
opts := logfmtr.DefaultOptions()
opts.Writer = os.Stderr
logger := logfmtr.NewWithOptions(opts)
logger.Info("important system information")
}
Several predefined keys are used when writing logs in logfmt style:
- msg - the log message
- error - error message passed to the
Errormethod - logger - the name of the logger writing the log entry
- level - the verbosity level of the logger writing the log entry
- caller - filename and line number of the origin of the log entry
Author
License
This is free and unencumbered software released into the public domain. Anyone is free to
copy, modify, publish, use, compile, sell, or distribute this software, either in source
code form or as a compiled binary, for any purpose, commercial or non-commercial, and by
any means. For more information, see http://unlicense.org/ or the
accompanying UNLICENSE file.
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DisableLogger ¶ added in v0.2.0
func DisableLogger(name string)
Example ¶
package main
import (
"github.com/iand/logfmtr"
)
func main() {
// Create the logger with a name
logger := logfmtr.NewNamed("europa")
// It logs normally
logger.Info("the sun is shining")
// Disable the logger
logfmtr.DisableLogger("europa")
logger.Info("the sun not shining now")
}
Output:
func EnableLogger ¶ added in v0.2.0
func EnableLogger(name string)
func New ¶
New returns a deferred logger that writes in logfmt using the default options. The logger defers configuring its options until it is instantiated with the first call to Info, Error or Enabled or the first call to those function on any child loggers created via V, WithName or WithValues.
Example ¶
package main
import (
"github.com/iand/logfmtr"
)
func main() {
// Create the logger with deferred options
logger := logfmtr.New()
// Later on set options that all loggers will be based on
opts := logfmtr.DefaultOptions()
opts.Humanize = true
logfmtr.UseOptions(opts)
// Logger is instantiated with the options
logger.Info("the sun is shining")
}
Output:
func NewNamed ¶ added in v0.2.0
NewNamed returns a deferred logger with the given name that writes in logfmt using the default options.
Example ¶
package main
import (
"github.com/iand/logfmtr"
)
func main() {
// Create the logger with a name
logger := logfmtr.NewNamed("europa")
logger.Info("the sun is shining")
}
Output:
func NewWithOptions ¶
NewWithOptions returns an instantiated logger that writes in logfmt using the supplied options. Panics if no writer is supplied in the options.
Example ¶
package main
import (
"github.com/iand/logfmtr"
)
func main() {
opts := logfmtr.DefaultOptions()
opts.Humanize = true
logger := logfmtr.NewWithOptions(opts)
logger.Info("the sun is shining")
}
Output:
func SetVerbosity ¶
SetVerbosity sets the global log level. Only loggers with a V level less than or equal to this value will be enabled.
func UseOptions ¶ added in v0.2.0
func UseOptions(opts Options)
UseOptions sets options that new loggers will use when it they are instantiated.
Types ¶
type Options ¶
type Options struct {
// Writer is where logs will be written to
Writer io.Writer
// Humanize changes the log output to a human friendly format
Humanize bool
// Colorize adds color to the log output. Only applies if Humanize is also true.
Colorize bool
// TimestampFormat sets the format for log timestamps. Set to empty to disable timestamping
// of log messages. Humanize uses a fixed short timestamp format.
TimestampFormat string
// NameDelim is the delimiter character used when appending names of loggers.
NameDelim string
// AddCaller indicates that log messages should include the file and line number of the caller of the logger.
AddCaller bool
// CallerSkip adds frames to skip when determining the caller of the logger. Useful when the logger is wrapped
// by another logger.
CallerSkip int
}
Options contains fields and flags for customizing logger behaviour
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns the default options used by New unless overridden by a call to UseOptions. Override the option field to customise behaviour and then pass to UseOptions or NewWithOptions.
Source Files
Directories