日誌指南

语言: English | 简体中文

版本: 1.0.0 最後更新: 2025-12-30 適用範圍: 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 優化格式（节省 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

效能考量

各環境的日誌量

| 環境 | 层级 | 策略 | |------|------|------| | 开发 | DEBUG | 所有日誌 | | 测试 | INFO | 大部分日誌 | | 生产 | INFO | 高流量端点採样 |

高流量端点

使用採样（每 100 筆记录 1 筆）
聚合指標而非个别日誌
使用獨立的日誌串流

检查清单

必要欄位

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

安全性

[ ] 没有密码或机密
[ ] 没有完整 Token
[ ] PII 已遮罩或雜湊
[ ] 信用卡從不记录
[ ] 保留政策已设置

设置偵测

此技能支援项目特定设置。

偵测順序

检查現有的日誌程序庫设置
检查 CONTRIBUTING.md 中的日誌指南
若無找到，预设使用结构化 JSON 日誌

首次设置

若未找到日誌标准：

建议：「此项目尚未设置日誌标准。您要设置结构化日誌嗎？」
建议在 CONTRIBUTING.md 中记录：

## 日誌标准

### 日誌层级
- DEBUG: 僅开发環境，详细診斷信息
- INFO: 正常操作（啟动、使用者操作、任务）
- WARN: 意外但可恢復的情况
- ERROR: 需要調查的失败

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

### 敏感数据
絕不记录：密码、Token、信用卡、身分证字号

版本历史

| 版本 | 日期 | 变更 | |------|------|------| | 1.0.0 | 2025-12-30 | 初始發布 |

授权

此技能採用 CC BY 4.0 授权。

來源: universal-dev-standards

logging

日誌指南

目的

快速參考

日誌层级

层级选择决策樹

各层级使用时机

结构化日誌

必要欄位

建议欄位

欄位命名慣例

详细指南

AI 優化格式（节省 Token）

敏感数据处理

絕对不要记录

遮罩或编修

PII 处理

错误日誌

必要的错误欄位

错误上下文

日誌格式

JSON 格式（生产環境）

人类可读格式（开发環境）

效能考量

各環境的日誌量

高流量端点

检查清单

必要欄位

安全性

设置偵测

偵测順序

首次设置

相关标准

版本历史

授权