logging-guide

# 日誌指南 > **語言**: [English](../../../../skills/logging-guide/SKILL.md) | 繁體中文 **版本**: 1.4.0 **最後更新**: 2026-06-19 **適用範圍**: Claude Code Skills --- ## 目的 此技能幫助在所有環境中實作一致、結構化且可操作的應用程式日誌。 ## 快速參考 ### 日誌層級 | 層級 | 代碼 | 使用時機 | 生產環境 | |------|------|----------|----------| | **TRACE** | 10 | 非常詳細的除錯資訊 | 關閉 | | **DEBUG** | 20 | 詳細的除錯資訊 | 關閉 | | **INFO** | 30 | 正常操作事件 | 開啟 | | **WARN** | 40 | 潛在問題，可恢復 | 開啟 | | **ERROR** | 50 | 需要注意的錯誤 | 開啟 | | **FATAL** | 60 | 嚴重故障 | 開啟 | ### 層級選擇決策樹 ``` 只用於除錯？ → DEBUG（生產環境關閉） 正常操作完成？ → INFO 意外但沒問題的情況？ → WARN 操作失敗？ → ERROR 應用程式無法繼續？ → FATAL ``` ### 各層級使用時機 | 層級 | 範例 | |------|------| | **TRACE** | 函式進入/離開、迴圈迭代、變數值 | | **DEBUG** | 狀態變更、設定值、查詢參數 | | **INFO** | 應用啟動/關閉、使用者操作、排程任務 | | **WARN** | 已棄用 API、重試嘗試、資源接近上限 | | **ERROR** | 失敗的操作、捕獲的例外、整合失敗 | | **FATAL** | 無法恢復的錯誤、啟動失敗、失去關鍵資源 | ## 強制事件 把每則日誌格式化得再完美，但**在真正關鍵的時刻卻從不觸發**，比什麼都沒有還糟——它會在事故當下給人虛假的安心感。核心標準定義了**9 個必須產生日誌記錄的標準事件**。若日誌設定遵守層級／欄位規則卻遺漏這些事件，就是「規範上合格、實質上沉默」。務必全部實作這 9 項： | 事件 id | 時機 | 層級 | 核心必要欄位 | 不可記錄 | |----------|------|-------|----------------------|--------------| | `application_startup` | 開機後、**接受請求前** | INFO | app_name, version, git_sha, environment, hostname, pid, listening_endpoints | secrets、完整連線字串 | | `request_received` | Middleware 首次看到請求時 | INFO / DEBUG | method, path, source_ip, request_id | request body、auth headers | | `validation_failure` | schema / ModelState / DTO 驗證拒絕時 | WARN | request_id, path, missing_fields[...