【実務・中級編】分散トレーシング(OpenTelemetry)によるAPIリクエストの追跡 – Web APIアーキテクチャ・データ連携実践ガイド

皆さん、ご機嫌いかがでしょうか。ネットワークの深淵に魅せられ、パケットの鼓動に耳を傾け続けてきた、この私がお届けします。今日のテーマは、現代の複雑怪奇なシステムを解き明かすための最強の武器、分散トレーシング、そしてそのデファクトスタンダードとなりつつあるOpenTelemetryについてです。

マイクロサービスアーキテクチャが主流となり、一つのリクエストが複数のサービスを縦横無尽に駆け巡るのが当たり前になりました。しかし、その恩恵を享受する一方で、システム内部が「ブラックボックス」化し、いざトラブルが発生した際に「どこで何が起きているのか」「ボトルネックはどこか」を特定するのが非常に困難になったと感じている方も多いのではないでしょうか。

まさに、この「見えない壁」を打ち破り、システム全体に「光を当てる」技術こそが、分散トレーシングなのです。本記事では、特にWeb APIの文脈において、OpenTelemetryがどのようにしてマイクロサービス間のリクエストを追跡し、その詳細な挙動を可視化するのかを、実践的なコード例を交えながら深掘りしていきます。

複雑なAPI連携の迷宮を照らす光：分散トレーシングの必要性

かつてモノリシックなアプリケーションが主流だった時代は、一つのプロセス内で全ての処理が完結するため、問題発生時のデバッグは比較的シンプルでした。しかし、現代のシステムは複数の独立したサービスがAPIを介して連携し、非同期処理やメッセージキューを多用するなど、その複雑さは指数関数的に増大しています。

例えば、ユーザーがECサイトで商品を注文する際のリクエストを考えてみてください。
1. フロントエンドからの注文リクエストがAPI Gatewayに到達。
2. 注文サービスがリクエストを受け取り、データベースに注文を登録。
3. 在庫サービスに問い合わせて在庫を確保。
4. 決済サービスに連携して支払い処理を実行。
5. 通知サービスに処理結果を渡し、ユーザーにメールを送信。
6. 全ての処理が完了した後、最終的なレスポンスがユーザーに返却される。

この一連のフローの中で、もしレスポンスが遅延したり、エラーが発生したりした場合、あなたはどのサービスが原因だと特定できるでしょうか？ログを横断的に集めても、単一のリクエストに紐づく全てのログを関連付けるのは至難の業です。まるで、暗闇の中で一本の糸を辿るようなものです。

ここで登場するのが、分散トレーシングです。分散トレーシングは、このような複雑なマイクロサービス環境において、単一のリクエスト（ユーザー操作やAPIコールなど）がシステム内でどのように伝播し、どのような処理を経て完了したかをエンドツーエンドで追跡し、可視化するための技術です。そして、その共通言語として標準化が進められているのが、OpenTelemetryというわけです。

OpenTelemetryの基本概念：Trace IDとSpan IDが織りなす物語

OpenTelemetryは、トレーシング（追跡）、メトリクス（測定）、ロギング（記録）の3つのオブザーバビリティ要素を標準化し、ベンダーニュートラルな形でデータ収集・エクスポートを可能にするCNCF（Cloud Native Computing Foundation）プロジェクトです。今回はその中でも特に「トレーシング」に焦点を当てます。

分散トレーシングを理解する上で、最も重要な概念がTraceとSpanです。これを映画や小説の「物語」に例えると分かりやすいでしょう。

Trace：一つの物語の始まりから終わりまで

Trace（トレース）は、システムに対する単一のリクエスト（ユーザー操作やAPIコールなど）が開始されてから完了するまでの一連の処理全体を表します。先ほどのECサイトの例で言えば、「ユーザーが商品を注文する」という一連のビジネスプロセス全体が1つのTraceです。

このTraceを一意に識別するのがTrace ID（トレースID）です。Trace IDは、システムに入ってきたリクエストの入り口で一度生成され、そのリクエストがどんなサービスを跨ごうとも、最後まで一貫して引き継がれていきます。これにより、たとえ異なるサービスやプロセスで生成されたログやメトリクスであっても、同じTrace IDを持つもの同士を関連付けて、一つの「物語」として追跡できるようになるのです。

