---
title: "トレース ID とスパン ID の違いを実際の traceparent ヘッダーで解読"
description: "トレース ID は 1 件のリクエストを、それが届くすべてのサービスで同じ値のまま示します。スパン ID は 1 つの処理を示すため、サービスごとに新しく作られます。"
canonical: "https://logbrew.co/ja/guides/trace-id"
last_updated: "2026-11-21"
---

# トレース ID とスパン ID の違いを実際の traceparent ヘッダーで解読

トレース ID は 1 件のリクエストを、それが届くすべてのサービスで同じ値のまま示します。スパン ID は 1 つの処理を示すため、サービスごとに新しく作られます。

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/ja/guides/trace-id

## 各 traceparent ヘッダーでトレースがどうなったか

| curl が送ったヘッダー | トレース ID を維持 | 2 つのログが同じトレース ID |
| --- | --- | --- |
| 有効、フラグ `01` | はい | はい |
| 有効、フラグ `00` | はい | はい |
| 大文字のトレース ID | はい、小文字に変換 | はい |
| すべて 0 のトレース ID | 新しいトレース | はい |
| バージョン `ff` | 新しいトレース | はい |
| ヘッダーなし | 新しいトレース | はい |

FastAPI サービスを呼び出す Node.js サービスへの 6 件のリクエスト。@logbrew/node 0.1.30 と logbrew-fastapi 0.1.14 を使用。

## traceparent ヘッダーを解読する

### ヘッダーをハイフンで区切る

`traceparent` は `-` で区切られた小文字の 16 進数のフィールドを 4 つ持ちます。バージョン、トレース ID、親 ID、トレースフラグです。これは curl が `checkout` サービスに送ったヘッダーです。

出力

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

### バージョンを読む

W3C Trace Context 勧告のバージョンは `00` だけで、`ff` は無効です。`ff` を送ると、両方の SDK がヘッダーを無視して新しいトレースを開始しました。

### トレース ID を読む

次の 32 文字がトレース ID で、16 バイトの 16 進数の `9095c7b7bf222836f82c2c415bc2bd65` です。リクエスト全体を示し、各サービスはこれを変えずに渡します。すべて 0 のトレース ID は無効です。

### 親 ID を読む

次の 16 文字が親 ID で、8 バイトの 16 進数の `fe8e70882fecdf07` です。呼び出し元のスパンのスパン ID なので、ホップごとに変わります。すべて 0 の親 ID は無効です。

### トレースフラグを読む

最後の 2 文字がフラグで、意味を持つのはビット 0 だけです。`01` は呼び出し元がトレースを記録した可能性を、`00` は記録しなかったことを示します。`00` でも両方の SDK はスパンを送り、LogBrew はトレースを表示しました。

## Node.js から Python にトレースを渡す

### 2 つの SDK をインストールする

`checkout` サービスは `@logbrew/node` を使い Node.js で動きます。呼び出す先の `payments` は `logbrew-fastapi` を使う FastAPI アプリです。どちらにも LogBrew プロジェクトのサーバーキーを使います。

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

### Node.js サーバーと呼び出しをラップする

`withLogBrewHttpHandler()` は各リクエストから `traceparent` を読み、スパンを開始します。`fetchWithLogBrewSpan()` は呼び出し用の子スパンを開始し、そのスパンの 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` を読み、子スパンを開始します。`logbrew.logging_handler` は各ログレコードにリクエストのトレース ID とスパン 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"}
```

## ログ行のトレースを見つける

### 2 つのサービスを通るリクエストを 1 件送る

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` はトレース ID を維持し、親 ID に自分の呼び出しスパンの ID `1a95bcb4e3fcb3ce` を入れました。`payments` はそのヘッダーを読み、その下にスパン `bc7e3f490d4a4d00` を開始しました。

出力

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

### トレースのログをすべて見つける

任意のログ行からトレース ID をコピーし、`--trace` に渡します。CLI は各サービスのログを返しました。ダッシュボードでは、ログの検索ボックスにトレース 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 つのスパンがあり、2 つが `checkout`、1 つが `payments` のものです。ダッシュボードでは、探索の検索ボックスにトレース 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
```

## テストで確認したこと

`checkout` は Node.js 22.18 と @logbrew/node 0.1.30 で、`payments` は Python 3.13.9、FastAPI 0.165.0、uvicorn 0.54.0、logbrew-fastapi 0.1.14 で動かしました。どちらもローカルの LogBrew サーバーに送信しました。curl は `checkout` に 6 件のリクエストを送りました。5 件はそれぞれ異なる `traceparent` 付き、1 件はヘッダーなしです。

