# Zap — Blazing Fast Structured Logging for Go

> A high-performance, structured, leveled logging library for Go that avoids reflection and allocations on the hot path for production workloads.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Zap — Blazing Fast Structured Logging for Go

## Quick Use
```bash
go get go.uber.org/zap
```
```go
logger, _ := zap.NewProduction()
defer logger.Sync()
logger.Info("request handled", zap.String("path", "/api"), zap.Int("status", 200))
```

## Introduction
Zap is a structured logging library from Uber that prioritizes performance above all else. It avoids serialization overhead and memory allocations in the critical logging path, making it suitable for latency-sensitive services that generate millions of log lines per second.

## What Zap Does
- Provides zero-allocation structured logging at the core (Logger) level
- Offers a convenience SugaredLogger for printf-style and loosely typed logging
- Supports leveled logging (Debug, Info, Warn, Error, DPanic, Panic, Fatal)
- Outputs JSON or console-friendly formats with configurable encoders
- Integrates with log rotation and third-party sinks via WriteSyncer interface

## Architecture Overview
Zap separates its API into two loggers: the core Logger uses strongly typed Field constructors to avoid reflection and interface boxing, achieving near-zero allocations per log entry. The SugaredLogger wraps it with a friendlier API that accepts variadic key-value pairs at the cost of minor allocations. Both share the same underlying Core, which handles level checking, encoding, and writing to one or more output sinks.

## Self-Hosting & Configuration
- Install: `go get go.uber.org/zap`
- Use `zap.NewProduction()` or `zap.NewDevelopment()` for sensible defaults
- Customize via `zap.Config` struct for output paths, level, and encoding
- Add context fields with `logger.With(zap.String("service", "api"))` for child loggers
- Redirect stdlib log package to Zap using `zap.RedirectStdLog(logger)`

## Key Features
- Near-zero allocation logging path for structured fields
- Type-safe field constructors prevent runtime errors from mismatched key-value pairs
- Atomic level changes at runtime without restarting the service
- Pluggable output sinks supporting files, stdout, network, and custom destinations
- Sampling support to reduce log volume under high load while preserving visibility

## Comparison with Similar Tools
- **Zerolog** — also zero-allocation with a chaining API; Zap offers more flexible configuration and a richer sink ecosystem
- **Logrus** — popular but slower due to reflection; Zap is significantly faster in benchmarks
- **slog (stdlib)** — built-in since Go 1.21; Zap predates it and remains faster for high-throughput scenarios
- **Apex Log** — simple interface-based logger; Zap provides more production features like sampling
- **Go kit log** — part of Go-kit; Zap is standalone and optimized purely for performance

## FAQ
**Q:** When should I use Logger vs SugaredLogger?
A: Use Logger in hot paths where every allocation matters. Use SugaredLogger for application setup, tests, or infrequent log calls where convenience wins.

**Q:** Can I change log level at runtime?
A: Yes. Create an `AtomicLevel` and pass it to your config. You can then change it via HTTP endpoint or programmatically.

**Q:** Does Zap support log rotation?
A: Zap itself does not rotate files, but you can use lumberjack as a WriteSyncer to handle rotation transparently.

**Q:** How does Zap compare to Go 1.21 slog?
A: slog is a good standard choice. Zap remains faster in micro-benchmarks and has a larger ecosystem of integrations.

## Sources
- https://github.com/uber-go/zap
- https://pkg.go.dev/go.uber.org/zap

---
Source: https://tokrepo.com/en/workflows/zap-blazing-fast-structured-logging-go-7ffa7179
Author: Script Depot