zerolog

zerolog is a structured logging library for Go designed around a single goal: emit JSON log events without the allocations that typically come from reflection-based marshaling. Instead of building up a struct and serializing it, zerolog’s chaining Event API appends typed fields directly onto a byte buffer, giving it performance close to hand-written byte concatenation while keeping the call-site ergonomic (log.Info().Str("foo", "bar").Msg("hello")).

The core package stays intentionally small — a Logger, an Event, and an encoder abstraction that can target JSON or CBOR — while optional capability lives in subpackages: log for a ready-to-use global logger, hlog for net/http middleware, diode for a non-blocking ring-buffer writer under load, journald and syslog writers for platform logging targets, and pkgerrors for attaching stack traces to logged errors. A ConsoleWriter renders the same JSON events as colorized, human-readable lines for local development without changing how the application logs.

What You Get

• A chaining Event builder (log.Info().Str(...).Int(...).Msg(...)) that writes typed fields straight to a byte buffer with no intermediate struct or reflection
• Seven log levels (trace through panic) plus a no-level Log() call, with a package-wide SetGlobalLevel filter and per-logger level overrides
• Sub-loggers via With() that carry contextual fields (request ID, component name, etc.) into every event logged through them, safely shareable across goroutines
• A ConsoleWriter for colorized, human-readable output during development, with fully customizable field/level/message formatting
• Hooks for injecting computed fields or side effects into every event, and a Sampler interface for rate-limiting noisy log lines
• Optional CBOR binary encoding as a drop-in alternative to JSON via build tag
• Ready-made integrations: hlog (HTTP middleware), diode (non-blocking writer for bursty workloads), journald/syslog writers, and pkgerrors for stack-trace-aware error logging
• A log/slog compatible handler for projects standardizing on the Go standard library’s structured logging interface

Common Use Cases

• Structured JSON logging in latency-sensitive services (APIs, proxies, daemons) where log-line allocation shows up in profiles
• Attaching request-scoped context (user ID, trace ID, route) to every log line inside an HTTP handler via hlog middleware and a With()-derived sub-logger
• Local development with human-readable, colorized console output that switches to JSON in production by swapping the output writer
• High-throughput or bursty logging paths where a blocking writer would create backpressure, using the diode non-blocking ring buffer
• Shipping logs to systemd’s journal or syslog directly from a Go service via the journald/syslog writer packages
• Attaching formatted stack traces to error-level logs for services using github.com/pkg/errors, via the pkgerrors integration

Under The Hood

Architecture The core zerolog package centers on a Logger struct that pairs an io.Writer (upgraded to a LevelWriter if the caller provides one) with a level, an optional Sampler, a hook list, and a pre-encoded context byte slice. Calling a level method (Info(), Error(), etc.) produces an Event that appends fields directly to a shared buffer via an encoder interface, avoiding intermediate struct allocation; the buffer is only flushed to the writer on Msg/Send. With() snapshots the logger’s context into a Context value, letting callers build immutable sub-loggers that carry fields (request ID, component name) into every subsequent event without mutating the parent. Optional behavior is pushed into leaf packages rather than the core: log wraps a package-level global Logger, hlog adds net/http middleware that stores a Logger in the request context, diode wraps any writer in a lock-free ring buffer for non-blocking writes, and journald/syslog provide platform-specific writer implementations — none of which the core package depends on.

Tech Stack Written in Go (module targets Go 1.23) with a deliberately small dependency surface: github.com/rs/xid for compact ID generation, github.com/mattn/go-colorable and go-isatty for cross-platform console color support in ConsoleWriter, github.com/coreos/go-systemd/v22 for the journald writer, and github.com/pkg/errors (consumed only by the optional pkgerrors stack-trace subpackage). Encoding is abstracted behind an encoder interface with build-tag-selected implementations in internal/json and internal/cbor, so the same Event API can emit either format. CI runs via a single GitHub Actions workflow (.github/workflows/test.yml).

Code Quality The repository pairs most implementation files with a _test.go counterpart (16 test files covering the array/binary encoders, context, events, hooks, sampling, and the console writer), plus a dedicated benchmark_test.go reflecting the project’s performance focus. Errors are handled idiomatically — Err() short-circuits to an info-level event when passed nil, and the pkgerrors package layers formatted stack traces on top rather than swallowing failures. Public API surfaces are documented with godoc comments throughout log.go, event.go, and context.go, and example-driven tests (log_example_test.go, hlog_example_test.go, diode_example_test.go) double as executable documentation.

What Makes It Unique Where most Go JSON loggers build an intermediate representation (map, struct, or interface{} slice) and hand it to encoding/json, zerolog’s Event writes encoded bytes for each field as soon as it’s called, so a fully-populated log line is close to a single allocation-free buffer append. It applies this same design to both JSON and CBOR output through one encoder abstraction, and extends it past the core logger into a non-blocking writer (diode) for cases where even a fast writer becomes a bottleneck under bursty load — a concern most logging libraries leave entirely to the caller.