Justin Harms
3703e40442
- Introduced multiple new markdown files detailing caching patterns, configuration management, development workflows, Go language conventions, HTTP proxy patterns, logging and monitoring practices, performance optimization guidelines, project structure, security validation, and VFS architecture. - Each document outlines best practices, patterns, and guidelines to enhance the understanding and implementation of various components within the SteamCache2 project. - This documentation aims to improve maintainability, facilitate onboarding for new contributors, and ensure consistent application of coding and architectural standards across the codebase.
87 lines
3.0 KiB
Plaintext
87 lines
3.0 KiB
Plaintext
---
|
|
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 |