---
title: "Trace ID 和 Span ID 的区别，用真实的 traceparent 请求头解读"
description: "Trace ID 在请求经过的每个服务中标识同 1 个请求，值始终不变。Span ID 标识 1 个步骤，所以每个服务都会生成新的 Span ID。"
canonical: "https://logbrew.co/zh-Hans/guides/trace-id"
last_updated: "2026-11-21"
---

# Trace ID 和 Span ID 的区别，用真实的 traceparent 请求头解读

Trace ID 在请求经过的每个服务中标识同 1 个请求，值始终不变。Span ID 标识 1 个步骤，所以每个服务都会生成新的 Span ID。

2026年11月21日 用 Node.js 22.18.0、@logbrew/node 0.1.30、Python 3.13.9、FastAPI 0.165.0、uvicorn 0.54.0、logbrew-fastapi 0.1.14、curl 8.7.1和logbrew CLI 0.1.96 实测

作者 [Furkan Erday](https://github.com/furkanerday). Furkan Erday 是 LogBrew 的创始人，每天用 Claude Code 和 Codex 开发 LogBrew。

Canonical: https://logbrew.co/zh-Hans/guides/trace-id

## 每个 traceparent 请求头对链路产生了什么影响

| curl 发送的请求头 | 保留了 Trace ID | 2 条日志共用 1 个 Trace ID |
| --- | --- | --- |
| 有效，标志 `01` | 是 | 是 |
| 有效，标志 `00` | 是 | 是 |
| 大写的 Trace ID | 是，转为小写 | 是 |
| 全为 0 的 Trace ID | 新链路 | 是 |
| 版本 `ff` | 新链路 | 是 |
| 没有请求头 | 新链路 | 是 |

向一个调用 FastAPI 服务的 Node.js 服务发送 6 个请求，使用 @logbrew/node 0.1.30 和 logbrew-fastapi 0.1.14。

## 解读 traceparent 请求头

### 按连字符拆分请求头

`traceparent` 包含 4 个小写十六进制字段，用 `-` 分隔，依次是版本、Trace ID、Parent ID 和链路标志。这是 curl 发给 `checkout` 服务的请求头。

输出

```text
checkout got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01
```

### 读取版本

W3C Trace Context 推荐标准中只有 `00` 这一个版本，`ff` 无效。我们发送 `ff` 时，2 个 SDK 都忽略了这个请求头，并开始了新链路。

### 读取 Trace ID

接下来的 32 个字符是 Trace ID `9095c7b7bf222836f82c2c415bc2bd65`，即 16 字节的十六进制。它标识整个请求，每个服务都原样传递它。全为 0 的 Trace ID 无效。

### 读取 Parent ID

接下来的 16 个字符是 Parent ID `fe8e70882fecdf07`，即 8 字节的十六进制。它是调用方 Span 的 Span ID，所以每一跳都会变。全为 0 的 Parent ID 无效。

### 读取链路标志

最后 2 个字符是标志，只有第 0 位有含义。`01` 表示调用方可能记录了链路，`00` 表示没有记录。即使是 `00`，2 个 SDK 仍然发送了 Span，LogBrew 也显示了这条链路。

## 把链路从 Node.js 传到 Python

### 安装 2 个 SDK

`checkout` 服务运行在 Node.js 上，使用 `@logbrew/node`。它调用 `payments`，一个使用 `logbrew-fastapi` 的 FastAPI 应用。两边都使用你的 LogBrew 项目的服务端密钥。

```bash
npm install @logbrew/sdk @logbrew/node
python3 -m pip install logbrew-sdk logbrew-fastapi
```

### 包装 Node.js 服务器和它发出的调用

`withLogBrewHttpHandler()` 从每个请求读取 `traceparent` 并开始一个 Span。`fetchWithLogBrewSpan()` 为这次调用开始一个子 Span，并用这个 Span 的 ID 写入新的 `traceparent`。包装器从 `LOGBREW_SERVER_API_KEY` 读取密钥。

```bash
import { createServer } from "node:http";
import { fetchWithLogBrewSpan, withLogBrewHttpHandler } from "@logbrew/node";

const server = createServer(withLogBrewHttpHandler(async (req, res, logbrew) => {
  logbrew.client.log(`evt_checkout_${Date.now()}`, new Date().toISOString(), {
    message: "checkout started for order 1042",
    level: "info",
    logger: "checkout"
  });
  const reply = await fetchWithLogBrewSpan("http://127.0.0.1:28702/payments/1042", {
    method: "POST"
  }, {
    client: logbrew.client,
    trace: logbrew.trace,
    routeTemplate: "/payments/:orderId"
  });
  res.writeHead(reply.status, { "content-type": "application/json" });
  res.end(await reply.text());
}));

server.listen(28701, "127.0.0.1");
```

### 给 FastAPI 应用接入 LogBrew

`init_logbrew()` 从每个请求读取 `traceparent` 并开始一个子 Span。`logbrew.logging_handler` 把请求的 Trace ID 和 Span ID 加到每条日志记录上。

```bash
import logging
import os

from fastapi import FastAPI
from logbrew_fastapi import init_logbrew

app = FastAPI()
logbrew = init_logbrew(
    app, api_key=os.environ["LOGBREW_SERVER_API_KEY"], service_name="payments"
)
logger = logging.getLogger("payments")
logger.setLevel(logging.INFO)
logger.addHandler(logbrew.logging_handler)


@app.post("/payments/{order_id}")
def authorize(order_id: str):
    logger.warning("card declined for order %s", order_id)
    return {"orderId": order_id, "status": "declined"}
```

## 找到一行日志所属的链路

### 发送 1 个经过 2 个服务的请求

curl 发送了 `traceparent`，`checkout` 前面的浏览器或网关也会这样做。没有这个请求头时，`checkout` 会开始新链路。

```bash
curl -X POST http://127.0.0.1:28701/checkout \
  -H 'traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01'
```

输出

```text
{"orderId":"1042","status":"declined"}
```

### 比较每一跳的请求头

我们在每个服务中打印了请求头。`checkout` 保留了 Trace ID，并把它的调用 Span 的 ID `1a95bcb4e3fcb3ce` 填入 Parent ID。`payments` 读取这个请求头，并在其下开始了 Span `bc7e3f490d4a4d00`。

输出

```text
checkout got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01
checkout sent traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01
payments got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01
```

### 找到链路的全部日志

从任意一行日志复制 Trace ID，传给 `--trace`。CLI 返回了每个服务的日志。在控制台中，把 Trace ID 粘贴到日志页面的搜索框。

```bash
logbrew read logs --project "<project_id>" --trace 9095c7b7bf222836f82c2c415bc2bd65
```

输出

```text
Logs (2)
- warning card declined for order 1042 service=payments trace=9095c7b7bf222836f82c2c415bc2bd65 [unversioned / production]
- info checkout started for order 1042 service=checkout trace=9095c7b7bf222836f82c2c415bc2bd65 [unversioned / production]
```

### 打开链路

这条链路有 3 个 Span，2 个来自 `checkout`，1 个来自 `payments`。在控制台中，把 Trace ID 粘贴到探索页面的搜索框，然后打开链路。

```bash
logbrew read trace 9095c7b7bf222836f82c2c415bc2bd65 --project "<project_id>"
```

输出

```text
Trace 9095c7b7bf222836f82c2c415bc2bd65 spans=3 [unversioned / production]
- POST /payments/{order_id}
- POST /payments/:orderId
- POST /checkout
```

## 我们测试时看到的结果

我们在 Node.js 22.18 上用 @logbrew/node 0.1.30 运行 `checkout`，在 Python 3.13.9 上用 FastAPI 0.165.0、uvicorn 0.54.0 和 logbrew-fastapi 0.1.14 运行 `payments`。两者都发送到本地 LogBrew 服务器。curl 向 `checkout` 发送了 6 个请求，5 个各带一个不同的 `traceparent`，1 个不带。

每个请求中，2 个服务的日志都共用 1 个 Trace ID。请求头有效时，它就是 curl 发送的 Trace ID。请求头无效或缺失时，`checkout` 开始新链路并继续传递。

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| `checkout` 请求 | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| `checkout` 调用 `payments` | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| `payments` 请求 | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

- `checkout`
  - `level`: `info`
  - 消息: `checkout started for order 1042`
  - `trace_id`: `9095c7b7bf222836f82c2c415bc2bd65`
  - `span_id`: `5569d78d6d163d95`
- `payments`
  - `level`: `warning`
  - 消息: `card declined for order 1042`
  - `trace_id`: `9095c7b7bf222836f82c2c415bc2bd65`
  - `span_id`: `bc7e3f490d4a4d00`

## Trace ID 和 Span ID 的区别

Trace ID 是 16 字节，写成 32 个十六进制字符。Span ID 是 8 字节，写成 16 个字符。OpenTelemetry 链路 API 规范规定，只有至少 1 个字节不为 0 的 ID 才有效，并且两者都用小写十六进制书写。

在 OpenTelemetry 中，Span 上下文包含 Trace ID、Span ID、链路标志和链路状态。`traceparent` 携带前 3 项。`tracestate` 请求头携带链路状态，它是最多 32 个厂商条目的列表。LogBrew 的 2 个 SDK 都不写 `tracestate`。

|  | Trace ID | Span ID |
| --- | --- | --- |
| 十六进制字符数 | `32` | `16` |
| 每一跳都相同 | 是 | 否 |
| 全为 0 时有效 | 否 | 否 |

## 请求头有误时

推荐标准只允许小写十六进制，并禁止版本 `ff` 和全为 0 的 ID。收到这种请求头的服务必须忽略它并开始新链路。对于 `ff`，以及全为 0 的 Trace ID 或 Parent ID，2 个 SDK 都这样处理了。

2 个 SDK 都接受了大写的 Trace ID，并以小写形式传递。请发送小写，因为严格的服务会改为开始新链路。

没有请求头时，`checkout` 开始了一条标志为 `01` 的链路，`payments` 开始了一条标志为 `00` 的链路。LogBrew 保留了这 2 条链路。

| 保留了 Trace ID | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| 大写的 Trace ID | 是 | 是 |
| 版本 `ff` | 否 | 否 |
| 全为 0 的 Trace ID | 否 | 否 |
| 全为 0 的 Parent ID | 否 | 否 |

## 常见问题

### Trace ID 是什么？

Trace ID 是一个 16 字节的 ID，写成 32 个小写十六进制字符。它在请求经过的每个服务中标识同 1 个请求。每个服务都通过 `traceparent` 请求头传递它。

### Trace ID 和 Span ID 有什么区别？

在 1 个请求经过的每个服务中，Trace ID 都相同。Span ID 标识 1 个服务中的 1 个步骤。我们的请求有 1 个 Trace ID 和 3 个 Span ID。

### traceparent 请求头是什么？

`traceparent` 是 W3C Trace Context 推荐标准定义的 HTTP 请求头。它包含版本、Trace ID、调用方的 Span ID 和链路标志，例如 `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`。

### traceparent 末尾的 01 是什么意思？

`01` 设置了 sampled 标志，表示调用方可能记录了链路。`00` 表示没有记录。LogBrew 的 2 个 SDK 对两种值都照常传递，LogBrew 也保留了链路。

### 如何找到 Trace ID 相同的全部日志？

运行 `logbrew read logs --project "<project_id>" --trace <trace_id>`，或在 LogBrew 控制台的日志页面搜索框中粘贴 Trace ID。SDK 在请求期间写入的每条日志都带有该请求的 Trace ID。

### traceparent 请求头区分大小写吗？

区分。推荐标准只允许小写十六进制。LogBrew 的 2 个 SDK 都接受了大写的 Trace ID 并转为小写，但严格的服务会忽略这个请求头。

## 1 次搜索找到链路的全部日志

LogBrew 的 Node.js 和 FastAPI SDK 会读取并发送 `traceparent`，每条日志都保留所属请求的 Trace ID。免费额度充足，无需绑卡。

[免费开始](https://logbrew.co/zh-Hans)

## 参考来源

- [W3C Recommendation, Trace Context, 3.2 Traceparent Header](https://www.w3.org/TR/trace-context/#traceparent-header)
- [W3C Recommendation, Trace Context, 4.3 A traceparent is received](https://www.w3.org/TR/trace-context/#a-traceparent-is-received)
- [@logbrew/node on npm](https://www.npmjs.com/package/@logbrew/node)
- [LogBrewCo/sdk, logbrew-fastapi README](https://github.com/LogBrewCo/sdk/blob/main/python/logbrew_fastapi/README.md)

## 更多智能体、Python、Node.js 与 React 指南

- [在 Claude Code 和 Codex 中添加 MCP 服务器](https://logbrew.co/zh-Hans/guides/mcp-server-claude-code-codex)
- [在 Claude Code 和 Codex 中使用 AGENTS.md](https://logbrew.co/zh-Hans/guides/agents-md)
- [解决 Claude overloaded 529 错误和 rate limit 429 错误](https://logbrew.co/zh-Hans/guides/claude-overloaded-rate-limit-error)
- [配置 Python 日志用对日志级别并捕获异常和回溯](https://logbrew.co/zh-Hans/guides/python-logging)
- [结构化日志用能按字段搜索的日志格式和日志级别](https://logbrew.co/zh-Hans/guides/structured-logging)
- [用 Pino 或 Winston 配置 Node.js 日志一个错误都不丢](https://logbrew.co/zh-Hans/guides/node-logging)
- [配置 Django 日志保留每个 500 错误的回溯信息](https://logbrew.co/zh-Hans/guides/django-logging)
- [配置 FastAPI 日志处理错误不丢失回溯](https://logbrew.co/zh-Hans/guides/fastapi-logging)
- [给 React 加上错误边界并记录它漏掉的错误](https://logbrew.co/zh-Hans/guides/react-error-boundary)
- [错误、日志、链路、指标和版本指南](https://logbrew.co/zh-Hans/guides)
