logging-best-practices

What this skill does

# Logging Best Practices

Apply these logging principles to ensure effective debugging, monitoring, and audit capabilities across applications and services.

## Structured Logging

- Use structured logging formats (JSON) for all log output
- Include consistent fields across all log entries
- Make logs machine-parseable while remaining human-readable
- Use a logging library that supports structured output natively
- Avoid string concatenation for log messages; use structured fields

## Standard Log Fields

Include these fields in every log entry:

- **timestamp**: ISO 8601 format with timezone
- **level**: Log severity (DEBUG, INFO, WARN, ERROR, FATAL)
- **message**: Human-readable description of the event
- **service**: Name of the service or application
- **version**: Application version or build identifier
- **trace_id**: Distributed tracing correlation ID
- **span_id**: Current span identifier
- **request_id**: Unique identifier for the request

## Log Levels

Use appropriate log levels consistently:

- **DEBUG**: Detailed diagnostic information for development
- **INFO**: Normal operational events and state changes
- **WARN**: Unexpected situations that are handled gracefully
- **ERROR**: Failures that affect current operation but not the service
- **FATAL**: Critical failures requiring immediate attention

## Context Propagation

- Include request context in all log entries within a request lifecycle
- Propagate trace IDs across service boundaries
- Add user context (anonymized) for user-initiated actions
- Include relevant business context for domain events
- Use MDC (Mapped Diagnostic Context) or equivalent for context management

## Security and Privacy

- Never log sensitive information (passwords, tokens, PII)
- Mask or redact sensitive data when it must be referenced
- Implement log access controls appropriate to data sensitivity
- Consider data retention policies and compliance requirements
- Audit log access for sensitive systems

## Performance Considerations

- Use asynchronous logging to avoid blocking application threads
- Implement log sampling for high-volume debug logs in production
- Buffer logs appropriately to balance latency and throughput
- Monitor logging infrastructure for bottlenecks
- Set appropriate log levels per environment

## Log Aggregation

- Centralize logs from all services into a single platform
- Use consistent formatting across all services
- Implement log rotation and retention policies
- Enable full-text search and filtering capabilities
- Set up log-based alerts for critical patterns

## Error Logging

- Include full error context: message, code, stack trace
- Log the chain of errors in wrapped/nested exceptions
- Include relevant request and state information
- Avoid duplicate error logging across layers
- Log error recovery actions and outcomes

## Best Practices

- Log at service boundaries (entry and exit points)
- Include timing information for performance analysis
- Log configuration changes and deployments
- Create actionable log messages that aid debugging
- Review and clean up logging regularly to reduce noise

## Log Message Guidelines

- Write clear, descriptive messages
- Include relevant identifiers (user ID, order ID, etc.)
- Avoid generic messages like "Error occurred"
- Use consistent terminology across the application
- Include enough context to understand the event without additional lookups

## Environment-Specific Configuration

- **Development**: DEBUG level, console output, verbose formatting
- **Staging**: INFO level, structured JSON, full context
- **Production**: INFO/WARN level, structured JSON, sampling for DEBUG