5409743185 | ||
---|---|---|
log | ||
.gitignore | ||
.travis.yml | ||
LICENSE | ||
README.md | ||
benchmark_test.go | ||
context.go | ||
event.go | ||
field.go | ||
globals.go | ||
json.go | ||
log.go | ||
log_example_test.go | ||
log_test.go | ||
syslog.go | ||
syslog_test.go | ||
writer.go | ||
writer_test.go |
README.md
Zero Allocation JSON Logger
The zerolog package provides a fast and simple logger dedicated to JSON output. It is inspired by uber's zap but with a simpler API and a smaller code base.
Features
- Level logging
- Sampling
- Contextual fields
Benchmark
All operations are allocation free (those numbers include JSON encoding):
BenchmarkLogEmpty-8 50000000 22 ns/op 0 B/op 0 allocs/op
BenchmarkDisabled-8 100000000 10 ns/op 0 B/op 0 allocs/op
BenchmarkInfo-8 10000000 210 ns/op 0 B/op 0 allocs/op
BenchmarkContextFields-8 10000000 254 ns/op 0 B/op 0 allocs/op
BenchmarkLogFields-8 5000000 377 ns/op 0 B/op 0 allocs/op
Usage
import "github.com/rs/zerolog/log"
A global logger can be use for simple logging
log.Info().Msg("hello world")
// Output: {"level":"info","time":1494567715,"message":"hello world"}
NOTE: To import the global logger, import the log
subpackage github.com/rs/zerolog/log
.
log.Fatal().
Err(err).
Str("service", service).
Msgf("Cannot start %s", service)
// Output: {"level":"fatal","time":1494567715,"message":"Cannot start myservice","error":"some error","service":"myservice"}
// Exit 1
NOTE: Using Msgf
generates an allocation even when the logger is disabled.
Fields can be added to log messages
log.Info().
Str("foo", "bar").
Int("n", 123).
Msg("hello world")
// Output: {"level":"info","time":1494567715,"foo":"bar","n":123,"message":"hello world"}
Create logger instance to manage different outputs
logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
logger.Info().Str("foo", "bar").Msg("hello world")
// Output: {"level":"info","time":1494567715,"message":"hello world","foo":"bar"}
Sub-loggers let you chain loggers with additional context
sublogger := log.With().
Str("component": "foo").
Logger()
sublogger.Info().Msg("hello world")
// Output: {"level":"info","time":1494567715,"message":"hello world","component":"foo"}
Level logging
zerolog.SetGlobalLevel(zerolog.InfoLevel)
log.Debug().Msg("filtered out message")
log.Info().Msg("routed message")
if e := log.Debug(); e.Enabled() {
// Compute log output only if enabled.
value := compute()
e.Str("foo": value).Msg("some debug message")
}
// Output: {"level":"info","time":1494567715,"routed message"}
Customize automatic field names
zerolog.TimestampFieldName = "t"
zerolog.LevelFieldName = "l"
zerolog.MessageFieldName = "m"
log.Info().Msg("hello world")
// Output: {"l":"info","t":1494567715,"m":"hello world"}
Log with no level nor message
log.Log().Str("foo","bar").Msg("")
// Output: {"time":1494567715,"foo":"bar"}
Add contextual fields to the global logger
log.Logger = log.With().Str("foo", "bar").Logger()
Log Sampling
sampled := log.Sample(10)
sampled.Info().Msg("will be logged every 10 messages")
// Output: {"time":1494567715,"sample":10,"message":"will be logged every 10 messages"}
Global Settings
Some settings can be changed and will by applied to all loggers:
log.Logger
: You can set this value to customize the global logger (the one used by package level methods).zerolog.SetGlobalLevel
: Can raise the mimimum level of all loggers. Set this tozerolog.Disable
to disable logging altogether (quiet mode).zerolog.DisableSampling
: If argument istrue
, all sampled loggers will stop sampling and issue 100% of their log events.zerolog.TimestampFieldName
: Can be set to customizeTimestamp
field name.zerolog.LevelFieldName
: Can be set to customize level field name.zerolog.MessageFieldName
: Can be set to customize message field name.zerolog.ErrorFieldName
: Can be set to customizeErr
field name.zerolog.SampleFieldName
: Can be set to customize the field name added when sampling is enabled.zerolog.TimeFieldFormat
: Can be set to customizeTime
field value formatting.
Field Types
Standard Types
Str
Bool
Int
,Int8
,Int16
,Int32
,Int64
Uint
,Uint8
,Uint16
,Uint32
,Uint64
Float32
,Float64
Advanced Fields
Timestamp
: Insert UNIX timestamp field withzerolog.TimestampFieldName
field name.Time
: Add a field with the time formated with thezerolog.TimeFieldFormat
.Err
: Takes anerror
and render it as a string using thezerolog.ErrorFieldName
field name.