Deep Dive into Uber's zap: Architecture, High‑Performance Design, and Lessons for Building Go Logging Libraries

zap is Uber's open‑source high‑performance logging library for Go. The author examines zap's architecture and implementation, revealing why it achieves superior speed compared to other Go loggers like seelog and logrus, and provides recommendations for building high‑performance Go components.

Logging is critical for observability, but many logging libraries consume excessive CPU and memory, raising service costs. In the author's own benchmarks, zap consistently outperforms seelog and logrus by several times in single‑threaded QPS.

Common Go logging libraries are summarized: seelog (feature‑rich but slow), logrus (clear API with decent performance), and zap (designed explicitly for speed). zap adopts structured logging, separating fields (key‑value context) from the message.

Example of structured logging with zap:

log.Error("User does not exist", zap.Int("uid", uid))

The logging flow in zap consists of five steps: (1) allocate a log entry, (2) check level and add core (including any hooks), (3) add caller and stack info if needed, (4) encode the entry into a byte slice via an encoder, and (5) write the encoded slice while invoking remaining cores.

Key components include the logger (exposes logger, field, and level objects), zapcore (core logic for level checking, field management, and encoding), encoder (JSON or other formats), and various utils (grpc logger, hooks, std logger, sublog).

zap does not define a high‑level logging interface; instead, zapcore provides the interface that the logger depends on. This design allows custom core implementations while keeping the logger API stable.

To avoid the cost of reflection, zap provides type‑specific append functions that directly convert values to []byte using strconv.AppendX . This eliminates the overhead of fmt.Sprintf and reflection‑based JSON marshaling.

Performance tricks include extensive use of sync.Pool to reuse buffers and entry objects, reducing GC pressure. Each log call typically requires two allocations (field creation and byte slice), but zap's pooling mitigates this.

zap implements its own JSON encoder to bypass the reflection‑heavy standard library encoder, constructing JSON strings manually for maximum speed.

Concurrency is handled via a write‑time copy mechanism and the introduction of CheckedEntry , which ensures that only logs passing level checks proceed to encoding, avoiding unnecessary work and race conditions.

Additional features: an HTTP level handler for dynamic log level changes, a sugar logger that supports printf‑style formatting, utilities for grpc integration, hooks for custom processing (e.g., sending logs to Kafka), and a RollingWriter implementation for automatic log rotation.

In summary, zap achieves high performance through careful code organization, object pooling, avoidance of reflection, efficient byte‑slice manipulation, and a minimal‑locking design, offering valuable lessons for developers building high‑throughput Go libraries.