Span：物語を構成する個々の出来事

Span（スパン）は、Traceを構成する個々の操作や処理の単位を表します。例えば、「API Gatewayでリクエストを受信する」「注文サービスがデータベースに登録する」「在庫サービスに問い合わせる」といった、一つ一つの処理がSpanに対応します。

各Spanには、そのSpan自身を一意に識別するSpan ID（スパンID）が割り当てられます。さらに、どのTraceに属するSpanなのかを示すためにTrace IDも持ちます。

Spanは親子関係を持つことができます。ある処理（親Span）の中で、さらに細かい処理（子Span）が実行される場合、子Spanは親Spanの情報を引き継ぎます。これにより、処理の階層構造を表現し、時間軸上でどの処理がどの処理の一部として実行されたかを明確にできるのです。

Root Span（ルートスパン）: Traceの起点となる最初のSpan。親Spanを持たない。
Child Span（チャイルドスパン）: 親Spanを持つSpan。

Context Propagation：バトンリレーで繋ぐTrace IDとSpan ID

では、複数のサービス間をまたがるリクエストで、どのようにしてTrace IDやSpan IDが伝播していくのでしょうか？その鍵を握るのがContext Propagation（コンテキスト伝播）です。

これは例えるなら、オリンピックの聖火リレーの「バトン」のようなものです。サービスAが処理を開始し、新しいSpanを生成したら、そのSpanのTrace IDとSpan ID（そして、現在のSpanが親Spanとなる場合はそのSpan ID）をHTTPヘッダーなどの形で次のサービスBに「バトン」として渡します。サービスBはこのバトンを受け取り、自身の処理を開始する際に、受け取ったTrace IDを自身のSpanに引き継ぎ、さらに新しい子Spanを生成する際に、渡されたSpan IDを親Span IDとして設定する、といった具合です。

これにより、一連のリクエストは途切れることなく、単一のTraceとして追跡されるのです。

RFC 8892：W3C Trace Contextによる標準化

このContext Propagationの方式は、かつては各APMベンダーが独自の実装を持っていましたが、それでは相互運用性が担保されません。異なるベンダーのAPMツールやSDKを組み合わせて使うことができませんでした。

この課題を解決するために、W3C（World Wide Web Consortium）が標準化したのがW3C Trace Context (RFC 8892)です。これは、HTTPヘッダーを介してTrace IDとSpan ID（およびその他のコンテキスト情報）を伝播させるための共通フォーマットを定義しています。OpenTelemetryはこの標準に準拠しています。

W3C Trace Contextでは主に以下の2つのHTTPヘッダーが使われます。

traceparent ヘッダー

traceparent ヘッダーは、現在のリクエストのトレーシングコンテキストの必須部分を伝達します。これは、Trace ID、Parent Span ID（現在のSpanの親となるSpan ID）、およびトレーシングフラグを含みます。

フォーマットは以下の通りです。
traceparent: <version>-<trace-id>-<parent-id>-<trace-flags>

各要素の意味は以下の通りです。

<version>: Trace Contextプロトコルのバージョン。現在、多くは 00 です。
<trace-id>: 16バイトのグローバルに一意なTrace ID（32桁の16進数）。
<parent-id>: 8バイトのSpan ID（現在のSpanの親となるSpan ID）（16桁の16進数）。
<trace-flags>: トレースの挙動に関するオプションフラグ（8桁の2進数で、通常は2桁の16進数）。例えば、サンプリングされているか否かなど。

例:
traceparent: 00-4bf92f3577b34da6a3ce9232a67e4359-00f067aa0ba902b7-01

00: バージョン
4bf92f3577b34da6a3ce9232a67e4359: Trace ID
00f067aa0ba902b7: 親Span ID（このリクエストを呼び出したSpanのID）
01: トレースフラグ（サンプリング済みであることを示す）

tracestate ヘッダー

tracestate ヘッダーは、ベンダー固有の追加のトレーシングコンテキスト情報を伝達するために使用されます。これは、複数のベンダーが関与する環境で、それぞれのベンダーが自社システムに特有の情報を伝播させる際に利用されます。

