zerolog

zerolog is a fast, simple, zero-allocation JSON logger for Go. It focuses on efficient structured logging using a unique chaining API that avoids reflection and allocations.

Key features include:

• Performance: Blazing fast with low to zero allocation.
• Structured Logging: Native JSON and CBOR encoding formats.
• Logging Control: Leveled logging, sampling, and hooks.
• Contextualization: Support for contextual fields and context.Context integration.
• Integrations: net/http integration and log/slog compatibility.
• Developer Experience: Error logging with optional stacktraces and a zerolog.ConsoleWriter for pretty-printed console output during development.

Zerolog Lint is a tool designed to detect missing log event finishers in zerolog code. In zerolog, a log chain must end with a finisher like Msg() or Msgf() to actually write the event. If these are omitted, the log will not occur, and no compile-time error is raised. This linter inspects method call chains on zerolog.Event to ensure a finisher is present.

Note: This tool is DEPRECATED. It is recommended to use zerologlint instead, which integrates directly with go vet and golangci-lint.

go run cmd/lint/lint.go <package>

Zerolog uses sync.Pool for high performance. To avoid memory corruption or unexpected behavior, follow these rules:

1. *Event objects: The Event returned by level-specific functions (e.g., Info(), Debug()) is pooled. Do not hold a reference to it after calling Msg(), Msgf(), Send(), or MsgFunc(). This includes references inside Hook.Run() or MarshalZerologObject callbacks.
2. Array objects: Objects returned from Context.CreateArray() or Event.CreateArray() are pooled. Do not hold references to them inside MarshalZerologArray callbacks or your own code after the buffering call completes.
3. Dictionary objects: Objects returned from Context.CreateDict() or Event.CreateDict() must not be referenced after being buffered by Array.Dict(), Context.Dict(), or Event.Dict().

You can pass loggers through your application using Go's context.Context.

1. Attach a logger to a context: Use logger.WithContext(ctx).
2. Retrieve a logger from a context: Use zerolog.Ctx(ctx). If no logger is found in the context, it returns zerolog.DefaultContextLogger (or a disabled logger if that is nil).

You can also use Hooks to extract information (like trace IDs) from the context and add them to the log event automatically.

func someFunc(ctx context.Context) {
    // Get Logger from the go Context
    logger := zerolog.Ctx(ctx)
    logger.Info().Msg("Hello")
}

func f() {
    logger := zerolog.New(os.Stdout)
    ctx := context.Background()

    // Attach the Logger to the context.Context
    ctx = logger.WithContext(ctx)
    someFunc(ctx)
}

Zerolog does not perform de-duplication of keys. If you use the same key multiple times in a single event, the resulting JSON will contain multiple identical keys. While many JSON parsers will take the last value, this behavior is not guaranteed across all consumers.

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

The UpdateContext method is not concurrency safe. To safely add context in concurrent environments (like HTTP handlers), use the With() method to create a child logger instead of modifying a shared logger instance.

func handler(w http.ResponseWriter, r *http.Request) {
    // Create a child logger for concurrency safety
    logger := log.Logger.With().Logger()

    // Add context fields, for example User-Agent from HTTP headers
    logger.UpdateContext(func(c zerolog.Context) zerolog.Context {
        ...
    })
}

The github.com/rs/zerolog/hlog package provides helpers for integrating zerolog into HTTP middleware.

• hlog.NewHandler(logger): Creates a handler that provides the logger via the request context.
• hlog.AccessHandler(...): Logs request details (method, status, size, duration).
• hlog.RemoteAddrHandler, hlog.UserAgentHandler, etc.: Automatically adds request metadata to the log context.

// Example using hlog in an HTTP middleware chain
c = c.Append(hlog.NewHandler(log))
c = c.Append(hlog.AccessHandler(func(r *http.Request, status, size int, duration time.Duration) {
    hlog.FromRequest(r).Info().
        Str("method", r.Method).
        Int("status", status).
        Msg("")
}))

// Inside the handler:
hlog.FromRequest(r).Info().Msg("Something happened")

To install zerolog, use the following command to fetch the package:

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

Zerolog PrettyLog is a CLI utility designed to colorize and pretty-print structured JSON logs produced by zerolog.

Because zerolog outputs to stderr by default rather than stdout, you must redirect the stderr stream to the prettylog tool to view formatted logs. The method for redirection depends on your operating system.

### Linux
Redirect `stderr` to `prettylog` while leaving `stdout` unaffected:

# Using a compiled version
some_program_with_zerolog 2> >(prettylog)

# Running directly with `go run`
some_program_with_zerolog 2> >(go run cmd/prettylog/prettylog.go)

### Windows
Redirect `stderr` to `stdout` and pipe it to `prettylog`:

# Using a compiled version
some_program_with_zerolog 2>&1 | prettylog

# Running directly with `go run`
some_program_with_zerolog 2>&1 | go run cmd/prettylog/prettylog.go

For human-readable, colorized output (useful for local development), use zerolog.ConsoleWriter. You can customize the output by configuring fields like FormatLevel, FormatMessage, FormatFieldName, and FormatFieldValue.

// Basic pretty logging
log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stderr})
log.Info().Str("foo", "bar").Msg("Hello world")

// Advanced customization
output := zerolog.ConsoleWriter{Out: os.Stdout, TimeFormat: time.RFC3339}
output.FormatLevel = func(i interface{}) string {
    return strings.ToUpper(fmt.Sprintf("| %-6s|", i))
}
// ... other formatters
log := zerolog.New(output).With().Timestamp().Logger()