Who uses zerolog

Features

Installation

go get -u github.com/rs/zerolog/log

Getting Started

Simple Logging Example

package mainimport ("github.com/rs/zerolog""github.com/rs/zerolog/log")funcmain() {// UNIX Time is faster and smaller than most timestampszerolog.TimeFieldFormat=zerolog.TimeFormatUnixlog.Print("hello world")}// Output: {"time":1516134303,"level":"debug","message":"hello world"}

Contextual Logging

package mainimport ("github.com/rs/zerolog""github.com/rs/zerolog/log")funcmain() {zerolog.TimeFieldFormat=zerolog.TimeFormatUnixlog.Debug().Str("Scale","833 cents").Float64("Interval",833.09).Msg("Fibonacci is everywhere")log.Debug().Str("Name","Tom").Send()}// Output: {"level":"debug","Scale":"833 cents","Interval":833.09,"time":1562212768,"message":"Fibonacci is everywhere"}// Output: {"level":"debug","Name":"Tom","time":1562212768}

Leveled Logging

Simple Leveled Logging Example

package mainimport ("github.com/rs/zerolog""github.com/rs/zerolog/log")funcmain() {zerolog.TimeFieldFormat=zerolog.TimeFormatUnixlog.Info().Msg("hello world")}// Output: {"time":1516134303,"level":"info","message":"hello world"}

Setting Global Log Level

package mainimport ("flag""github.com/rs/zerolog""github.com/rs/zerolog/log")funcmain() {zerolog.TimeFieldFormat=zerolog.TimeFormatUnixdebug:=flag.Bool("debug",false,"sets log level to debug")flag.Parse()// Default level for this example is info, unless debug flag is presentzerolog.SetGlobalLevel(zerolog.InfoLevel)if*debug {zerolog.SetGlobalLevel(zerolog.DebugLevel)    }log.Debug().Msg("This message appears only when log level set to Debug")log.Info().Msg("This message appears when log level set to Debug or Info")ife:=log.Debug();e.Enabled() {// Compute log output only if enabled.value:="bar"e.Str("foo",value).Msg("some debug message")    }}

$ ./logLevelExample{"time":1516387492,"level":"info","message":"This message appears when log level set to Debug or Info"}

$ ./logLevelExample -debug{"time":1516387573,"level":"debug","message":"This message appears only when log level set to Debug"}{"time":1516387573,"level":"info","message":"This message appears when log level set to Debug or Info"}{"time":1516387573,"level":"debug","foo":"bar","message":"some debug message"}

Logging without Level or Message

package mainimport ("github.com/rs/zerolog""github.com/rs/zerolog/log")funcmain() {zerolog.TimeFieldFormat=zerolog.TimeFormatUnixlog.Log().Str("foo","bar").Msg("")}// Output: {"time":1494567715,"foo":"bar"}

Error Logging

package mainimport ("errors""github.com/rs/zerolog""github.com/rs/zerolog/log")funcmain() {zerolog.TimeFieldFormat=zerolog.TimeFormatUnixerr:=errors.New("seems we have an error here")log.Error().Err(err).Msg("")}// Output: {"level":"error","error":"seems we have an error here","time":1609085256}

Error Logging with Stacktrace

package mainimport ("github.com/pkg/errors""github.com/rs/zerolog/pkgerrors""github.com/rs/zerolog""github.com/rs/zerolog/log")funcmain() {zerolog.TimeFieldFormat=zerolog.TimeFormatUnixzerolog.ErrorStackMarshaler=pkgerrors.MarshalStackerr:=outer()log.Error().Stack().Err(err).Msg("")}funcinner()error {returnerrors.New("seems we have an error here")}funcmiddle()error {err:=inner()iferr!=nil {returnerr}returnnil}funcouter()error {err:=middle()iferr!=nil {returnerr}returnnil}// Output: {"level":"error","stack":[{"func":"inner","line":"20","source":"errors.go"},{"func":"middle","line":"24","source":"errors.go"},{"func":"outer","line":"32","source":"errors.go"},{"func":"main","line":"15","source":"errors.go"},{"func":"main","line":"204","source":"proc.go"},{"func":"goexit","line":"1374","source":"asm_amd64.s"}],"error":"seems we have an error here","time":1609086683}

Logging Fatal Messages

package mainimport ("errors""github.com/rs/zerolog""github.com/rs/zerolog/log")funcmain() {err:=errors.New("A repo man spends his life getting into tense situations")service:="myservice"zerolog.TimeFieldFormat=zerolog.TimeFormatUnixlog.Fatal().Err(err).Str("service",service).Msgf("Cannot start %s",service)}// Output: {"time":1516133263,"level":"fatal","error":"A repo man spends his life getting into tense situations","service":"myservice","message":"Cannot start myservice"}//         exit status 1

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"}

Pretty logging

log.Logger=log.Output(zerolog.ConsoleWriter{Out:os.Stderr})log.Info().Str("foo","bar").Msg("Hello world")// Output: 3:04PM INF Hello World foo=bar

output:= zerolog.ConsoleWriter{Out:os.Stdout,TimeFormat:time.RFC3339}output.FormatLevel=func(iinterface{})string {returnstrings.ToUpper(fmt.Sprintf("| %-6s|",i))}output.FormatMessage=func(iinterface{})string {returnfmt.Sprintf("***%s****",i)}output.FormatFieldName=func(iinterface{})string {returnfmt.Sprintf("%s:",i)}output.FormatFieldValue=func(iinterface{})string {returnstrings.ToUpper(fmt.Sprintf("%s",i))}log:=zerolog.New(output).With().Timestamp().Logger()log.Info().Str("foo","bar").Msg("Hello World")// Output: 2006-01-02T15:04:05Z07:00 | INFO  | ***Hello World**** foo:BAR

output:= zerolog.ConsoleWriter{Out:os.Stdout,NoColor:true,PartsOrder:    []string{"level","one","two","three","message"},FieldsExclude: []string{"one","two","three"}}output.FormatLevel=func(iinterface{})string {returnstrings.ToUpper(fmt.Sprintf("%-6s",i)) }output.FormatFieldName=func(iinterface{})string {returnfmt.Sprintf("%s:",i) }output.FormatPartValueByName=func(iinterface{},sstring)string {varretstringswitchs {case"one":ret=strings.ToUpper(fmt.Sprintf("%s",i))case"two":ret=strings.ToLower(fmt.Sprintf("%s",i))case"three":ret=strings.ToLower(fmt.Sprintf("(%s)",i))    }returnret}log:=zerolog.New(output)log.Info().Str("foo","bar").Str("two","TEST_TWO").Str("one","test_one").Str("three","test_three").Msg("Hello World")// Output: INFO   TEST_ONE test_two (test_three) Hello World foo:bar

Sub dictionary

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"}

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"}

Add contextual fields to the global logger

log.Logger=log.With().Str("foo","bar").Logger()

Add file and line number to log

log.Logger=log.With().Caller().Logger()log.Info().Msg("hello world")// Output: {"level": "info", "message": "hello world", "caller": "/go/src/your_project/some_file:21"}

zerolog.CallerMarshalFunc=func(pcuintptr,filestring,lineint)string {returnfilepath.Base(file)+":"+strconv.Itoa(line)}log.Logger=log.With().Caller().Logger()log.Info().Msg("hello world")// Output: {"level": "info", "message": "hello world", "caller": "some_file:21"}

Thread-safe, lock-free, non-blocking writer

wr:=diode.NewWriter(os.Stdout,1000,10*time.Millisecond,func(missedint) {fmt.Printf("Logger Dropped %d messages",missed)})log:=zerolog.New(wr)log.Print("test")

Log Sampling

sampled:=log.Sample(&zerolog.BasicSampler{N:10})sampled.Info().Msg("will be logged every 10 messages")// Output: {"time":1494567715,"level":"info","message":"will be logged every 10 messages"}

// Will let 5 debug messages per period of 1 second.// Over 5 debug message, 1 every 100 debug messages are logged.// Other levels are not sampled.sampled:=log.Sample(zerolog.LevelSampler{DebugSampler:&zerolog.BurstSampler{Burst:5,Period:1*time.Second,NextSampler:&zerolog.BasicSampler{N:100},    },})sampled.Debug().Msg("hello world")// Output: {"time":1494567715,"level":"debug","message":"hello world"}

Hooks

typeSeverityHookstruct{}func (hSeverityHook)Run(e*zerolog.Event,level zerolog.Level,msgstring) {iflevel!=zerolog.NoLevel {e.Str("severity",level.String())    }}hooked:=log.Hook(SeverityHook{})hooked.Warn().Msg("")// Output: {"level":"warn","severity":"warn"}

Pass a sub-logger by context

ctx:=log.With().Str("component","module").Logger().WithContext(ctx)log.Ctx(ctx).Info().Msg("hello world")// Output: {"component":"module","level":"info","message":"hello world"}

Set as standard logger output

log:=zerolog.New(os.Stdout).With().Str("foo","bar").Logger()stdlog.SetFlags(0)stdlog.SetOutput(log)stdlog.Print("hello world")// Output: {"foo":"bar","message":"hello world"}

context.Context integration

funcf() {logger:=zerolog.New(os.Stdout)ctx:=context.Background()// Attach the Logger to the context.Contextctx=logger.WithContext(ctx)someFunc(ctx)}funcsomeFunc(ctx context.Context) {// Get Logger from the go Context. if it's nil, then// `zerolog.DefaultContextLogger` is returned, if// `DefaultContextLogger` is nil, then a disabled logger is returned.logger:=zerolog.Ctx(ctx)logger.Info().Msg("Hello")}

typeTracingHookstruct{}func (hTracingHook)Run(e*zerolog.Event,level zerolog.Level,msgstring) {ctx:=e.GetCtx()spanId:=getSpanIdFromContext(ctx)// as per your tracing frameworke.Str("span-id",spanId)}funcf() {// Setup the loggerlogger:=zerolog.New(os.Stdout)logger=logger.Hook(TracingHook{})ctx:=context.Background()// Use the Ctx function to make the context available to the hooklogger.Info().Ctx(ctx).Msg("Hello")}

Integration withnet/http

log:=zerolog.New(os.Stdout).With().Timestamp().Str("role","my-service").Str("host",host).Logger()c:=alice.New()// Install the logger handler with default output on the consolec=c.Append(hlog.NewHandler(log))// Install some provided extra handler to set some request's context fields.// Thanks to that handler, all our logs will come with some prepopulated fields.c=c.Append(hlog.AccessHandler(func(r*http.Request,status,sizeint,duration time.Duration) {hlog.FromRequest(r).Info().Str("method",r.Method).Stringer("url",r.URL).Int("status",status).Int("size",size).Dur("duration",duration).Msg("")}))c=c.Append(hlog.RemoteAddrHandler("ip"))c=c.Append(hlog.UserAgentHandler("user_agent"))c=c.Append(hlog.RefererHandler("referer"))c=c.Append(hlog.RequestIDHandler("req_id","Request-Id"))// Here is your final handlerh:=c.Then(http.HandlerFunc(func(w http.ResponseWriter,r*http.Request) {// Get the logger from the request's context. You can safely assume it// will be always there: if the handler is removed, hlog.FromRequest// will return a no-op logger.hlog.FromRequest(r).Info().Str("user","current user").Str("status","ok").Msg("Something happened")// Output: {"level":"info","time":"2001-02-03T04:05:06Z","role":"my-service","host":"local-hostname","req_id":"b4g0l5t6tfid6dtrapu0","user":"current user","status":"ok","message":"Something happened"}}))http.Handle("/",h)iferr:=http.ListenAndServe(":8080",nil);err!=nil {log.Fatal().Err(err).Msg("Startup failed")}

Multiple Log Output

funcmain() {consoleWriter:= zerolog.ConsoleWriter{Out:os.Stdout}multi:=zerolog.MultiLevelWriter(consoleWriter,os.Stdout)logger:=zerolog.New(multi).With().Timestamp().Logger()logger.Info().Msg("Hello World!")}// Output (Line 1: Console; Line 2: Stdout)// 12:36PM INF Hello World!// {"level":"info","time":"2019-11-07T12:36:38+03:00","message":"Hello World!"}

Global Settings

Field Types

Standard Types

Advanced Fields

Binary Encoding

go build -tags binary_log.

Related Projects

Benchmarks

BenchmarkLogEmpty-8        100000000    19.1 ns/op     0 B/op       0 allocs/opBenchmarkDisabled-8        500000000    4.07 ns/op     0 B/op       0 allocs/opBenchmarkInfo-8            30000000     42.5 ns/op     0 B/op       0 allocs/opBenchmarkContextFields-8   30000000     44.9 ns/op     0 B/op       0 allocs/opBenchmarkLogFields-8       10000000     184 ns/op      0 B/op       0 allocs/op

Caveats

Field duplication

logger:=zerolog.New(os.Stderr).With().Timestamp().Logger()logger.Info().Timestamp().Msg("dup")// Output: {"level":"info","time":1494567715,"time":1494567715,"message":"dup"}

Concurrency safety

funchandler(w http.ResponseWriter,r*http.Request) {// Create a child logger for concurrency safetylogger:=log.Logger.With().Logger()// Add context fields, for example User-Agent from HTTP headerslogger.UpdateContext(func(c zerolog.Context) zerolog.Context {...    })}