logger

A production-ready, context-aware, structured logger for Go. JSON/logfmt/ECS/GCP formats, ANSI colors, child fields, async flushing, and pluggable sinks. Sensible defaults for dev and prod, plus security helpers (redaction, size limits, allowlist). See examples/ to copy-paste usage.

Features

Core API & Ergonomics

Child loggers: With(fields) for persistent context
Multiple formats: JSON, logfmt, ECS, GCP Cloud Logging, Console
Message shaping: Msgf(), Err(err).Msg(), KV() helpers
Dynamic levels: Runtime level changes with SetLevel()
Smart defaults: TTY detection, NO_COLOR support

Performance & Concurrency

Batching: Configurable batch sizes and timeouts
Backpressure: Block, drop oldest, or sample strategies
Zero-alloc: Buffer pooling with sync.Pool
Atomic config: Thread-safe configuration updates

Reliability & Delivery

Pluggable sinks: stdout, stderr, file, HTTP, with retry/backoff
Circuit breakers: Automatic failure detection and recovery
Spool to disk: Network outage resilience
Crash-safe hooks: Isolated error handling

Experimental Features

The following features are marked as experimental and may change in future versions:

HTTPSink: HTTP endpoint logging with retry and circuit breaker support
RetrySink: Exponential backoff with failure tracking
CircuitBreakerSink: Failure windows, half-open probing, and state management
SpoolSink: Disk persistence on failure and drain on recovery
Metrics & Health: Real-time observability with Prometheus export
PrometheusExporter: Metrics export functionality

These features are production-ready but may have API changes in future versions.

Security & Compliance

PII redaction: Email, SSN, credit card, phone number patterns
Secret scrubbing: Password, API key, token auto-masking
Size limits: Configurable message truncation
Schema allowlist: Field-level access control

Observability

Prometheus metrics: logs_emitted_total, queue_depth, etc.
Health checks: logger.Health() with diagnostics
Self-diagnostics: Comprehensive system status

Quick Start

Get started by reading the usage examples in the examples/ package.

Running examples:

# Run all examples.
go test ./examples -count 1 -v

# Run specific example.
go test ./examples -count 1 -v -run Test_BasicLogging

Configuration

Environment Variables

export LOG_LEVEL=INFO
export LOG_FORMAT=json
export LOG_COLOR=true
export LOG_ASYNC_BUF=1000
export NO_COLOR=1  # Disable colors

Smart Configuration

Use the smart builder for environment-aware defaults:

// Automatically detects environment and applies appropriate defaults
smartLogger := logger.NewSmart(ctx, func(context.Context) *logger.ExtraData {
    return &logger.ExtraData{
        TraceID: "trace-123",
        SpanID:  "span-456",
    }
})

aatuh/logger