Menu
实现结构化日志，包含正确的日志级别和敏感数据处理。 使用时机：新增日志、调试、设置可观测性。 关键字：logging, log level, structured logging, observability, 日志, 记录, 结构化日志。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
[UDS] 引導 CI/CD 管線設計、配置和優化
Guide CI/CD pipeline design, configuration, and optimization. Use when: setting up pipelines, optimizing build times, configuring deployment stages. Keywords: CI/CD, pipeline, GitHub Actions, deployment, build.
在编写规格前进行结构化 AI 辅助头脑风暴。 使用时机：功能规划、创意发想、问题定义。 关键字：brainstorm, persona, multi-critic, HMW, SCAMPER, 头脑风暴, 发想。
[UDS] 在撰寫規格前進行結構化 AI 輔助腦力激盪
[UDS] Structured AI-assisted brainstorming before spec creation
[UDS] 从规格衍生 BDD 场景、TDD 骨架或 ATDD 表格
| name | logging |
| description | 实现结构化日志，包含正确的日志级别和敏感数据处理。 使用时机：新增日志、调试、设置可观测性。 关键字：logging, log level, structured logging, observability, 日志, 记录, 结构化日志。 |
| source | ../../../../skills/logging-guide/SKILL.md |
| source_version | 1.1.0 |
| translation_version | 1.1.0 |
| last_synced | "2026-06-10T00:00:00.000Z" |
| source_hash | 6b7244c91aa0 |
| status | current |
语言: English | 简体中文
版本: 1.1.0 最后更新: 2026-05-26 适用范围: 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 | 无法恢复的错误、启动失败、失去关键资源 |
{
"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 助手可使用 YAML 格式文件以减少 Token 使用量：
ai/standards/logging.ai.yaml// 不好
logger.info('登录尝试', { password: userPassword });
// 好
logger.info('登录尝试', { password: '***已脱敏***' });
// 好 - 部分脱敏
logger.info('卡片处理', { last_four: '4242' });
{
"level": "ERROR",
"message": "数据库连接失败",
"error_type": "ConnectionError",
"error_message": "连接被拒绝",
"error_code": "ECONNREFUSED",
"stack": "Error: Connection refused\n at connect (/app/db.js:45:11)..."
}
务必包含：
logger.error('处理订单失败', {
error_type: err.name,
error_message: err.message,
order_id: orderId,
user_id: userId,
retry_count: 2,
stack: err.stack
});
{"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 | 高流量端点采样 |
基于文件的日志接收器必须同时设置两个轮转触发器——基于时间和基于大小。常见库（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）配置示例及真实事故失败模式参考的完整规范，请参见核心标准中的 日志文件轮转策略。
rollingInterval: Day 或同等配置）fileSizeLimitBytes + rollOnFileSizeLimit: true）retainedFileCountLimit ≥ N×7（N = 每天最大轮转次数）本技能支持项目特定配置。
CONTRIBUTING.md 中的日志指南若未找到日志标准：
CONTRIBUTING.md 中记录：## 日志标准
### 日志级别
- DEBUG: 仅开发环境，详细诊断信息
- INFO: 正常操作（启动、用户操作、任务）
- WARN: 意外但可恢复的情况
- ERROR: 需要调查的失败
### 必要字段
所有日志必须包含：timestamp, level, message, service, request_id
### 敏感数据
绝不记录：密码、令牌、信用卡、身份证号码
/logging 完成后，AI 助手应建议：
日志标准已掌握。建议下一步 / Logging standards understood. Suggested next steps:
- 根据日志指南在代码中实现结构化日志 ⭐ 推荐 — 立即将日志标准应用到项目
- 执行
/errors设计错误码以配合日志系统 — 让错误追踪更高效- 执行
/sdd将可观测性需求纳入规格 — 确保日志需求在规格中有定义
| 版本 | 日期 | 变更 |
|---|---|---|
| 1.1.0 | 2026-05-26 | 新增：日志文件轮转章节及核心标准轮转策略交叉引用；轮转检查清单（XSPEC-232） |
| 1.0.0 | 2025-12-30 | 初始发布 |
本技能采用 CC BY 4.0 发布。