Menu
[UDS] 實作結構化日誌，包含正確的日誌層級和敏感資料處理
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
[UDS] 引導 CI/CD 管線設計、配置和優化
Guide CI/CD pipeline design, configuration, and optimization. Use when: setting up pipelines, optimizing build times, configuring deployment stages. Keywords: CI/CD, pipeline, GitHub Actions, deployment, build.
在编写规格前进行结构化 AI 辅助头脑风暴。 使用时机：功能规划、创意发想、问题定义。 关键字：brainstorm, persona, multi-critic, HMW, SCAMPER, 头脑风暴, 发想。
[UDS] 在撰寫規格前進行結構化 AI 輔助腦力激盪
[UDS] Structured AI-assisted brainstorming before spec creation
[UDS] 从规格衍生 BDD 场景、TDD 骨架或 ATDD 表格
| name | logging |
| description | [UDS] 實作結構化日誌，包含正確的日誌層級和敏感資料處理 |
| source | ../../../../skills/logging-guide/SKILL.md |
| source_version | 1.1.0 |
| translation_version | 1.1.0 |
| last_synced | "2026-06-10T00:00:00.000Z" |
| source_hash | 6b7244c91aa0 |
| status | current |
語言: English | 繁體中文
版本: 1.1.0 最後更新: 2026-05-26 適用範圍: 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 | 無法恢復的錯誤、啟動失敗、失去關鍵資源 |
{
"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.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