フォーマットは以下の通りです。
tracestate: <vendor1-key>=<vendor1-value>,<vendor2-key>=<vendor2-value>

例:
tracestate: congo=t6mtgfbusjpamqj6,rojo=00f067aa0ba902b7

このヘッダーはオプションであり、traceparent ヘッダーが必須であるのに対し、tracestate は、特定のユースケースやベンダーとの連携が必要な場合に利用されます。一般的なOpenTelemetryの自動計装では、traceparent のみを主に扱えば十分なケースが多いでしょう。

マイクロサービス間のTrace ID/Span ID伝播シーケンス

では、これらのヘッダーが実際にどのように伝播していくのか、簡単なシーケンスで見てみましょう。

1. クライアント (Webブラウザ/モバイルアプリ)

ユーザーが操作を開始。
OpenTelemetry SDKが新しいTrace IDを生成し、最初のRoot Spanを開始。
このRoot SpanのTrace IDとSpan IDを元に、traceparent ヘッダーを生成。
API Gatewayへのリクエストにこのtraceparent ヘッダーを付与して送信。

GET /api/order HTTP/1.1
    Host: api.example.com
    traceparent: 00-4bf92f3577b34da6a3ce9232a67e4359-00f067aa0ba902b7-01

2. サービスA (API Gateway)

リクエストを受信。traceparent ヘッダーからTrace ID (4bf9...) とParent Span ID (00f0...) を抽出。
新しいChild Spanを開始。このSpanのTrace IDは受信したTrace ID (4bf9...) を継承し、Parent Span IDは受信したParent Span ID (00f0...) を設定。自身のSpan ID (8a6b...) を生成。
サービスBへのリクエストを構築する際に、traceparent ヘッダーを更新。Trace ID (4bf9...) はそのままに、Parent Span IDを自身のSpan ID (8a6b...) に置き換えて送信。

GET /internal/process-order HTTP/1.1
    Host: order-service.internal
    traceparent: 00-4bf92f3577b34da6a3ce9232a67e4359-8a6b7c8d9e0f1a2b-01

3. サービスB (注文サービス)

リクエストを受信。traceparent ヘッダーからTrace ID (4bf9...) とParent Span ID (8a6b...) を抽出。
新しいChild Spanを開始。Trace IDは受信したものを継承。Parent Span IDも受信したものを設定。自身のSpan ID (cdef...) を生成。
サービスCへのリクエストを構築する際に、traceparent ヘッダーを更新。Trace ID (4bf9...) はそのままに、Parent Span IDを自身のSpan ID (cdef...) に置き換えて送信。

GET /internal/check-stock HTTP/1.1
    Host: stock-service.internal
    traceparent: 00-4bf92f3577b34da6a3ce9232a67e4359-cdef1234567890ab-01

4. サービスC (在庫サービス)

リクエストを受信。Trace ID (4bf9...) とParent Span ID (cdef...) を抽出。
新しいChild Spanを開始し、処理を実行。このサービスでリクエストが完結する場合、次のサービスへのリクエストは発生しない。
処理が完了したら、Spanを終了。

この流れで、Trace IDは最初から最後まで一貫して維持され、Span IDは各サービスで適切に親子関係を築きながら伝播していくのです。

実践！APIリクエストにTrace ID/Span IDを乗せる

ここからは、実際に手動でTrace Contextヘッダーを付与してAPIリクエストを送信する例を見ていきましょう。実際の運用ではOpenTelemetry SDKが自動的にこれらをやってくれますが、裏側で何が起きているかを理解するためには、手動での操作を知っておくことは非常に重要です。

1. curl コマンドで手動でヘッダーを付与する

最も原始的で分かりやすいのが curl コマンドです。ここでは、適当なTrace IDとSpan IDを生成してリクエストに含めてみましょう。

# 適当なTrace IDとSpan IDを生成 (実際はOpenTelemetry SDKが生成します)
# Trace ID: 16バイト (32桁の16進数)
TRACE_ID=$(head /dev/urandom | tr -dc a-f0-9 | head -c 32)
# Span ID: 8バイト (16桁の16進数)
SPAN_ID=$(head /dev/urandom | tr -dc a-f0-9 | head -c 16)

