goplt/docs/content/stories/epic0/0.3-structured-logging-system.md

Story 0.3: Structured Logging System

Metadata

• Story ID: 0.3
• Title: Structured Logging System
• Epic: 0 - Project Setup & Foundation
• Status: Completed
• Priority: High
• Estimated Time: 4-6 hours
• Dependencies: 0.1, 0.2

Goal

Implement a production-ready logging system with structured JSON output, request correlation, and configurable log levels that can be used by all modules.

Description

This story implements a complete logging system using Zap that provides structured logging, request correlation via request IDs, and context-aware logging. The system must support both development (human-readable) and production (JSON) formats.

Deliverables

1. Logger Interface (pkg/logger/logger.go)

Define Logger interface with:

• Debug(msg string, fields ...Field) - Debug level logging
• Info(msg string, fields ...Field) - Info level logging
• Warn(msg string, fields ...Field) - Warning level logging
• Error(msg string, fields ...Field) - Error level logging
• With(fields ...Field) Logger - Create child logger with fields
• WithContext(ctx context.Context) Logger - Create logger with context fields
• Field type for structured fields
• Package-level convenience functions

2. Zap Implementation (internal/logger/zap_logger.go)

Implement Logger interface using Zap:

• Structured JSON logging for production mode
• Human-readable console logging for development mode
• Configurable log levels (debug, info, warn, error)
• Request-scoped fields support
• Context-aware logging (extract request ID, user ID from context)
• Field mapping to Zap fields
• Error stack trace support

3. Request ID Middleware (internal/logger/middleware.go)

Gin middleware for request correlation:

• Generate unique request ID per HTTP request
• Add request ID to request context
• Add request ID to all logs within request context
• Return request ID in response headers (X-Request-ID)
• Support for existing request IDs in headers

4. Global Logger Export (pkg/logger/global.go)

• Export default logger instance
• Package-level convenience functions
• Thread-safe logger access

5. DI Integration

• Provider function for Logger
• Register in DI container
• Make configurable via FX

Implementation Steps

1. Install Dependencies

   go get go.uber.org/zap@v1.26.0
   

2. Create Logger Interface

   • Define Logger interface in pkg/logger/logger.go
   • Define Field type for structured fields
   • Add package documentation

3. Implement Zap Logger

   • Create internal/logger/zap_logger.go
   • Implement all interface methods
   • Support both JSON and console encoders
   • Handle log levels and field mapping

4. Create Request ID Middleware

   • Create internal/logger/middleware.go
   • Implement Gin middleware
   • Generate and propagate request IDs
   • Add to response headers

5. Add Global Logger

   • Create pkg/logger/global.go
   • Export default logger
   • Add convenience functions

6. Integrate with DI

   • Create provider function
   • Register in DI container
   • Test injection

Acceptance Criteria

• Logger interface is defined and documented
• Zap implementation supports JSON and console formats
• Log levels are configurable and respected
• Request IDs are generated and included in all logs
• Request ID middleware works with Gin
• Context-aware logging extracts request ID and user ID
• Logger can be injected via DI container
• All modules can use logger through interface
• Request correlation works across service boundaries
• Structured fields work correctly

Related ADRs

• ADR-0005: Logging Framework
• ADR-0012: Logger Interface Design

Implementation Notes

• Use Zap's production and development presets
• Request IDs should be UUIDs or similar unique identifiers
• Context should be propagated through all service calls
• Log levels should be configurable via configuration system
• Consider adding log sampling for high-volume production
• Support for log rotation and file output (future enhancement)

Testing

# Test logger interface
go test ./pkg/logger/...

# Test Zap implementation
go test ./internal/logger/...

# Test request ID middleware
go test ./internal/logger/... -run TestRequestIDMiddleware

Files to Create/Modify

• pkg/logger/logger.go - Logger interface
• pkg/logger/global.go - Global logger export
• internal/logger/zap_logger.go - Zap implementation
• internal/logger/middleware.go - Request ID middleware
• internal/di/providers.go - Add logger provider
• config/default.yaml - Add logging configuration