logging

Logging Package

Structured logging utilities for the LLM proxy, built on Zap.

Purpose & Responsibilities

• Structured Logging: JSON and console output formats via Zap
• Canonical Fields: Standardized field names for consistent log analysis
• Context Propagation: Request ID and correlation ID tracking
• Log Level Filtering: Configurable verbosity (debug, info, warn, error)
• Output Routing: Stdout or file-based log output

Configuration Options

Log Levels

Canonical Log Fields

The package provides helper functions for consistent field naming:

Security: TokenID() automatically obfuscates tokens to prevent sensitive data leakage.

Context Propagation

flowchart LR
    subgraph Request Flow
        R[Request] --> M[Middleware]
        M --> H[Handler]
        H --> S[Service]
    end
    
    subgraph Context
        C[Context with IDs]
    end
    
    M -->|WithRequestID| C
    M -->|WithCorrelationID| C
    C -->|GetRequestID| H
    C -->|GetCorrelationID| S

Key Functions:

• WithRequestID(ctx, id) / GetRequestID(ctx) - Add/retrieve request ID
• WithCorrelationID(ctx, id) / GetCorrelationID(ctx) - Add/retrieve correlation ID
• WithRequestContext(ctx, logger) - Enrich logger with request ID from context
• WithCorrelationContext(ctx, logger) - Enrich logger with correlation ID from context
• NewChildLogger(parent, component) - Create component-specific logger

Output Formats

JSON Format (Production)

{
    "ts": "2024-01-15T10:30:45.123Z",
    "level": "info",
    "msg": "Request completed",
    "request_id": "req-abc123",
    "method": "POST",
    "status_code": 200
}

Console Format (Development)

2024-01-15T10:30:45.123Z  info  Request completed  {"request_id": "req-abc123", "method": "POST"}

Integration Flow

sequenceDiagram
    participant Client
    participant Middleware
    participant Handler
    participant Logger
    
    Client->>Middleware: Request
    Middleware->>Middleware: WithRequestID(ctx)
    Middleware->>Handler: ctx with IDs
    Handler->>Logger: WithRequestContext(ctx)
    Logger->>Logger: Log with request_id
    Handler->>Middleware: Response
    Middleware->>Logger: RequestFields(...)
    Middleware->>Client: Response

Testing Guidance

• Unit Tests: Use zaptest.NewLogger(t) for test-captured output
• Assert Logs: Use zap/zaptest/observer to capture and verify log entries
• Existing Tests: See logger_test.go for comprehensive examples

Related Documentation

• Audit Package - Security audit logging (separate from application logs)

Files