asiaostrich/logging

日志指南

语言: English | 简体中文

版本: 1.4.0 最后更新: 2026-06-19 适用范围: Claude Code Skills

---

核心标准: 本技能实现 日志标准。如需面向任何 AI 工具的完整方法论文档，请参阅核心标准。

目的

此技能帮助在所有环境中实现一致、结构化且可操作的应用程序日志。

快速参考

日志级别

| 级别 | 代码 | 使用时机 | 生产环境 | |------|------|----------|----------| | 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 及合规示例），请参见核心 Logging Standards 的 强制事件 章节。

结构化日志

必要字段

{
  "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 密钥或令牌
• 信用卡号码
• 身份证号码
• 完整的认证令牌

脱敏处理

// 不好
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 条）
• 聚合指标而非单独日志
• 使用独立的日志流

日志文件轮转

基于文件的日志接收器必须同时设置两个轮转触发器——基于时间和基于大小。常见库（Serilog 1 GB、log4j/Winston/Python RotatingFileHandler 无上限）的默认大小上限会导致生产环境中的静默数据丢失。

✓ rollingInterval: Day                    # 基于时间
✓ fileSizeLimitBytes: 104857600 (100 MB)  # 基于大小
✓ rollOnFileSizeLimit: true               # 轮转，不丢弃
✓ retainedFileCountLimit: ≥ N*7           # N = 每天最大轮转次数

当日志文件大小在预计当天结束时达到 fileSizeLimitBytes 的 ≥ 90%，先调查噪声根因（嘈杂的重试循环 / 意外启用的调试日志 / 堆栈跟踪洪流），再提高上限。

含各语言（.NET Serilog / Python / Java log4j2 / Node Winston）配置示例及真实事故失败模式参考的完整规范，请参见核心标准中的 日志文件轮转策略。

检查清单

必要字段

• [ ] timestamp（ISO 8601）
• [ ] level
• [ ] message
• [ ] 服务名称
• [ ] request_id 或 trace_id

安全性

• [ ] 无密码或密钥
• [ ] 无完整令牌
• [ ] PII 已脱敏或哈希
• [ ] 信用卡从不记录
• [ ] 保留策略已配置

轮转

• [ ] 已设置时间轮转（rollingInterval: Day 或同等配置）
• [ ] 已设置大小轮转（fileSizeLimitBytes + rollOnFileSizeLimit: true）
• [ ] retainedFileCountLimit ≥ N×7（N = 每天最大轮转次数）
• [ ] 已定义 90% 大小 SOP（调查噪声，不要盲目提高上限）

---

配置检测

本技能支持项目特定配置。

检测顺序

1. 检查现有的日志库配置
2. 检查 CONTRIBUTING.md 中的日志指南
3. 若未找到，默认使用结构化 JSON 日志

首次设置

若未找到日志标准：

1. 建议："此项目尚未配置日志标准。是否要设置结构化日志？"
2. 建议在 CONTRIBUTING.md 中记录：

## 日志标准

### 日志级别
- DEBUG: 仅开发环境，详细诊断信息
- INFO: 正常操作（启动、用户操作、任务）
- WARN: 意外但可恢复的情况
- ERROR: 需要调查的失败

### 必要字段
所有日志必须包含：timestamp, level, message, service, request_id

### 敏感数据
绝不记录：密码、令牌、信用卡、身份证号码

---

下一步引导

/logging 完成后，AI 助手应建议：

日志标准已掌握。建议下一步 / Logging standards understood. Suggested next steps:

• 根据日志指南在代码中实现结构化日志 ⭐ 推荐 — 立即将日志标准应用到项目
• 执行 /errors 设计错误码以配合日志系统 — 让错误追踪更高效
• 执行 /sdd 将可观测性需求纳入规格 — 确保日志需求在规格中有定义

---

相关标准

• 日志标准
• 错误码标准

---

版本历史

| 版本 | 日期 | 变更 | |------|------|------| | 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 发布。

来源: universal-dev-standards