echo "Generated Trace ID: ${TRACE_ID}"
echo "Generated Span ID: ${SPAN_ID}"

# traceparent ヘッダーを作成
# フォーマット: <version>-<trace-id>-<parent-id>-<trace-flags>
# ここではバージョン00、Trace IDとSpan IDを生成し、flagsは01 (sampled) とする
TRACE_PARENT_HEADER="00-${TRACE_ID}-${SPAN_ID}-01"

echo "traceparent header: ${TRACE_PARENT_HEADER}"

# curl コマンドでリクエストを送信
# -H オプションでHTTPヘッダーを指定
# ここでは例としてJSONPlaceholderのAPIにリクエストします
curl -X GET \
  -H "traceparent: ${TRACE_PARENT_HEADER}" \
  -H "Content-Type: application/json" \
  https://jsonplaceholder.typicode.com/posts/1

この curl コマンドを実行すると、指定した traceparent ヘッダーが付与されてリクエストが送信されます。もし、jsonplaceholder.typicode.com 側でOpenTelemetryの計装が行われていれば、このTrace IDとSpan IDがログやトレースデータに記録されるはずです（ただし、jsonplaceholderは公開APIなので、通常はトレーシングされていません）。

2. JavaScript (Fetch API) でヘッダーを付与する

フロントエンドのWebアプリケーションからAPIを呼び出す際も、同様にヘッダーを付与できます。

// Trace IDとSpan IDを生成するヘルパー関数
// 実際にはOpenTelemetryのブラウザSDKが自動で行います
function generateRandomHex(length) {
  const chars = '0123456789abcdef';
  let result = '';
  for (let i = 0; i < length; i++) {
    result += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return result;
}

const traceId = generateRandomHex(32); // 32桁の16進数
const spanId = generateRandomHex(16);  // 16桁の16進数
const traceParentHeader = `00-${traceId}-${spanId}-01`; // traceparentヘッダーを構築

console.log(`Generated Trace ID: ${traceId}`);
console.log(`Generated Span ID: ${spanId}`);
console.log(`traceparent header: ${traceParentHeader}`);

fetch('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // traceparentヘッダーを付与
    'traceparent': traceParentHeader
  },
  body: JSON.stringify({
    title: 'foo',
    body: 'bar',
    userId: 1,
  }),
})
.then(response => response.json())
.then(data => console.log('API Response:', data))
.catch(error => console.error('Error:', error));

ブラウザの開発者ツール（Networkタブ）でこのリクエストを調べると、traceparent ヘッダーが確かに付与されていることを確認できます。

3. Python (requestsライブラリ) でヘッダーを付与する

Pythonの requests ライブラリを使って、サーバーサイドのサービスから別のサービスを呼び出す例です。

import requests
import os
import secrets

# Trace IDとSpan IDを生成する (実際はOpenTelemetry SDKが自動で行います)
# Trace ID: 16バイト (32桁の16進数)
trace_id = secrets.token_hex(16)
# Span ID: 8バイト (16桁の16進数)
span_id = secrets.token_hex(8)

print(f"Generated Trace ID: {trace_id}")
print(f"Generated Span ID: {span_id}")

# traceparent ヘッダーを作成
# フォーマット: <version>-<trace-id>-<parent-id>-<trace-flags>
trace_parent_header = f"00-{trace_id}-{span_id}-01"

print(f"traceparent header: {trace_parent_header}")

# HTTPヘッダーを辞書形式で定義
headers = {
    "Content-Type": "application/json",
    # traceparentヘッダーを付与
    "traceparent": trace_parent_header
}

# APIエンドポイント
api_url = "https://jsonplaceholder.typicode.com/users/1"

try:
    # GETリクエストを送信
    response = requests.get(api_url, headers=headers)
    response.raise_for_status() # HTTPエラーが発生した場合に例外を発生させる

    print("API Response:")
    print(response.json())

except requests.exceptions.RequestException as e:
    print(f"APIリクエスト中にエラーが発生しました: {e}")

OpenTelemetry SDKによる自動計装の重要性

