Log Level Reference Guide
Comprehensive guide for logging best practices
DEBUG
Detailed diagnostic information for development and troubleshooting
When to Use
- Variable values and state information
- Function entry/exit with parameters
- Detailed flow of execution
- Cache hits/misses
- Query details and results
Characteristics
- Volume: Very high
- Production: Usually disabled
- Audience: Developers
- Performance: Can impact performance
Example Messages
DEBUG: Processing user request for ID 12345
DEBUG: Cache miss for key 'user:session:abc123'
DEBUG: Executing SQL: SELECT * FROM users WHERE id = ?
DEBUG: Function calculateTotal() returned 156.78
Warning: Never log sensitive data (passwords, tokens, PII) even at DEBUG level
INFO
General informational messages about system operation
When to Use
- Application startup and shutdown
- Configuration values loaded
- Significant business events
- Successful completion of major operations
- User actions (login, logout, purchase)
- API calls to external services
Characteristics
- Volume: Moderate
- Production: Enabled
- Audience: Operations, support
- Performance: Minimal impact
Example Messages
INFO: Application started on port 8080
INFO: User 'john@example.com' logged in successfully
INFO: Payment processed for order #ORD-12345
INFO: Daily backup completed successfully
INFO: Connected to database: prod-db-01
Best Practice: INFO should tell the story of what your application is doing
WARN / WARNING
Potentially harmful situations that don't prevent operation
When to Use
- Deprecated API usage
- Suboptimal configuration
- Retry attempts (before failure)
- Resource usage approaching limits
- Unexpected but recoverable conditions
- Fallback behavior triggered
Characteristics
- Volume: Low to moderate
- Production: Enabled
- Audience: Operations, developers
- Action Required: Review and investigate
Example Messages
WARN: API endpoint /old-api is deprecated, use /api/v2
WARN: Retrying failed request to payment service (attempt 2/3)
WARN: Connection pool at 80% capacity
WARN: Cache server unavailable, using local cache
WARN: Response time exceeded 500ms: 1,245ms
Rule of Thumb: WARN = "This worked, but you should look at this"
ERROR
Error events that still allow the application to continue
When to Use
- Failed operations (request failed, save failed)
- Unhandled exceptions in request handlers
- Database connection failures
- Failed external service calls (after retries)
- Data validation failures
- File I/O errors
Characteristics
- Volume: Low (should be rare)
- Production: Enabled
- Audience: Operations, on-call engineers
- Action Required: Immediate investigation
Example Messages
ERROR: Failed to process payment for order #ORD-12345: TimeoutException
ERROR: Database connection lost: Could not connect to prod-db-01
ERROR: Unable to send email notification: SMTP server unreachable
ERROR: Invalid data in request: User ID cannot be null
ERROR: Failed to write to file /var/log/app.log: Disk full
Important: ERROR should always include context (stack trace, request ID, user ID)
FATAL / CRITICAL
Severe errors that cause application shutdown or inability to function
When to Use
- Application cannot start (missing critical config)
- Out of memory errors
- Database completely unavailable
- Critical system resource unavailable
- Security violations requiring shutdown
- Data corruption detected
Characteristics
- Volume: Very low (rarely seen)
- Production: Enabled
- Audience: On-call engineers, management
- Action Required: Emergency response
Example Messages
FATAL: Cannot connect to database, application shutting down
FATAL: Out of memory, cannot allocate heap space
FATAL: Configuration file missing: /etc/app/config.yaml
FATAL: SSL certificate expired, cannot start HTTPS server
FATAL: Critical dependency 'payment-service' unreachable
Critical: FATAL logs should trigger immediate alerts (PagerDuty, phone calls)
Best Practices
General Logging Guidelines
- Be consistent: Use the same format and structure across your application
- Include context: Request IDs, user IDs, timestamps, correlation IDs
- Be concise: Log messages should be clear and to the point
- Use structured logging: JSON format for machine parsing
- Don't log sensitive data: Passwords, tokens, credit cards, PII
- Think about volume: Excessive logging impacts performance and costs
What to Log
DO Log:
- Request/response metadata
- Errors with stack traces
- Performance metrics
- Business events
- Security events
- State changes
- External API calls
DON'T Log:
- Passwords or secrets
- Credit card numbers
- Social security numbers
- Authentication tokens
- Complete request bodies
- Personal health information
- Encryption keys
Log Levels in Different Environments
| Environment | Recommended Level | Reasoning |
|---|---|---|
| Development | DEBUG | Maximum visibility for debugging |
| Testing/Staging | INFO | Similar to production |
| Production | INFO or WARN | Balance visibility and performance |
| High-traffic Prod | WARN | Reduce volume and costs |
Structured Logging Example
{
"timestamp": "2024-01-15T14:30:45.123Z",
"level": "ERROR",
"service": "payment-api",
"requestId": "req-abc-123",
"userId": "user-456",
"message": "Payment processing failed",
"error": {
"type": "TimeoutException",
"message": "Connection timeout after 5000ms",
"stack": "..."
},
"metadata": {
"orderId": "ORD-789",
"amount": 99.99,
"currency": "USD",
"gateway": "stripe"
}
}Quick Reference
| DEBUG | Diagnostic info |
| INFO | General events |
| WARN | Potential issues |
| ERROR | Operation failed |
| FATAL | App shutting down |
Decision Tree
Will the app crash?
Yes → FATAL
Did an operation fail?
Yes → ERROR
Is this unexpected but handled?
Yes → WARN
Is this a significant event?
Yes → INFO
Is this for debugging?
Yes → DEBUG
Related Topics
- Log aggregation (ELK, Splunk)
- Distributed tracing
- Metrics vs Logs
- Log retention policies
- GDPR compliance
- Log analysis tools