0x1d
926f3f927e
- Verified all acceptance criteria for Stories 1.1-1.6 - Updated Status fields from Pending to Completed - Marked all acceptance criteria checkboxes as completed - All stories in Epic 1 are now fully implemented and verified
137 lines
4.7 KiB
Markdown
137 lines
4.7 KiB
Markdown
# 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**
|
|
```bash
|
|
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
|
|
- [x] `Logger` interface is defined and documented
|
|
- [x] Zap implementation supports JSON and console formats
|
|
- [x] Log levels are configurable and respected
|
|
- [x] Request IDs are generated and included in all logs
|
|
- [x] Request ID middleware works with Gin
|
|
- [x] Context-aware logging extracts request ID and user ID
|
|
- [x] Logger can be injected via DI container
|
|
- [x] All modules can use logger through interface
|
|
- [x] Request correlation works across service boundaries
|
|
- [x] Structured fields work correctly
|
|
|
|
## Related ADRs
|
|
- [ADR-0005: Logging Framework](../../adr/0005-logging-framework.md)
|
|
- [ADR-0012: Logger Interface Design](../../adr/0012-logger-interface-design.md)
|
|
|
|
## 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
|
|
```bash
|
|
# 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
|
|
|