Logging Guide

日誌指南

語言: English | 繁體中文

版本: 1.4.0 最後更新: 2026-06-19 適用範圍: Claude Code Skills

目的

此技能幫助在所有環境中實作一致、結構化且可操作的應用程式日誌。

快速參考

日誌層級

層級選擇決策樹

只用於除錯？               → DEBUG（生產環境關閉）
正常操作完成？             → INFO
意外但沒問題的情況？       → WARN
操作失敗？                 → ERROR
應用程式無法繼續？         → FATAL

各層級使用時機

強制事件

把每則日誌格式化得再完美，但在真正關鍵的時刻卻從不觸發，比什麼都沒有還糟——它會在事故當下給人虛假的安心感。核心標準定義了9 個必須產生日誌記錄的標準事件。若日誌設定遵守層級／欄位規則卻遺漏這些事件，就是「規範上合格、實質上沉默」。務必全部實作這 9 項：

為何是這些事件——每一項都補上一個真實的事故盲區：靜默的 validation_failure 會隱藏未記錄的 payload；authentication_failure 若缺 uid／source_ip 就無法調查；缺少 heartbeat 代表 0-byte 的日誌檔不會被察覺；沒有 outbound_call_* 會讓「送出失敗」變成一場找不到任何呼叫痕跡、耗時 2 天的追查。

背景服務若在 60 秒內未寫入任何 INFO/WARN/ERROR，必須發出一則 heartbeat；若連續 ≥ 2 倍間隔（≥ 120 秒）都沒有出現，沉默偵測器必須告警。

完整目錄（每個事件的 when／must_log／must_NOT_log／rationale 及合規範例），請參閱核心日誌標準的強制事件章節。

結構化日誌

必要欄位

{
  "timestamp": "2025-01-15T10:30:00.123Z",
  "level": "INFO",
  "message": "使用者登入成功",
  "service": "auth-service",
  "environment": "production"
}

建議欄位

{
  "timestamp": "2025-01-15T10:30:00.123Z",
  "level": "INFO",
  "message": "使用者登入成功",
  "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
}

欄位命名慣例

使用 snake_case 並加上領域前綴：

詳細指南

完整標準請參考：

• 日誌標準

AI 優化格式（節省 Token）

AI 助手可使用 YAML 格式檔案以減少 Token 使用量：

• 基礎標準：ai/standards/logging.ai.yaml

敏感資料處理

絕對不要記錄

• 密碼或機密
• API 金鑰或 Token
• 信用卡號碼
• 身分證字號
• 完整的認證 Token

遮罩或編修

// 不好
logger.info('登入嘗試', { password: userPassword });

// 好
logger.info('登入嘗試', { password: '***已編修***' });

// 好 - 部分遮罩
logger.info('卡片已處理', { last_four: '4242' });

PII 處理

• 盡可能記錄使用者 ID 而非電子郵件
• 對敏感查詢使用雜湊識別碼
• 設定資料保留政策

錯誤日誌

必要的錯誤欄位

{
  "level": "ERROR",
  "message": "資料庫連線失敗",
  "error_type": "ConnectionError",
  "error_message": "連線被拒絕",
  "error_code": "ECONNREFUSED",
  "stack": "Error: Connection refused\n    at connect (/app/db.js:45:11)..."
}

錯誤上下文

務必包含：

• 嘗試的操作是什麼
• 相關識別碼（user_id, request_id）
• 輸入參數（已清理）
• 重試次數（如適用）

logger.error('處理訂單失敗', {
  error_type: err.name,
  error_message: err.message,
  order_id: orderId,
  user_id: userId,
  retry_count: 2,
  stack: err.stack
});

日誌格式

JSON 格式（生產環境）

{"timestamp":"2025-01-15T10:30:00.123Z","level":"INFO","message":"請求完成","request_id":"req_123","duration_ms":45}

人類可讀格式（開發環境）

2025-01-15T10:30:00.123Z [INFO] 請求完成 request_id=req_123 duration_ms=45

效能考量

各環境的日誌量

高流量端點

• 使用採樣（每 100 筆記錄 1 筆）
• 聚合指標而非個別日誌
• 使用獨立的日誌串流

日誌檔案輪替

基於檔案的 log sink 必須同時設定兩種輪替觸發器——時間輪替與大小輪替。常見函式庫的預設大小上限（Serilog 1 GB、log4j/Winston/Python RotatingFileHandler 無上限）在正式環境中會造成靜默資料遺失。

✓ rollingInterval: Day                    # 時間輪替
✓ fileSizeLimitBytes: 104857600 (100 MB)  # 大小輪替
✓ rollOnFileSizeLimit: true               # 輪替，不要丟棄
✓ retainedFileCountLimit: ≥ N*7           # N = 每日最大輪替次數

當日誌檔案在預期的每日結束時達到 fileSizeLimitBytes 的 ≥ 90%，調查噪音根因（嘈雜的重試迴圈 / 不受限制的 debug 日誌 / stack trace 洪流），不要只提高上限。

含各語言設定範例（.NET Serilog / Python / Java log4j2 / Node Winston）及真實事故失敗模式參考的完整規格：請參閱核心標準的日誌檔案輪替政策。

檢查清單

必要欄位

• timestamp（ISO 8601）
• level
• message
• service name
• request_id 或 trace_id

安全性

• 沒有密碼或機密
• 沒有完整 Token
• PII 已遮罩或雜湊
• 信用卡從不記錄
• 保留政策已設定

輪替

• 已設定時間輪替（rollingInterval: Day 或等效設定）
• 已設定大小輪替（fileSizeLimitBytes + rollOnFileSizeLimit: true）
• retainedFileCountLimit ≥ N×7（N = 每日最大輪替次數）
• 已定義 90% 大小 SOP（調查噪音，勿只提高上限）

設定偵測

此技能支援專案特定設定。

偵測順序

1. 檢查現有的日誌程式庫設定
2. 檢查 CONTRIBUTING.md 中的日誌指南
3. 若無找到，預設使用結構化 JSON 日誌

首次設定

若未找到日誌標準：

1. 建議：「此專案尚未設定日誌標準。您要設定結構化日誌嗎？」
2. 建議在 CONTRIBUTING.md 中記錄：

## 日誌標準

### 日誌層級
- DEBUG: 僅開發環境，詳細診斷資訊
- INFO: 正常操作（啟動、使用者操作、任務）
- WARN: 意外但可恢復的情況
- ERROR: 需要調查的失敗

### 必要欄位
所有日誌必須包含：timestamp, level, message, service, request_id

### 敏感資料
絕不記錄：密碼、Token、信用卡、身分證字號

相關標準

• 日誌標準
• 錯誤碼標準

版本歷史

授權

此技能採用 CC BY 4.0 授權。

來源: universal-dev-standards

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