feat: reword phase to epic, update mkdocs
This commit is contained in:
136
docs/content/stories/epic0/0.3-structured-logging-system.md
Normal file
136
docs/content/stories/epic0/0.3-structured-logging-system.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Story 0.3: Structured Logging System
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 0.3
|
||||
- **Title**: Structured Logging System
|
||||
- **Epic**: 0 - Project Setup & Foundation
|
||||
- **Status**: Pending
|
||||
- **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
|
||||
- [ ] `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/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
|
||||
|
||||
Reference in New Issue
Block a user