Guide · Open source

How to use zerolog: install, log JSON and set levels in Go

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Zerolog is a Go logging library that writes structured events as JSON, or optionally CBOR, with typed key-value fields. This guide shows you how to install it, log messages with fields, control the log level and log errors with stack traces. It is aimed at Go developers who want machine-readable logs with low overhead.

zerologrs/zerolog · ★ 12.5k · MIT Install options & downloads

Quick start

1Install the package. Make sure Go is installed, then run go get -u github.com/rs/zerolog/log in your project.
2Import the global logger. Import github.com/rs/zerolog and github.com/rs/zerolog/log in your Go file.
3Choose a time format. Set zerolog.TimeFieldFormat to zerolog.TimeFormatUnix if you want UNIX timestamps.
4Log with typed fields. Chain Str, Float64 or other typed methods, then end the chain with Msg or Send.
5Set the level. Call zerolog.SetGlobalLevel with the lowest level you want written, such as zerolog.InfoLevel.
6Log errors with stacks if needed. Use Err, and for stack traces set zerolog.ErrorStackMarshaler with pkgerrors and call Stack().

Install zerolog in a Go project

Zerolog is a Go package, so you need Go installed first. The README installs the global logger package with a single command, which fetches zerolog as a dependency of your project.

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

Log a simple message

For simple logging, import the global logger package github.com/rs/zerolog/log. Setting zerolog.TimeFieldFormat to zerolog.TimeFormatUnix makes the timestamp a UNIX time, which the README says is faster and smaller than most timestamps.

By default the log writes to os.Stderr, and the default level for log.Print is trace.

package main

import (
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    // UNIX Time is faster and smaller than most timestamps
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix

    log.Print("hello world")
}

// Output: {"time":1516134303,"level":"debug","message":"hello world"}

Add typed fields to log events

Contextual fields are key-value pairs added to a message with a chain of method calls. Fields are strongly typed, so you use Str for strings, Float64 for floats and so on. The chain must end with Msg or Msgf, or Send when there is no message. If you forget both, the log is not written and the compiler does not warn you.

Str adds a string field.
Float64 adds a floating-point field.
Msg writes the event with a message.
Send writes the event without a message.

package main

import (
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix

    log.Debug().
        Str("Scale", "833 cents").
        Float64("Interval", 833.09).
        Msg("Fibonacci is everywhere")

    log.Debug().
        Str("Name", "Tom").
        Send()
}

Set the global log level

Zerolog has seven levels, from highest to lowest: panic, fatal, error, warn, info, debug and trace. Call zerolog.SetGlobalLevel with a constant such as zerolog.InfoLevel, and every event at that level or above is written. Pass zerolog.Disabled to turn logging off.

Note the default: if you never call SetGlobalLevel, every event including trace is written to stderr, so a plain log.Info call appears out of the box. Calling SetGlobalLevel(zerolog.InfoLevel) suppresses trace and debug messages.

panic (zerolog.PanicLevel, 5)
fatal (zerolog.FatalLevel, 4)
error (zerolog.ErrorLevel, 3)
warn (zerolog.WarnLevel, 2)
info (zerolog.InfoLevel, 1)
debug (zerolog.DebugLevel, 0)
trace (zerolog.TraceLevel, -1)

zerolog.SetGlobalLevel(zerolog.InfoLevel)

Log errors and stack traces

Use the Err method to attach an error. The default field name is error, and you can change it by setting zerolog.ErrorFieldName.

To include a stack trace, use the github.com/pkg/errors package together with zerolog/pkgerrors, set zerolog.ErrorStackMarshaler to pkgerrors.MarshalStack, and call Stack() in the chain.

package main

import (
    "github.com/pkg/errors"
    "github.com/rs/zerolog/pkgerrors"

    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
    zerolog.ErrorStackMarshaler = pkgerrors.MarshalStack

    err := outer()
    log.Error().Stack().Err(err).Msg("")
}

Check the level before building expensive output

If computing a field is costly, check whether the level is enabled first. Call e.Enabled() on the event returned by log.Debug(), and only build the extra data when it returns true.

if e := log.Debug(); e.Enabled() {
    value := "bar"
    e.Str("foo", value).Msg("some debug message")
}

What people use it for

Writing JSON logs that a log-processing tool can parse and index by field.
Adding request or job context such as names and numbers to each event.
Logging in backend services where the cost of logging matters.
Recording errors with a stack trace from github.com/pkg/errors.

Frequently asked questions

Is zerolog free to use?

Zerolog is released under the MIT licence, as stated in the project's README and licence badge. The MIT licence permits use in both open-source and commercial projects, but check the LICENSE file in the repository for the exact terms.

What do I need to use zerolog?

You need Go installed, since zerolog is a Go package and the README installs it with go get. It is not usable from other languages.

Why does my log.Info message show up even though I did not configure anything?

By default the global logger writes to os.Stderr at the trace level, so every event is written. To hide lower-level messages, call zerolog.SetGlobalLevel with a higher level such as zerolog.InfoLevel.

Why is my log line missing entirely?

A log event only writes when the chain ends with Msg, Msgf or Send. The README warns that forgetting these produces no log and no compile-time error.

Can zerolog print colored, readable output in the console?

The README says zerolog.ConsoleWriter provides pretty printing, but it is inefficient, and the library is focused on structured JSON. Use it for development, not for high-volume production logs.

How does zerolog compare to zap, logrus and slog?

The README says zerolog builds on the approach of Uber's zap, aiming for a simpler API and better performance. It also includes log/slog integration. Logrus and slog are other Go logging options you can compare by API style and performance needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Zerolog suits Go developers who want fast, structured JSON logs and a typed chaining API, especially in backend services. If you need readable coloured console output by default, or a full framework with rotation and file management, the README does not describe those features, so look at another tool.

Install options & downloads