logging-guide

Logging Guide

Language: English | 繁體中文

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
WARN	Deprecated API, retry attempts, resource approaching limits
ERROR	Failed operations, caught exceptions, integration failures
FATAL	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:

Event id	When	Level	Core required fields	Must NOT log
application_startup	After boot, before accepting requests	INFO	app_name, version, git_sha, environment, hostname, pid, listening_endpoints	secrets, full connection strings
request_received	First time middleware sees a request	INFO / DEBUG	method, path, source_ip, request_id	request body, auth headers
validation_failure	schema / ModelState / DTO validation rejects	WARN	request_id, path, missing_fields[], payload_shape (keys only)	field values, PII
authentication_failure	login / token verification fails	WARN	uid (attempted), source_ip, failure_reason	password, token value
outbound_call_start	An outbound HTTP/RPC call is initiated	INFO	target_url (host+path), request_id propagated, timeout_ms	credentials, bearer tokens
outbound_call_complete	An external call returns or fails	INFO / WARN / ERROR	status_code or failure_phase (dns/tcp/tls/http), elapsed_ms, retries	response body with PII
business_event	A state-changing business operation completes	INFO	operation_name, actor, target ids, outcome	full record payload, PII
heartbeat	Long-running background service, ≥ 1× / 60 s	INFO	service_name, queue_depth, items_processed_since_last_heartbeat	—
shutdown	Process exits (graceful or fatal)	INFO / ERROR	app_name, signal/reason, uptime_seconds, pending_work_count	—

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.

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:

• Logging Standards

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

// Bad
logger.info('Login attempt', { password: userPassword });

// Good
logger.info('Login attempt', { password: '***REDACTED***' });

// Good - mask partial
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

Log File Rotation

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

1. Check for existing logging library configuration
2. Check CONTRIBUTING.md for logging guidelines
3. If not found, default to structured JSON logging

First-Time Setup

If no logging standard found:

1. Suggest: "This project hasn't configured logging standards. Would you like to set up structured logging?"
2. 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

• Logging Standards
• Error Code Standards

---

Version History

Version	Date	Changes
1.4.0	2026-06-19	Added: Mandatory Events section (9 canonical events) to close skill↔standard content drift; aligned version with core Logging Standards v1.4.0 (XSPEC-070 Phase 2)
1.1.0	2026-05-26	Added: Log File Rotation section with cross-link to core standard rotation policy; Rotation checklist (XSPEC-232)
1.0.0	2025-12-30	Initial release

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards