goplt/docs/content/adr/0005-logging-framework.md

ADR-0005: Logging Framework

Status

Accepted

Context

The platform requires structured logging that:

• Supports multiple log levels
• Provides structured output (JSON for production)
• Allows adding contextual fields
• Performs well under load
• Integrates with observability tools

Options considered:

1. go.uber.org/zap - High-performance structured logging
2. rs/zerolog - Zero-allocation logger
3. sirupsen/logrus - Structured logger (maintenance mode)
4. Standard library log - Basic logging (insufficient)

Decision

Use go.uber.org/zap (v1.26.0+) as the logging framework.

Rationale:

• Industry standard for high-performance Go applications
• Excellent structured logging with field support
• Very low overhead (designed for high-throughput systems)
• JSON output for production, human-readable for development
• Strong ecosystem integration
• Actively maintained by Uber

Consequences

Positive

• High performance (low latency, high throughput)
• Rich structured logging with fields
• Easy integration with observability tools
• Configurable output formats (JSON/console)

Negative

• Slightly more verbose API than standard library
• Requires wrapping for common use cases (we'll abstract via interface)

Implementation Notes

• Install: go get go.uber.org/zap@v1.26.0
• Create pkg/logger/logger.go interface to abstract zap
• Implement internal/logger/zap_logger.go as concrete implementation
• Use JSON encoder for production, console encoder for development
• Support request-scoped fields via context
• Export global logger via pkg/logger package