---
description: Logging and monitoring patterns for SteamCache2
---

# Logging and Monitoring Patterns

## Structured Logging with Zerolog
- Use zerolog for all logging operations
- Include structured fields for better querying and analysis
- Use appropriate log levels: Debug, Info, Warn, Error
- Include timestamps and context in all log messages
- Configure log format (JSON for production, console for development)

## Log Context and Fields
- Always include relevant context in log messages
- Use consistent field names: `client_ip`, `cache_key`, `url`, `service`
- Include operation duration with `Dur()` for performance monitoring
- Log cache hit/miss status for analytics
- Include file sizes and operation counts for monitoring

## Performance Monitoring
- Log request processing times with `zduration` field
- Monitor cache hit/miss ratios
- Track memory and disk usage
- Log garbage collection events and statistics
- Monitor concurrent request counts and limits

## Error Logging
- Log errors with full context and stack traces
- Include relevant request information in error logs
- Use structured error logging with `Err()` field
- Log configuration errors with file paths
- Include upstream server errors with status codes

## Cache Operation Logging
- Log cache hits with key and response time
- Log cache misses with reason and upstream response time
- Log cache corruption detection and cleanup
- Log garbage collection operations and evicted items
- Log cache promotion events (disk to memory)

## Service Detection Logging
- Log service detection results (Steam, Epic, etc.)
- Log User-Agent patterns and matches
- Log service configuration changes
- Log cache key generation for different services

## HTTP Request Logging
- Log incoming requests with method, URL, and client IP
- Log response status codes and sizes
- Log upstream server communication
- Log rate limiting events and client limits
- Log health check and heartbeat requests

## Configuration Logging
- Log configuration loading and validation
- Log default configuration generation
- Log configuration changes and overrides
- Log startup parameters and settings

## Security Event Logging
- Log suspicious request patterns
- Log rate limiting violations
- Log authentication failures (if applicable)
- Log configuration security issues
- Log potential security threats

## System Health Logging
- Log memory usage and fragmentation
- Log disk usage and capacity
- Log connection pool statistics
- Log goroutine counts and lifecycle
- Log system resource utilization

## Log Rotation and Management
- Implement log rotation for long-running services
- Use appropriate log retention policies
- Monitor log file sizes and disk usage
- Configure log levels for different environments
- Use structured logging for log analysis tools

## Monitoring Integration
- Design logs for easy parsing by monitoring tools
- Include metrics that can be scraped by Prometheus
- Use consistent field naming for dashboard creation
- Log events that can trigger alerts
- Include correlation IDs for request tracing