2017-05-12 05:24:39 +00:00
# Zero Allocation JSON Logger
[](https://godoc.org/github.com/rs/zerolog) [](https://raw.githubusercontent.com/rs/zerolog/master/LICENSE) [](https://travis-ci.org/rs/zerolog) [](http://gocover.io/github.com/rs/zerolog)
2017-05-17 05:58:33 +00:00
The zerolog package provides a fast and simple logger dedicated to JSON output. It is inspired by uber's [zap ](https://godoc.org/go.uber.org/zap ) but with a simpler API and a smaller code base.
2017-05-12 05:24:39 +00:00
## Features
* Level logging
* Sampling
* Contextual fields
## Benchmark
2017-05-17 06:06:42 +00:00
All operations are allocation free (those numbers *include* JSON encoding):
2017-05-12 05:24:39 +00:00
```
2017-05-20 02:43:59 +00:00
BenchmarkLogEmpty-8 50000000 19.8 ns/op 0 B/op 0 allocs/op
BenchmarkDisabled-8 100000000 4.73 ns/op 0 B/op 0 allocs/op
BenchmarkInfo-8 10000000 85.1 ns/op 0 B/op 0 allocs/op
BenchmarkContextFields-8 10000000 81.9 ns/op 0 B/op 0 allocs/op
BenchmarkLogFields-8 5000000 247 ns/op 0 B/op 0 allocs/op
2017-05-12 05:24:39 +00:00
```
## Usage
```go
import "github.com/rs/zerolog/log"
```
### A global logger can be use for simple logging
```go
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` .
```go
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
```go
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
```go
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
```go
sublogger := log.With().
Str("component": "foo").
Logger()
sublogger.Info().Msg("hello world")
// Output: {"level":"info","time":1494567715,"message":"hello world","component":"foo"}
```
### Level logging
```go
2017-05-15 18:16:13 +00:00
zerolog.SetGlobalLevel(zerolog.InfoLevel)
2017-05-12 05:24:39 +00:00
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")
}
2017-05-18 07:10:45 +00:00
// Output: {"level":"info","time":1494567715,"message":"routed message"}
2017-05-12 05:24:39 +00:00
```
2017-05-18 07:10:45 +00:00
### Sub dictionary
```go
log.Info().
Str("foo", "bar").
Dict("dict", zerolog.Dict().
Str("bar", "baz").
Int("n", 1)
).Msg("hello world")
// Output: {"level":"info","time":1494567715,"foo":"bar","dict":{"bar":"baz","n":1},"message":"hello world"}
```
2017-05-12 05:24:39 +00:00
### Customize automatic field names
```go
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
```go
log.Log().Str("foo","bar").Msg("")
// Output: {"time":1494567715,"foo":"bar"}
```
### Add contextual fields to the global logger
```go
log.Logger = log.With().Str("foo", "bar").Logger()
```
### Log Sampling
```go
sampled := log.Sample(10)
sampled.Info().Msg("will be logged every 10 messages")
2017-05-17 05:42:57 +00:00
// Output: {"time":1494567715,"sample":10,"message":"will be logged every 10 messages"}
2017-05-12 05:24:39 +00:00
```
## 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).
2017-05-15 18:16:13 +00:00
* `zerolog.SetGlobalLevel` : Can raise the mimimum level of all loggers. Set this to `zerolog.Disable` to disable logging altogether (quiet mode).
* `zerolog.DisableSampling` : If argument is `true` , all sampled loggers will stop sampling and issue 100% of their log events.
2017-05-12 05:24:39 +00:00
* `zerolog.TimestampFieldName` : Can be set to customize `Timestamp` 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 customize `Err` field name.
* `zerolog.SampleFieldName` : Can be set to customize the field name added when sampling is enabled.
* `zerolog.TimeFieldFormat` : Can be set to customize `Time` 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 with `zerolog.TimestampFieldName` field name.
* `Time` : Add a field with the time formated with the `zerolog.TimeFieldFormat` .
* `Err` : Takes an `error` and render it as a string using the `zerolog.ErrorFieldName` field name.
