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.
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.
Version: 1.4.0
Last Updated: 2026-06-19
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
Unrecoverable errors, startup failures, lost critical resources
Mandatory Events
Formatting every log perfectly but never firing at the moment that matters is
worse than useless — it gives false confidence during an incident. The core
standard defines 9 canonical events that MUST produce a log entry. A logging
setup that follows the level/field rules but omits these is "compliant on paper,
materially silent". Always implement all 9:
Why these exact events — each closes a real incident blind spot: a silent
validation_failure hides un-logged payloads; authentication_failure without
uid/source_ip is un-investigable; a missing heartbeat means a 0-byte log
file goes unnoticed; absent outbound_call_* turns "send failed" into a 2-day
hunt with no trace of the call.
A background service that writes no INFO/WARN/ERROR within 60 s MUST emit a
heartbeat; if none appears for ≥ 2× the interval (≥ 120 s), a silence detector
MUST alert.
For the full catalog (each event's when / must_log / must_NOT_log /
rationale and compliant examples), see the Mandatory Events section of the
core Logging Standards.
File-based log sinks MUST set both rotation triggers — time-based and size-based. Default size caps in popular libraries (Serilog 1 GB, log4j/Winston/Python RotatingFileHandler no cap) cause silent data loss in production.
✓ rollingInterval: Day # time-based
✓ fileSizeLimitBytes: 104857600 (100 MB) # size-based
✓ rollOnFileSizeLimit: true # roll, do NOT drop
✓ retainedFileCountLimit: ≥ N*7 # N = max rolls/day
When a log file reaches ≥ 90% of fileSizeLimitBytes at expected end-of-day, investigate the noise root cause (noisy retry loop / unbounded debug logging / stack-trace flood) before raising the cap.
Full specification with per-language recipes (.NET Serilog / Python / Java log4j2 / Node Winston) and the real-incident failure-mode reference: see Log File Rotation Policy in the core standard.
Checklist
Required Fields
timestamp (ISO 8601)
level
message
service name
request_id or trace_id
Security
No passwords or secrets
No full tokens
PII masked or hashed
Credit cards never logged
Retention policies configured
Rotation
Time-based rotation set (rollingInterval: Day or equivalent)
Size-based rotation set (fileSizeLimitBytes + rollOnFileSizeLimit: true)
retainedFileCountLimit ≥ N×7 (N = max rolls/day)
90% size SOP defined (investigate noise, do not just raise cap)
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
