logging

name	logging
description	实现结构化日志，包含正确的日志级别和敏感数据处理。 使用时机：新增日志、调试、设置可观测性。 关键字：logging, log level, structured logging, observability, 日志, 记录, 结构化日志。
source	../../../../skills/logging-guide/SKILL.md
source_version	1.4.0
translation_version	1.4.0
last_synced	"2026-07-08T00:00:00.000Z"
source_hash	cf114de1df86
status	current

日志指南

语言: 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