---
title: "Trace ID và span ID, giải mã từ một header traceparent thật"
description: "Trace ID đặt tên cho 1 request ở mọi dịch vụ mà request đi qua và không đổi. Span ID đặt tên cho 1 bước, nên mỗi dịch vụ tạo một span ID mới."
canonical: "https://logbrew.co/vi/guides/trace-id"
last_updated: "2026-11-21"
---

# Trace ID và span ID, giải mã từ một header traceparent thật

Trace ID đặt tên cho 1 request ở mọi dịch vụ mà request đi qua và không đổi. Span ID đặt tên cho 1 bước, nên mỗi dịch vụ tạo một span ID mới.

Đã thử nghiệm ngày 21 tháng 11, 2026 với 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 và logbrew CLI 0.1.96

Tác giả [Furkan Erday](https://github.com/furkanerday). Furkan Erday là nhà sáng lập LogBrew. Anh xây dựng LogBrew bằng Claude Code và Codex mỗi ngày.

Canonical: https://logbrew.co/vi/guides/trace-id

## Mỗi header traceparent đã làm gì với trace

| Header curl đã gửi | Giữ nguyên trace ID | 2 log có cùng 1 trace ID |
| --- | --- | --- |
| Hợp lệ, cờ `01` | Có | Có |
| Hợp lệ, cờ `00` | Có | Có |
| Trace ID viết hoa | Có, chuyển thành chữ thường | Có |
| Trace ID toàn số 0 | Trace mới | Có |
| Phiên bản `ff` | Trace mới | Có |
| Không có header | Trace mới | Có |

6 request vào một dịch vụ Node.js gọi một dịch vụ FastAPI, dùng @logbrew/node 0.1.30 và logbrew-fastapi 0.1.14.

## Giải mã header traceparent

### Tách header tại các dấu gạch ngang

`traceparent` có 4 trường hex chữ thường, cách nhau bằng `-`. Đó là phiên bản, trace ID, parent ID và cờ trace. Đây là header curl đã gửi tới dịch vụ `checkout` của chúng tôi.

Kết quả

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

### Đọc phiên bản

`00` là phiên bản duy nhất trong Khuyến nghị W3C Trace Context, còn `ff` không hợp lệ. Khi chúng tôi gửi `ff`, cả 2 SDK đều bỏ qua header và bắt đầu một trace mới.

### Đọc trace ID

32 ký tự tiếp theo là trace ID `9095c7b7bf222836f82c2c415bc2bd65`, 16 byte dạng hex. Nó đặt tên cho cả request, và mọi dịch vụ chuyển tiếp nó mà không đổi. Trace ID toàn số 0 là không hợp lệ.

### Đọc parent ID

16 ký tự tiếp theo là parent ID `fe8e70882fecdf07`, 8 byte dạng hex. Đây là span ID của span bên gọi, nên nó đổi ở mỗi chặng. Parent ID toàn số 0 là không hợp lệ.

### Đọc cờ trace

2 ký tự cuối là cờ, và chỉ bit 0 có ý nghĩa. `01` cho biết bên gọi có thể đã ghi lại trace, còn `00` cho biết là không. Với `00`, cả 2 SDK vẫn gửi span, và LogBrew vẫn hiển thị trace.

## Chuyển trace từ Node.js sang Python

### Cài 2 SDK

Dịch vụ `checkout` chạy trên Node.js với `@logbrew/node`. Nó gọi `payments`, một ứng dụng FastAPI dùng `logbrew-fastapi`. Dùng một khóa máy chủ của dự án LogBrew cho mỗi dịch vụ.

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

### Bọc máy chủ Node.js và lời gọi của nó

`withLogBrewHttpHandler()` đọc `traceparent` từ mỗi request và bắt đầu một span. `fetchWithLogBrewSpan()` bắt đầu một span con cho lời gọi và ghi một `traceparent` mới với ID của span đó. Wrapper đọc khóa từ `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");
```

### Thêm LogBrew vào ứng dụng FastAPI

`init_logbrew()` đọc `traceparent` từ mỗi request và bắt đầu một span con. `logbrew.logging_handler` thêm trace ID và span ID của request vào mỗi bản ghi log.

```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"}
```

## Tìm trace của một dòng log

### Gửi 1 request qua cả 2 dịch vụ

curl đã gửi một `traceparent`, giống như trình duyệt hoặc gateway đứng trước `checkout` có thể làm. Không có header, `checkout` bắt đầu một trace mới.

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

Kết quả

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

### So sánh header ở mỗi chặng

Chúng tôi in header ở mỗi dịch vụ. `checkout` giữ trace ID và đặt ID của span gọi đi, `1a95bcb4e3fcb3ce`, vào parent ID. `payments` đọc header đó và bắt đầu span `bc7e3f490d4a4d00` bên dưới.

Kết quả

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

### Tìm mọi log của trace

Sao chép trace ID từ một dòng log bất kỳ và truyền vào `--trace`. CLI trả về log của từng dịch vụ. Trong dashboard, dán trace ID vào ô tìm kiếm của Log.

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

Kết quả

```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]
```

### Mở trace

Trace có 3 span, 2 từ `checkout` và 1 từ `payments`. Trong dashboard, dán trace ID vào ô tìm kiếm của Khám phá, rồi mở trace.

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

Kết quả

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

## Những gì chúng tôi thấy khi thử nghiệm

Chúng tôi chạy `checkout` trên Node.js 22.18 với @logbrew/node 0.1.30, và `payments` trên Python 3.13.9 với FastAPI 0.165.0, uvicorn 0.54.0 và logbrew-fastapi 0.1.14. Cả 2 gửi tới một máy chủ LogBrew cục bộ. curl gửi 6 request vào `checkout`, 5 request với `traceparent` khác nhau và 1 request không có header.

Trong mỗi request, log của cả 2 dịch vụ có cùng 1 trace ID. Khi header hợp lệ, đó là trace ID mà curl đã gửi. Khi header không hợp lệ hoặc không có, `checkout` bắt đầu một trace mới và chuyển tiếp nó.

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| Request vào `checkout` | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| Lời gọi từ `checkout` tới `payments` | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| Request vào `payments` | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

- `checkout`
  - `level`: `info`
  - Thông điệp: `checkout started for order 1042`
  - `trace_id`: `9095c7b7bf222836f82c2c415bc2bd65`
  - `span_id`: `5569d78d6d163d95`
- `payments`
  - `level`: `warning`
  - Thông điệp: `card declined for order 1042`
  - `trace_id`: `9095c7b7bf222836f82c2c415bc2bd65`
  - `span_id`: `bc7e3f490d4a4d00`

## Trace ID và span ID

Trace ID dài 16 byte, viết thành 32 ký tự hex. Span ID dài 8 byte, viết thành 16 ký tự. Đặc tả trace API của OpenTelemetry chỉ coi một ID là hợp lệ khi có ít nhất 1 byte khác 0, và viết cả 2 bằng hex chữ thường.

Trong OpenTelemetry, một span context chứa trace ID, span ID, cờ trace và trace state. `traceparent` mang 3 thứ đầu. Header `tracestate` mang trace state, một danh sách tối đa 32 mục của các nhà cung cấp. Cả 2 SDK của LogBrew đều không ghi `tracestate`.

|  | Trace ID | Span ID |
| --- | --- | --- |
| Số ký tự hex | `32` | `16` |
| Giống nhau ở mọi chặng | Có | Không |
| Hợp lệ khi toàn số 0 | Không | Không |

## Khi header bị sai

Khuyến nghị chỉ cho phép hex chữ thường, và cấm phiên bản `ff` cùng các ID toàn số 0. Dịch vụ nhận header như vậy phải bỏ qua nó và bắt đầu một trace mới. Cả 2 SDK đều làm vậy với `ff` và với trace ID hoặc parent ID toàn số 0.

Cả 2 SDK đều chấp nhận trace ID viết hoa và chuyển tiếp nó ở dạng chữ thường. Hãy gửi chữ thường, vì một dịch vụ chặt chẽ sẽ bắt đầu trace mới thay vào đó.

Khi không có header, `checkout` bắt đầu một trace với cờ `01`, còn `payments` bắt đầu một trace với `00`. LogBrew giữ cả 2 trace.

| Giữ nguyên trace ID | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| Trace ID viết hoa | Có | Có |
| Phiên bản `ff` | Không | Không |
| Trace ID toàn số 0 | Không | Không |
| Parent ID toàn số 0 | Không | Không |

## Câu hỏi thường gặp

### Trace ID là gì?

Trace ID là một ID 16 byte, viết thành 32 ký tự hex chữ thường. Nó đặt tên cho 1 request ở mọi dịch vụ mà request đi qua. Mỗi dịch vụ chuyển tiếp nó trong header `traceparent`.

### Trace ID và span ID khác nhau thế nào?

Trace ID giống nhau ở mọi dịch vụ của 1 request. Span ID đặt tên cho 1 bước trong 1 dịch vụ. Request của chúng tôi có 1 trace ID và 3 span ID.

### Header traceparent là gì?

`traceparent` là header HTTP của Khuyến nghị W3C Trace Context. Nó chứa phiên bản, trace ID, span ID của bên gọi và cờ trace, ví dụ `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`.

### Số 01 ở cuối traceparent nghĩa là gì?

`01` bật cờ sampled, tức là bên gọi có thể đã ghi lại trace. `00` cho biết là không. Cả 2 SDK của LogBrew đều chuyển tiếp cả 2 giá trị, và LogBrew giữ trace.

### Làm sao tìm mọi log có cùng trace ID?

Chạy `logbrew read logs --project "<project_id>" --trace <trace_id>`, hoặc dán trace ID vào ô tìm kiếm của Log trong dashboard LogBrew. Mỗi log mà SDK ghi trong một request đều mang trace ID của request đó.

### Header traceparent có phân biệt chữ hoa chữ thường không?

Có. Khuyến nghị chỉ cho phép hex chữ thường. Cả 2 SDK của LogBrew đều chấp nhận trace ID viết hoa và chuyển nó thành chữ thường, nhưng một dịch vụ chặt chẽ sẽ bỏ qua header.

## Tìm mọi log của một trace với 1 lần tìm kiếm

SDK LogBrew cho Node.js và FastAPI đọc và gửi `traceparent`, và mỗi log giữ trace ID của request của nó. Bắt đầu với gói miễn phí rộng rãi, không cần thẻ.

[Bắt đầu miễn phí](https://logbrew.co/vi)

## Nguồn

- [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)

## Thêm hướng dẫn cho agent, Python, Node.js và React

- [Thêm máy chủ MCP vào Claude Code và Codex](https://logbrew.co/vi/guides/mcp-server-claude-code-codex)
- [Dùng AGENTS.md trong Claude Code và Codex](https://logbrew.co/vi/guides/agents-md)
- [Khắc phục lỗi Claude overloaded 529 và lỗi rate limit 429](https://logbrew.co/vi/guides/claude-overloaded-rate-limit-error)
- [Thiết lập Python logging với đúng mức log và bắt ngoại lệ kèm traceback](https://logbrew.co/vi/guides/python-logging)
- [Structured logging với định dạng log và mức log bạn tìm được theo trường](https://logbrew.co/vi/guides/structured-logging)
- [Thiết lập log cho Node.js với Pino hoặc Winston mà không mất lỗi nào](https://logbrew.co/vi/guides/node-logging)
- [Thiết lập logging Django và giữ traceback của mọi lỗi 500](https://logbrew.co/vi/guides/django-logging)
- [Thiết lập logging FastAPI và xử lý lỗi mà không mất traceback](https://logbrew.co/vi/guides/fastapi-logging)
- [Thêm error boundary cho React và ghi log những lỗi mà nó bỏ lọt](https://logbrew.co/vi/guides/react-error-boundary)
- [Hướng dẫn về lỗi, log, trace, chỉ số và bản phát hành](https://logbrew.co/vi/guides)
