القائمة
[UDS] 實作結構化日誌，包含正確的日誌層級和敏感資料處理
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/AsiaOstrich/universal-dev-standards --skill loggingيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
[UDS] 以 Claude 原生 Agent tool 编排多任务执行计划（DAG-based，无外部引擎）。 Use when: executing a plan.json file with parallel/sequential task dependencies. Keywords: orchestrate, plan, execute, DAG, task plan, 编排, 执行计划, 并行.
[UDS] 从 Spec 文档、OpenSpec 变更或自由文本需求生成 plan.json。 Use when: converting specifications into executable task plans for /orchestrate. Keywords: plan, spec, task plan, 计划, 规格, 任务, plan.json, DAG.
[UDS] AI 辅助 git push 安全层：质量门禁 + 协作护栏。 Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches. Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, 推送, 保护分支, 质量门禁.
عرض SKILL.md
استنادا إلى تصنيف SOC المهني
| name | logging |
| description | [UDS] 實作結構化日誌，包含正確的日誌層級和敏感資料處理 |
| source | ../../../../skills/logging-guide/SKILL.md |
| source_version | 1.4.0 |
| translation_version | 1.4.0 |
| last_synced | "2026-07-08T00:00:00.000Z" |
| source_hash | cf114de1df86 |
| status | current |
語言: English | 繁體中文
版本: 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[], payload_shape（僅 keys） | 欄位值、PII |
authentication_failure | 登入 / token 驗證失敗時 | WARN | uid（嘗試值）, source_ip, failure_reason | password、token 值 |
outbound_call_start | 發起對外 HTTP/RPC 呼叫時 | INFO | target_url（host+path）, 傳遞的 request_id, timeout_ms | credentials、bearer tokens |
outbound_call_complete | 外部呼叫返回或失敗時 | INFO / WARN / ERROR | status_code 或 failure_phase（dns/tcp/tls/http）, elapsed_ms, retries | 含 PII 的 response body |
business_event | 具狀態改變的業務操作完成時 | INFO | operation_name, actor, target ids, outcome | 完整 record payload、PII |
heartbeat | 長期執行的背景服務，≥ 1 次 / 60 秒 | INFO | service_name, queue_depth, items_processed_since_last_heartbeat | — |
shutdown | 行程結束時（正常或致命錯誤） | INFO / ERROR | app_name, signal/reason, uptime_seconds, pending_work_count | — |
為何是這些事件——每一項都補上一個真實的事故盲區：靜默的 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 並加上領域前綴：
| 領域 | 常用欄位 |
|---|---|
| HTTP | http_method, http_path, http_status, http_duration_ms |
| 資料庫 | db_query_type, db_table, db_duration_ms, db_rows_affected |
| 佇列 | queue_name, queue_message_id, queue_delay_ms |
| 使用者 | user_id, user_role, user_action |
| 請求 | request_id, trace_id, span_id |
完整標準請參考：
AI 助手可使用 YAML 格式檔案以減少 Token 使用量：
ai/standards/logging.ai.yaml// 不好
logger.info('登入嘗試', { password: userPassword });
// 好
logger.info('登入嘗試', { password: '***已編修***' });
// 好 - 部分遮罩
logger.info('卡片已處理', { last_four: '4242' });
{
"level": "ERROR",
"message": "資料庫連線失敗",
"error_type": "ConnectionError",
"error_message": "連線被拒絕",
"error_code": "ECONNREFUSED",
"stack": "Error: Connection refused\n at connect (/app/db.js:45:11)..."
}
務必包含：
logger.error('處理訂單失敗', {
error_type: err.name,
error_message: err.message,
order_id: orderId,
user_id: userId,
retry_count: 2,
stack: err.stack
});
{"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
| 環境 | 層級 | 策略 |
|---|---|---|
| 開發 | DEBUG | 所有日誌 |
| 測試 | INFO | 大部分日誌 |
| 生產 | INFO | 高流量端點採樣 |
基於檔案的 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）及真實事故失敗模式參考的完整規格：請參閱核心標準的日誌檔案輪替政策。
rollingInterval: Day 或等效設定）fileSizeLimitBytes + rollOnFileSizeLimit: true）retainedFileCountLimit ≥ N×7（N = 每日最大輪替次數）此技能支援專案特定設定。
CONTRIBUTING.md 中的日誌指南若未找到日誌標準：
CONTRIBUTING.md 中記錄：## 日誌標準
### 日誌層級
- DEBUG: 僅開發環境，詳細診斷資訊
- INFO: 正常操作（啟動、使用者操作、任務）
- WARN: 意外但可恢復的情況
- ERROR: 需要調查的失敗
### 必要欄位
所有日誌必須包含：timestamp, level, message, service, request_id
### 敏感資料
絕不記錄：密碼、Token、信用卡、身分證字號
| 版本 | 日期 | 變更 |
|---|---|---|
| 1.4.0 | 2026-06-19 | 新增：強制事件章節（9 個標準事件），消弭技能與核心標準之間的內容漂移；版號與核心日誌標準 v1.4.0 對齊（XSPEC-070 Phase 2） |
| 1.1.0 | 2026-05-26 | 新增：日誌檔案輪替章節及指向核心標準輪替政策的交叉連結；輪替清單（XSPEC-232） |
| 1.0.0 | 2025-12-30 | 初始發布 |
此技能採用 CC BY 4.0 授權。
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