| name | logging-guide |
| scope | universal |
| description | Implement structured logging with proper log levels and sensitive data handling.
Use when: adding logging, debugging, setting up observability.
Keywords: logging, log level, structured logging, observability, 日誌, 記錄, 結構化日誌.
|
Logging Guide
Language: English | 繁體中文
Version: 1.0.0
Last Updated: 2025-12-30
Applicability: Claude Code Skills
Core Standard: This skill implements Logging Standards. For comprehensive methodology documentation, refer to the core standard.
Purpose
This skill helps implement consistent, structured, and actionable application logs across all environments.
Quick Reference
Log Levels
| Level | Code | When to Use | Production |
|---|
| TRACE | 10 | Very detailed debugging info | Off |
| DEBUG | 20 | Detailed debugging info | Off |
| INFO | 30 | Normal operation events | On |
| WARN | 40 | Potential issues, recoverable | On |
| ERROR | 50 | Errors that need attention | On |
| FATAL | 60 | Critical failures | On |
Level Selection Decision Tree
Is it debugging only? → DEBUG (off in prod)
Normal operation completed? → INFO
Something unexpected but OK? → WARN
Operation failed? → ERROR
App cannot continue? → FATAL
When to Use Each Level
| Level | Examples |
|---|
| TRACE | Function entry/exit, loop iterations, variable values |
| DEBUG | State changes, configuration values, query parameters |
| INFO | App startup/shutdown, user actions, scheduled tasks |
| WARN | Deprecated API, retry attempts, resource approaching limits |
| ERROR | Failed operations, caught exceptions, integration failures |
| FATAL | Unrecoverable errors, startup failures, lost critical resources |
Structured Logging
Required Fields
{
"timestamp": "2025-01-15T10:30:00.123Z",
"level": "INFO",
"message": "User login successful",
"service": "auth-service",
"environment": "production"
}
Recommended Fields
{
"timestamp": "2025-01-15T10:30:00.123Z",
"level": "INFO",
"message": "User login successful",
"service": "auth-service",
"environment": "production",
"trace_id": "abc123",
"span_id": "def456",
"user_id": "usr_12345",
"request_id": "req_67890",
"duration_ms": 150,
"http_method": "POST",
"http_path": "/api/v1/login",
"http_status": 200
}
Field Naming Conventions
Use snake_case and prefix with domain:
| Domain | Common Fields |
|---|
| HTTP | http_method, http_path, http_status, http_duration_ms |
| Database | db_query_type, db_table, db_duration_ms, db_rows_affected |
| Queue | queue_name, queue_message_id, queue_delay_ms |
| User | user_id, user_role, user_action |
| Request | request_id, trace_id, span_id |
Detailed Guidelines
For complete standards, see:
AI-Optimized Format (Token-Efficient)
For AI assistants, use the YAML format files for reduced token usage:
- Base standard:
ai/standards/logging.ai.yaml
Sensitive Data Handling
Never Log
- Passwords or secrets
- API keys or tokens
- Credit card numbers
- Social security numbers
- Full authentication tokens
Mask or Redact
logger.info('Login attempt', { password: userPassword });
logger.info('Login attempt', { password: '***REDACTED***' });
logger.info('Card processed', { last_four: '4242' });
PII Handling
- Log user IDs, not email addresses when possible
- Use hashed identifiers for sensitive lookups
- Configure data retention policies
Error Logging
Required Error Fields
{
"level": "ERROR",
"message": "Database connection failed",
"error_type": "ConnectionError",
"error_message": "Connection refused",
"error_code": "ECONNREFUSED",
"stack": "Error: Connection refused\n at connect (/app/db.js:45:11)..."
}
Error Context
Always include:
- What operation was attempted
- Relevant identifiers (user_id, request_id)
- Input parameters (sanitized)
- Retry count if applicable
logger.error('Failed to process order', {
error_type: err.name,
error_message: err.message,
order_id: orderId,
user_id: userId,
retry_count: 2,
stack: err.stack
});
Log Format
JSON Format (Production)
{"timestamp":"2025-01-15T10:30:00.123Z","level":"INFO","message":"Request completed","request_id":"req_123","duration_ms":45}
Human-Readable (Development)
2025-01-15T10:30:00.123Z [INFO] Request completed request_id=req_123 duration_ms=45
Performance Considerations
Log Volume by Environment
| Environment | Level | Strategy |
|---|
| Development | DEBUG | All logs |
| Staging | INFO | Most logs |
| Production | INFO | Sampling for high-volume |
High-Volume Endpoints
- Use sampling (log 1 in 100)
- Aggregate metrics instead of individual logs
- Use separate log streams
Checklist
Required Fields
Security
Configuration Detection
This skill supports project-specific configuration.
Detection Order
- Check for existing logging library configuration
- Check
CONTRIBUTING.md for logging guidelines
- If not found, default to structured JSON logging
First-Time Setup
If no logging standard found:
- Suggest: "This project hasn't configured logging standards. Would you like to set up structured logging?"
- Suggest documenting in
CONTRIBUTING.md:
## Logging Standards
### Log Levels
- DEBUG: Development only, detailed diagnostic info
- INFO: Normal operations (startup, user actions, tasks)
- WARN: Unexpected but recoverable situations
- ERROR: Failures that need investigation
### Required Fields
All logs must include: timestamp, level, message, service, request_id
### Sensitive Data
Never log: passwords, tokens, credit cards, SSN
Next Steps Guidance | 下一步引導
After /logging completes, the AI assistant should suggest:
日誌標準已掌握。建議下一步 / Logging standards understood. Suggested next steps:
- 根據日誌指南在程式碼中實作結構化日誌 ⭐ Recommended / 推薦 — 立即將日誌標準應用到專案 / Apply logging standards to the project immediately
- 執行
/errors 設計錯誤碼以配合日誌系統 — 讓錯誤追蹤更有效率 / Make error tracking more efficient
- 執行
/sdd 將可觀測性需求納入規格 — 確保日誌需求在規格中有定義 / Ensure logging requirements are defined in specs
Related Standards
Version History
| Version | Date | Changes |
|---|
| 1.0.0 | 2025-12-30 | Initial release |
License
This skill is released under CC BY 4.0.
Source: universal-dev-standards