上記の例は、traceparent ヘッダーを手動で組み立てることで、Context Propagationの仕組みを理解することを目的としています。しかし、実際のアプリケーション開発では、これらのヘッダーを手動で管理することは非常に煩雑であり、ヒューマンエラーの原因にもなりかねません。

そこで登場するのが、OpenTelemetryの各種言語向けSDK (Software Development Kit)です。OpenTelemetry SDKは、アプリケーションコードに計装（Instrumentation）を施すことで、明示的にコードを記述しなくても、自動的に以下の処理を行ってくれます。

リクエストの開始時にTrace IDとRoot Span IDを生成。
HTTPリクエスト/レスポンス、データベースクエリ、メッセージキュー操作などのI/O処理をSpanとして自動的に記録。
次のサービスへのリクエストにtraceparent および tracestate ヘッダーを自動で付与し、Context Propagationを実施。
Spanの開始・終了、属性（attributes）の追加、イベントの記録など。
生成されたトレースデータをOpenTelemetry Collectorを介して、JaegerやZipkinなどのバックエンドにエクスポート。

これにより、開発者はアプリケーションのビジネスロジックに集中しつつ、高品質なトレーシングデータを収集できるようになるのです。

ボトルネック特定のための可視化：トレースデータの活用

OpenTelemetry SDKによって収集され、OpenTelemetry Collectorを通じてエクスポートされたトレースデータは、Jaeger、Zipkin、Grafana Tempoなどのトレーシングバックエンドで集約・保存され、UIを通じて可視化されます。

これらのツールは、単一のTrace IDに紐づく全てのSpanを時間軸に沿って並べ、ツリー構造やガントチャート形式で表示してくれます。

可視化されたトレースデータの見方

可視化されたトレースデータを見ると、以下のような情報が一目で分かります。

Trace全体にかかった時間: リクエストが開始されてから完了するまでの総時間。
各Spanの実行時間: 各サービス内での処理時間や、外部サービスへの呼び出しにかかった時間。
Span間の親子関係: どの処理がどの処理の一部として実行されたか。
エラーの発生箇所: どのSpanでエラーが発生したか。
属性 (Attributes): HTTPメソッド、URL、データベースクエリ、ユーザーIDなど、各Spanに関連付けられた詳細情報。

ボトルネックの特定手法

この可視化されたトレースデータを活用することで、以下のようにボトルネックを特定できます。

1. 最も時間の長いSpanを探す: ガントチャート上で特に横に長く伸びているSpanは、その処理が全体の遅延に大きく寄与している可能性が高いです。
2. 特定のサービスに処理が集中しているか確認: あるサービスのSpan群だけが異常に長く、他のサービスへの呼び出しが完了するのを待っているような状況は、そのサービスがボトルネックになっていることを示唆します。
3. 外部サービス呼び出しの遅延: データベースクエリやサードパーティAPIへの呼び出しSpanが長い場合、そこがボトルネックです。
4. エラー発生箇所の特定: エラーを示すSpanがあれば、どのサービスで何が原因でエラーが発生したのかを迅速に特定できます。
5. 並列処理の評価: 複数のSpanが同時に実行されている場合、並列処理が効果的に行われているか、あるいはデッドロックなどの問題が発生していないかを分析できます。

これらの情報を活用することで、「このAPIリクエストの遅延は、注文サービスが在庫サービスからの応答を10秒間待っていたことが原因だ」といった具体的な原因特定が、ログを闇雲に検索するよりもはるかに迅速かつ正確に行えるようになるのです。

現場でのトラブルシューティングTips

最後に、私が現場で実際に経験してきた、分散トレーシングに関するトラブルシューティングのTipsをいくつかご紹介しましょう。

1. traceparent ヘッダーの伝播漏れは致命的

最も多いトラブルは、サービス間をまたぐHTTPリクエストでtraceparent ヘッダーが正しく伝播されていないケースです。これにより、トレースが途中で途切れてしまい、システム全体の一貫したトレースビューが得られなくなります。

