日誌指南

语言: 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 已遮罩或雜湊
• 信用卡從不记录
• 保留政策已设置

---

设置偵测

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

偵测順序

1. 检查現有的日誌程序庫设置
2. 检查

   CONTRIBUTING.md

   中的日誌指南
3. 若無找到，预设使用结构化 JSON 日誌

首次设置

若未找到日誌标准：

1. 建议：「此项目尚未设置日誌标准。您要设置结构化日誌嗎？」
2. 建议在

   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