日誌指南

语言: English | 简体中文

版本: 1.0.0 最後更新: 2025-12-30 適用範圍: Claude Code Skills

目的

此技能幫助在所有環境中实作一致、结构化且可操作的应用程序日誌。

快速參考

日誌层级

层级选择决策樹

只用於除錯？               → DEBUG（生产環境关閉）
正常操作完成？             → INFO
意外但没問題的情况？       → WARN
操作失败？                 → 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 并加上領域前綴：

详细指南

完整标准請參考：

• 日誌标准

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

效能考量

各環境的日誌量

高流量端点

• 使用採样（每 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、信用卡、身分证字号

相关标准

• 日誌标准
• 错误码标准

版本历史

授权

此技能採用 CC BY 4.0 授权。

來源: universal-dev-standards