どのリクエストでも、2 つのサービスのログは同じトレース ID を持ちました。ヘッダーが有効なときは curl が送ったトレース 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`

## トレース ID とスパン ID の違い

トレース ID は 16 バイトで、32 文字の 16 進数で書きます。スパン ID は 8 バイトで、16 文字で書きます。OpenTelemetry のトレース API 仕様は、少なくとも 1 バイトが 0 でない ID だけを有効とし、どちらも小文字の 16 進数で書きます。

OpenTelemetry では、スパンコンテキストがトレース ID、スパン ID、トレースフラグ、トレースステートを持ちます。`traceparent` が運ぶのは最初の 3 つです。トレースステートは最大 32 個のベンダーエントリーのリストで、`tracestate` ヘッダーが運びます。LogBrew の SDK はどちらも `tracestate` を書きません。

|  | トレース ID | スパン ID |
| --- | --- | --- |
| 16 進数の文字数 | `32` | `16` |
| ホップをまたいで同じ | はい | いいえ |
| すべて 0 でも有効 | いいえ | いいえ |

## ヘッダーが正しくないとき

勧告が認めるのは小文字の 16 進数だけで、バージョン `ff` とすべて 0 の ID を禁止しています。そのようなヘッダーを受け取ったサービスは、ヘッダーを無視して新しいトレースを開始する必要があります。両方の SDK は `ff` と、すべて 0 のトレース ID や親 ID でそのように動きました。

両方の SDK は大文字のトレース ID を受け入れ、小文字にして渡しました。小文字で送ってください。厳格なサービスは代わりに新しいトレースを開始します。

ヘッダーがないとき、`checkout` はフラグ `01` で、`payments` はフラグ `00` でトレースを開始しました。LogBrew はどちらのトレースも保存しました。

| トレース ID を維持 | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| 大文字のトレース ID | はい | はい |
| バージョン `ff` | いいえ | いいえ |
| すべて 0 のトレース ID | いいえ | いいえ |
| すべて 0 の親 ID | いいえ | いいえ |

## よくある質問

### トレース ID とは何ですか？

トレース ID は 16 バイトの ID で、32 文字の小文字の 16 進数で書きます。1 件のリクエストを、それが届くすべてのサービスで示します。各サービスは `traceparent` ヘッダーでこれを渡します。

### トレース ID とスパン ID の違いは何ですか？

トレース ID は 1 件のリクエストのすべてのサービスで同じです。スパン ID は 1 つのサービスの 1 つの処理を示します。今回のリクエストにはトレース ID が 1 つ、スパン ID が 3 つありました。

### traceparent ヘッダーとは何ですか？

`traceparent` は W3C Trace Context 勧告の HTTP ヘッダーです。バージョン、トレース ID、呼び出し元のスパン ID、トレースフラグを `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01` のように持ちます。

### traceparent の末尾の 01 は何を意味しますか？

`01` は sampled フラグが立っていることを示し、呼び出し元がトレースを記録した可能性があります。`00` は記録しなかったことを示します。LogBrew の両方の SDK はどちらの値も渡し、LogBrew はトレースを保存しました。

### 同じトレース ID のログをすべて見つけるには？

`logbrew read logs --project "<project_id>" --trace <trace_id>` を実行するか、LogBrew ダッシュボードのログの検索ボックスにトレース ID を貼り付けます。リクエスト中に SDK が書くログには、そのリクエストのトレース ID が付きます。

### traceparent ヘッダーは大文字と小文字を区別しますか？

はい。勧告が認めるのは小文字の 16 進数だけです。LogBrew の両方の SDK は大文字のトレース ID を受け入れて小文字にしましたが、厳格なサービスはヘッダーを無視します。

## 1 回の検索でトレースのログをすべて見つける

Node.js と FastAPI 向けの LogBrew SDK は `traceparent` を読み書きし、各ログはリクエストのトレース ID を保持します。余裕のある無料プランで始められます。クレジットカードは不要です。

[無料で始める](https://logbrew.co/ja)

## 出典

- [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/ja/guides/mcp-server-claude-code-codex)
- [Claude Code と Codex で AGENTS.md を使う](https://logbrew.co/ja/guides/agents-md)
- [Claude の overloaded エラー 529 とレート制限エラー 429 を解決する](https://logbrew.co/ja/guides/claude-overloaded-rate-limit-error)
- [Python logging を正しいログレベルと例外の記録つきで設定する](https://logbrew.co/ja/guides/python-logging)
- [構造化ログ（structured logging）でフィールドから検索できるログの書式とログレベルを整える](https://logbrew.co/ja/guides/structured-logging)
- [Node.js のログを Pino か Winston でエラーを失わずに設定する](https://logbrew.co/ja/guides/node-logging)
- [Django のログを設定してすべての 500 エラーのトレースバックを残す](https://logbrew.co/ja/guides/django-logging)
- [FastAPI のログを設定してトレースバックを失わずにエラーを処理する](https://logbrew.co/ja/guides/fastapi-logging)
- [React にエラーバウンダリを追加してそれが見逃すエラーも記録する](https://logbrew.co/ja/guides/react-error-boundary)
- [エラー、ログ、トレース、メトリクス、リリースのガイド](https://logbrew.co/ja/guides)
