Skip to content
Skills Library
Programming · Building & coding

logging

/logging

实现结构化日志,包含适当的日志级别与敏感数据处理。 Use when: 加入日志、调试、建立可观测性。 Not for: 指标、追踪与告警设计——请用 /observability;错误码分类体系——请用 /error-code-guide。 Keywords: logging, log level, structured logging, observability, 日志, 结构化日志, 日志级别, 敏感数据.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

  1. 目的
  2. 快速参考
  3. 强制事件
  4. 结构化日志
  5. 详细指南
  6. 敏感数据处理
  7. 错误日志
  8. 日志格式
  9. 性能考量
  10. 日志文件轮转
Original SKILL.md headings · 333 lines, 930 words
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

RepositoryScoreLicence
This page · AsiaOstrich/universal-dev-standards95MIT
gtlpanda/PandaStack100MIT
kettleofketchup/DraftForge100GPL-3.0
dxos/dxos100Apache-2.0
EpicenterHQ/epicenter100MIT
florianbuetow/claude-code100MIT
anmolnagpal/devops-skills100MIT
arbazkhan971/godmode100MIT
codewithmukesh/dotnet-claude-kit100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.