確認方法:
開発者ツールやプロキシツール（Fiddler, Wireshark, tcpdumpなど）を使って、実際にHTTPリクエスト/レスポンスのヘッダーを確認する。
OpenTelemetry SDKのデバッグログを有効にして、Context Propagationが行われているか確認する。
原因と対策:
API Gatewayやプロキシがヘッダーを適切に転送していない場合がある。設定を見直す。
使用しているHTTPクライアントライブラリが、デフォルトで全てのヘッダーを転送しない設定になっていることがある。
OpenTelemetry SDKが正しく初期化されていない、あるいは計装が適用されていない。

2. サンプリング設定の理解と調整

OpenTelemetryは、大量のトレースデータ全てを収集するのではなく、設定された割合で一部のトレースのみを収集するサンプリングの仕組みを持っています。これにより、オブザーバビリティのコストとパフォーマンスオーバーヘッドを制御します。

問題: 特定のリクエストのトレースが見つからない場合、サンプリングによってスキップされた可能性があります。
対策:
開発環境やテスト環境ではサンプリングレートを100%に設定し、全てのトレースを確実に収集するようにする。
本番環境では、アプリケーションの重要度やトラフィック量に応じて、適切なサンプリングレートを設定する。エラーが発生したトレースは必ずサンプリングするなど、高度なサンプリング戦略も検討する。

3. Spanの粒度と詳細度

Spanは細かすぎても粗すぎても問題です。

Spanが細かすぎる場合: 大量のSpanが生成され、トレースデータの収集・保存・可視化のコストが増大し、パフォーマンスオーバーヘッドも大きくなります。
Spanが粗すぎる場合: 重要な処理がSpanとして記録されず、ボトルネックの特定が困難になります。

対策:
ビジネスロジックの主要なステップや、外部I/O（DBアクセス、外部API呼び出し、メッセージングなど）はSpanとして記録する。
ごく短い時間で完了する内部処理や、頻繁に呼び出されるユーティリティ関数などはSpanとして記録しない。自動計装でカバーされない部分で必要であれば、手動でSpanを追加することを検討する。

4. パフォーマンスオーバーヘッドへの意識

OpenTelemetry SDKの計装自体も、多少なりともアプリケーションのパフォーマンスに影響を与えます。特に、大量のリクエストを処理する高負荷なサービスでは、このオーバーヘッドが無視できないレベルになることがあります。

対策:
OpenTelemetry SDKのバージョンは常に最新のものを使用し、パフォーマンスが改善されていることを確認する。
OpenTelemetry Collectorを適切に配置し、アプリケーションからのデータエクスポートが非同期かつ効率的に行われるようにする。
前述のサンプリングを適切に設定し、不要なトレースデータを収集しないようにする。
本番環境への導入前に、十分な負荷テストを行い、パフォーマンスへの影響を評価する。

これらのTipsは、私が幾多の障害現場で汗水垂らして得た知見です。分散トレーシングは導入すれば万事解決というものではなく、その設計思想と運用上の注意点を理解し、適切に活用することで初めてその真価を発揮します。

まとめ：見えないものを可視化する力

今日の記事では、マイクロサービスアーキテクチャにおける「見えない壁」を打ち破る、分散トレーシングとOpenTelemetryについて解説してきました。Trace IDとSpan IDが織りなす「物語」を理解し、W3C Trace Contextによる標準化されたContext Propagationの仕組みを知ることは、現代の複雑なシステムを設計・運用する上で不可欠なスキルです。

手動でHTTPヘッダーを操作する例を通じて、その裏側で何が起きているかを体感していただけたかと思います。そして、OpenTelemetry SDKによる自動計装が、いかに開発者の負担を軽減しつつ、高品質なトレーシングデータを提供してくれるかについても触れました。

収集されたトレースデータをJaegerやGrafana Tempoといったツールで可視化し、ボトルネックやエラーを迅速に特定する能力は、システムの安定稼働とパフォーマンス改善に直結します。これはまさに、暗闇の中を彷徨っていた私たちに、確かな「光」をもたらしてくれる技術と言えるでしょう。

これからも、進化し続けるネットワークとプロトコルの世界で、皆さんがより良いシステムを構築できるよう、私の経験と知識を惜しみなく共有していきます。次回の記事もどうぞお楽しみに！