Java 结构化日志规范（RFC-34）

技能文档

---
name: majiayu000-structured-logs-rfc-34
title: Java 结构化日志规范（RFC-34）
category: 开发工具
description: 为 Java 服务落地 RFC-34 结构化日志标准，覆盖 JSON 日志格式、结构化参数、必填字段与 Logback JSON 输出配置。当用户在 Java 服务中实现或排查日志、把非结构化日志改造为结构化日志、配置 Logback JSON 输出、审查日志规范时触发。触发词：结构化日志、JSON 日志、Logback 配置、日志规范、日志审查。
---

# Java 结构化日志规范（RFC-34）

面向 Java 服务（Spring Boot + Logback）的 RFC-34 结构化日志标准：统一 JSON 输出、必填字段与结构化参数写法，让日志可直接被采集、检索与聚合。

## 何时使用

- 在新 Java 服务中实现日志
- 把非结构化日志改造为结构化格式
- 审查现有日志实践
- 配置 Logback 输出 JSON
- 为日志补充业务上下文字段

## 技能工作流

### 步骤1：引入依赖

```groovy
implementation 'org.springframework.boot:spring-boot-starter-logging'
implementation 'net.logstash.logback:logstash-logback-encoder:${latest_version}'
```

### 步骤2：配置 Logback JSON 输出

在 `logback-spring.xml` 中使用 `LogstashEncoder`，让所有日志以 JSON 落盘（完整配置示例见 [references/logging-standards.md](references/logging-standards.md)）：

```xml
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
  <encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
</appender>
```

### 步骤3：使用结构化参数写日志

```java
import static net.logstash.logback.argument.StructuredArguments.kv;

log.info("Transaction processed",
         kv("transaction_id", txn.getId()),
         kv("user_id", user.getId()));
```

这会产出带独立 `transaction_id`、`user_id` 字段的 JSON，而不是把值拼进消息文本。

### 步骤4：校验必填字段

所有日志必须包含下表字段，缺项时先补齐 Logback 配置（`dd.*` 字段通常通过 MDC 或 encoder 的 `fieldNames`/`customFields` 注入）：

| 字段 | 说明 |
|-------|-------------|
| `@timestamp` | 日志时间戳 |
| `message` | 日志消息文本 |
| `logger` | Logger 名称 |
| `thread_name` | 线程名 |
| `level` | 日志级别（INFO、WARN、ERROR 等） |
| `dd.service` | 服务名 |
| `dd.env` | 环境 |
| `dd.version` | 服务版本 |

### 步骤5：审查与改造存量日志

按「最佳实践」逐条检查：业务标识是否独立成字段、消息是否清晰、级别是否一致、上下文是否自足、对象是否被 `toString()` 拼进消息。发现反模式按参考文档中的改法重构。

## 最佳实践

- 业务标识（各类 ID）作为独立字段添加，不要嵌进消息文本
- 日志消息文本保持清晰简洁
- 一致地使用合适的日志级别
- 包含足够上下文，无需额外查询即可理解事件
- 字段名使用 snake_case
- 包含对象时正确结构化，而不是调用 `toString()`

### 示例

```java
// ✅ 正确 - 结构化字段
log.info("Order created", kv("order_id", orderId), kv("user_id", userId), kv("amount", amount));

// ❌ 错误 - 拼进消息
log.info("Order {} created for user {} with amount {}", orderId, userId, amount);
```

## 参考文档

| 文档 | 说明 |
|-----------|-------------|
| [references/logging-standards.md](references/logging-standards.md) | RFC-34 完整实施指南（配置、MDC 上下文、异常与反模式） |

使用说明

# Java 结构化日志规范（RFC-34）

为 Java（Spring Boot + Logback）服务落地 RFC-34 结构化日志标准：统一 JSON 输出、必填字段与结构化参数写法，让日志可直接被采集、检索与聚合。

## 使用

```text
帮我把这个服务的日志改造成 JSON 结构化输出
```

```text
审查一下这段代码里的日志写法是否符合规范
```

## 工作原理

SKILL.md 给出五步工作流：引入 logstash-logback-encoder 依赖 → 配置 LogbackEncoder 输出 JSON 并注入 `dd.*` 部署元字段 → 用 `kv()/v()` 结构化参数写业务字段 → 校验八项必填字段 → 按最佳实践与反模式清单审查存量日志。完整配置、MDC 上下文与异常日志规范见 `references/logging-standards.md`。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。