Skip to main content
logging 实现结构化日志，包含正确的日志级别和敏感数据处理。
使用时机：新增日志、调试、设置可观测性。
关键字：logging, log level, structured logging, observability, 日志, 记录, 结构化日志。
Zur Installation springen Skills Marktplatz Entdecken und erkunden Sie KI-Skills, die von der Community erstellt wurden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Prompt-Details anzeigen Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
npx skills add https://github.com/AsiaOstrich/universal-dev-standards --skill loggingDer Befehl bleibt in einer Zeile. Scrollen Sie horizontal, um ihn vor dem Kopieren vollständig zu prüfen.
Sie bevorzugen eine lokale Kopie? Laden Sie die Dateien herunter, die SkillsMP derzeit vorliegen.
ZIP herunterladen Herunterladen... Mehr aus diesem Repository
Verwandte Berufe SOC
Basierend auf der SOC-Berufsklassifikation
[UDS] AI 辅助 git push 安全层：质量门禁 + 协作护栏。
Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches.
Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, 推送, 保护分支, 质量门禁.
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_receivedMiddleware 首次看到请求时 INFO / DEBUG method, path, source_ip, request_id request body、auth headers validation_failureschema / 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
}
字段命名规范 领域 常用字段 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）配置示例及真实事故失败模式参考的完整规范，请参见核心标准中的 日志文件轮转策略 。
检查清单
必要字段
安全性
轮转
配置检测
检测顺序
检查现有的日志库配置
检查 CONTRIBUTING.md 中的日志指南
若未找到，默认使用结构化 JSON 日志
首次设置
建议："此项目尚未配置日志标准。是否要设置结构化日志？"
建议在 CONTRIBUTING.md 中记录：
## 日志标准
### 日志级别
- DEBUG: 仅开发环境，详细诊断信息
- INFO: 正常操作（启动、用户操作、任务）
- WARN: 意外但可恢复的情况
- ERROR: 需要调查的失败
### 必要字段
所有日志必须包含：timestamp, level, message, service, request_id
### 敏感数据
绝不记录：密码、令牌、信用卡、身份证号码
下一步引导
日志标准已掌握。建议下一步 / 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 初始发布
授权 