logging
/logging
实现结构化日志,包含适当的日志级别与敏感数据处理。 Use when: 加入日志、调试、建立可观测性。 Not for: 指标、追踪与告警设计——请用 /observability;错误码分类体系——请用 /error-code-guide。 Keywords: logging, log level, structured logging, observability, 日志, 结构化日志, 日志级别, 敏感数据.
- Author
- AsiaOstrich ↗
- Repository
- universal-dev-standards ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
实现结构化日志,包含适当的日志级别与敏感数据处理。 Use when: 加入日志、调试、建立可观测性。 Not for: 指标、追踪与告警设计——请用 /observability;错误码分类体系——请用 /error-code-guide。 Keywords: logging, log level, structured logging, observability, 日志, 结构化日志, 日志级别, 敏感数据.
Original author description
实现结构化日志,包含适当的日志级别与敏感数据处理。 Use when: 加入日志、调试、建立可观测性。 Not for: 指标、追踪与告警设计——请用 /observability;错误码分类体系——请用 /error-code-guide。 Keywords: logging, log level, structured logging, observability, 日志, 结构化日志, 日志级别, 敏感数据.
How it works
- 目的
- 快速参考
- 强制事件
- 结构化日志
- 详细指南
- 敏感数据处理
- 错误日志
- 日志格式
- 性能考量
- 日志文件轮转
SKILL.md preview
---
name: logging
description: |
实现结构化日志,包含适当的日志级别与敏感数据处理。
Use when: 加入日志、调试、建立可观测性。
Not for: 指标、追踪与告警设计——请用 /observability;错误码分类体系——请用 /error-code-guide。
Keywords: logging, log level, structured logging, observability, 日志, 结构化日志, 日志级别, 敏感数据.
source: ../../../../skills/logging-guide/SKILL.md
source_version: 1.4.0
translation_version: 1.5.0
last_synced: 2026-08-17
source_hash: ca969fdf7847
status: current
---
# 日志指南
> **语言**: [English](../../../../skills/logging-guide/SKILL.md) | 简体中文
**版本**: 1.4.0
**最后更新**: 2026-06-19
**适用范围**: Claude Code Skills
---
> **核心标准**: 本技能实现 [日志标准](../../../../core/logging-standards.md)。如需面向任何 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](../../core/logging-standards.md#强制事件mandatory-events) 的 **强制事件** 章节。
## 结构化日志
### 必要字段
```json
{
"timestamp": "2025-01-15T10:30:00.123Z",
"level": "INFO",
"message": "用户登录成功",
"service": "auth-service",
"environment": "production"
}
```
### 推荐字段
```json
{
"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 |
## 详细指南
完整标准请参考:
- [日志标准](../../../../core/logging-standards.md)
### AI 优化格式(节省 Token)
AI 助手可使用 YAML 格式文件以减少 Token 使用量:
- 基础标准:`ai/standards/logging.ai.yaml`
## 敏感数据处理
### 绝不记录
- 密码或密钥
- API 密钥或令牌
- 信用卡号码
- 身份证号码
- 完整的认证令牌
### 脱敏处理
```javascript
// 不好
logger.info('登录尝试', { password: userPassword });
// 好
logger.info('登录尝试', { password: '***已脱敏***' });
// 好 - 部分脱敏
logger.info('卡片处理', { last_four: '4242' });
```
### PII 处理
- 尽可能记录用户 ID 而非电子邮件
- 对敏感查询使用哈希标识符
- 配置数据保留策略
## 错误日志
### 必要字段
```json
{
"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)
- 输入参数(已脱敏)
- 重试次数(如适用)
```javascript
logger.error('处理订单失败', {
error_type: err.name,
error_message: err.message,
order_id: orderId,
user_id: userId,
retry_count: 2,
stack: err.stack
});
```
## 日志格式
### JSON 格式(生产环境)
```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)配置示例及真实事故失败模式参考的完整规范,请参见核心标准中的 [日志文件轮转策略](../../core/logging-standards.md#日志文件轮转策略)。
## 检查清单
### 必要字段
- [ ] 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` 中记录:
```markdown
## 日志标准
### 日志级别
- DEBUG: 仅开发环境,详细诊断信息
- INFO: 正常操作(启动、用户操作、任务)
- WARN: 意外但可恢复的情况
- ERROR: 需要调查的失败
### 必要字段
所有日志必须包含:timestamp, level, message, service, request_id
### 敏感数据
绝不记录:密码、令牌、信用卡、身份证号码
```
---
## 下一步引导
`/logging` 完成后,AI 助手应建议:
> **日志标准已掌握。建议下一步 / Logging standards understood. Suggested next steps:**
> - 根据日志指南在代码中实现结构化日志 ⭐ **推荐** — 立即将日志标准应用到项目
> - 执行 `/errors` 设计错误码以配合日志系统 — 让错误追踪更高效
> - 执行 `/sdd` 将可观测性需求纳入规格 — 确保日志需求在规格中有定义
---
## 相关标准
- [日志标准](../../../../core/logging-standards.md)
- [错误码标准](../../../../core/error-code-standards.md)
---
## 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| 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](https://creativecommons.org/licenses/by/4.0/) 发布。
**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · AsiaOstrich/universal-dev-standards | 95 | MIT |
| gtlpanda/PandaStack | 100 | MIT |
| kettleofketchup/DraftForge | 100 | GPL-3.0 |
| dxos/dxos | 100 | Apache-2.0 |
| EpicenterHQ/epicenter | 100 | MIT |
| florianbuetow/claude-code | 100 | MIT |
| anmolnagpal/devops-skills | 100 | MIT |
| arbazkhan971/godmode | 100 | MIT |
| codewithmukesh/dotnet-claude-kit | 100 | MIT |
Database snapshot: 13.11.2026 · package version 8fa85ca45020 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100logging-guide
Implement structured logging with proper log levels and sensitive data handling. Use when: adding logging, debugging, setting up observability. Not for: metrics, traces, and alerting design — use /observability; error code taxonomy — use /error-code-guide. Keywords: logging, log… - 100logging-guide
實作結構化日誌,包含適當的日誌層級與敏感資料處理。 Use when: 加入日誌、除錯、建立可觀測性。 Not for: 指標、追蹤與告警設計——請用 /observability;錯誤碼分類體系——請用 /error-code-guide。 Keywords: logging, log level, structured logging, observability, 日誌, 結構化日誌, 日誌層級, 敏感資料. - 100eng-logging
Use when implementing logging in application code. Covers log level selection, structured logging, error tracking integration, and avoiding noise. - 100181-java-observability-logging
Use when you need to implement or improve Java logging and observability — including selecting SLF4J with Logback/Log4j2, applying proper log levels (ERROR, WARN, INFO, DEBUG, TRACE), parameterized logging, correlation context, secure logging without sensitive data exposure,… - 96observability
可观测性专家助手。当用户需要设计可观测性体系、规划指标监控、结构化日志、分布式链路追踪、告警策略或使用 OpenTelemetry 统一采集时调用。 - 100obsidian-observability
Implement structured logging, metrics, error tracking, and a debug panel for Obsidian plugins. Use when adding debug logging, tracking plugin performance, building a diagnostics view, or setting up error reporting. Trigger with phrases like "obsidian logging", "obsidian…