Logging

etcd uses zap (go.uber.org/zap) for structured logging. There is no second logger: the older capnslog integration was retired in v3.5.

Configuration

Defined in server/embed/config.go (Config.Logger, Config.LogLevel, Config.LogOutputs, Config.LogRotationConfig):

Flag	Default	Effect
--logger=zap	zap	Only zap is supported in current versions
--log-level	info	debug, info, warn, error, dpanic, panic, fatal
--log-outputs	default	Comma-separated list. default, stderr, stdout, file paths, or systemd/journal
--log-format	json	json or console
--log-rotation-config-json	disabled	JSON snippet that activates lumberjack-style rotation: {"maxsize": 100, "maxage": 0, "maxbackups": 0, "localtime": false, "compress": false}

Boot logs use a temporary in-memory logger until the configuration is parsed; you'll see a Running: line followed by the resolved settings.

Log conventions

• Structured fields: prefer zap.String, zap.Int64, zap.Duration over fmt.Sprintf.
• Levels:
  • Debug — per-request or per-iteration noise.
  • Info — state transitions: leader change, member added, snapshot saved, version negotiation.
  • Warn — recoverable trouble: slow apply, stream disconnect, retry exhausted.
  • Error — unrecoverable but caught.
  • Panic / DPanic — invariant violation; in dev-mode dpanic panics, in prod it logs at Error.
• Loggers are passed in by the constructor; no nil logger is supposed to slip through, although a few legacy paths still defend against it (e.g. server/etcdserver/zap_raft.go).

Slow-request logs

If an apply takes longer than --warning-apply-duration (default 100 ms), the server emits a structured warning that includes:

• The op type and key (or key range).
• Duration breakdown via traceutil.Trace.Step events.
• Context: leader/follower, current revision, etc.

Code: server/etcdserver/v3_server.go::traceThreshold. The same trace data feeds OpenTelemetry spans when distributed tracing is enabled.

Where logs live in code

• server/embed/config_logging.go — log setup at startup.
• server/embed/config_logging_journal_unix.go, ..._windows.go — systemd / event-log integration.
• client/pkg/v3/logutil/ — helpers shared with the Go client.
• server/etcdserver/zap_raft.go — adapter from the raft library's logger interface to zap.

Operator tips

• Always set --log-format=json in production; the Grafana mixin's log dashboards parse JSON.
• Pipe --log-outputs to a file plus stderr so systemd captures something even if the file logger fails.
• Combine with --enable-pprof=true and :2379/debug/pprof/profile for full-fidelity perf analysis.