分散システムの闇を照らす「灯火」：OpenTelemetryによるトレーシングの流儀
インフラエンジニアとして現場に立っていると、必ずと言っていいほど「あの時」がやってくる。フロントエンドからのリクエストがタイムアウトする。しかし、どのマイクロサービスで止まっているのか、どのDBクエリが悲鳴を上げているのか、一見しただけでは全く分からない。ログを10個のサーバーからgrepして突き合わせる……そんな泥臭い作業に明け暮れた経験は、誰にでもあるはずだ。
REST APIが洗練され、システムがマイクロサービス化すればするほど、リクエストは物理的な境界を超えて旅をする。この「旅」の全貌を可視化しなければ、モダンな分散システムの運用は不可能だ。今回は、現代のエンジニアが必須で習得すべき、OpenTelemetry（OTel）を用いた分散トレーシングの世界を深掘りしていく。
—
1. なぜ「Trace ID」が神なのか
分散トレーシングの核は、たった一つのIDにある。traceparent ヘッダーに含まれる Trace ID だ。
RFC 9522（W3C Trace Context）として標準化されているこの仕様は、リクエストの「始点」から「終点」まで、すべてのサービスが同じIDを継承することで成立する。
Trace ID: リクエスト全体を一意に識別する16バイトのID。Span ID: 個別の処理単位（DBアクセス、外部API呼び出しなど）を識別する8バイトのID。
これらがあることで、ログの海の中から「特定のユーザーの特定のクリック」が、どのサービスで何ミリ秒かかったのかを一本の線（トレース）として繋ぎ合わせることができるようになる。
—
2. 通信フロー：パケットが繋ぐ物語
マイクロサービス間を移動するパケットには、以下のようなヘッダーが挿入される。
1. Client: リクエスト送信時、traceparent ヘッダーを生成する。
2. Service A: ヘッダーを受け取り、自身の処理時間を計測。必要に応じて自身の Span ID を生成し、次の Service B へとヘッダーを伝播（Propagate）させる。
3. Service B: 同じ Trace ID を保持したまま、自身の処理を実行。
この連携により、監視ツール（JaegerやHoneycomb等）上で、滝のような「ガントチャート」が生成される。どこでネットワーク遅延が起きているか、どこがSQLのボトルネックかを一目で特定できる魔法のような仕組みだ。
—
3. 実践：Pythonで実装する計装の基本
では、実際にどう実装するか。泥臭い手動実装も勉強にはなるが、現場では opentelemetry-instrumentation を活用するのが定石だ。
以下は、Python (Flask) でリクエストを自動計測するための基本的な設定例だ。
# 必要なライブラリ: pip install opentelemetry-distro opentelemetry-exporter-otlp
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
# トレーサープロバイダーの設定
provider = TracerProvider()
# エクスポーター（収集サーバーへデータを送る）の設定
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4317"))
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# これでFlaskへのリクエストが自動的にトレースされる
# 開発者は意識せずに Trace ID が注入される—
4. curlで動作確認：生のリクエストを覗く
API設計者であれば、curl コマンドで traceparent ヘッダーを叩き、実際にシステムがどう反応するかを試すべきだ。W3C規格に従ったヘッダーを自分で構築してみよう。
# traceparent: version(00) - TraceID(32桁) - SpanID(16桁) - flags(01)
curl -v -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
http://api.example.com/v1/ordersこのヘッダーを付与してリクエストを送れば、バックエンドのログに同じ Trace ID が記録されるはずだ。もし記録されていなければ、そこが「トレーシングの断絶地点」であると即座に判断できる。
—
5. 現場のシニアとしてのアドバイス：落とし穴を避ける
最後に、現場でよくある失敗談を共有しておく。
- ヘッダーの伝播漏れ: サービス間でHTTP通信を行う際、ライブラリが自動でヘッダーをコピーしてくれないケースがある。
requestsやhttpxを使う場合は、必ずトレーシングライブラリが適切にフックされているか確認すること。 - サンプリングレートの最適化: 全リクエストを記録すると、ログのボリュームが爆発し、ストレージコストが跳ね上がる。本番環境では
ParentBasedサンプリングなどを使い、重要なエラー発生時のみトレースを詳細に残す設定（100%サンプリング）を行うのが賢い運用だ。 - 個人情報の混入:
Spanにアトリビュート（付加情報）としてユーザーのメアドやトークンを突っ込むな。これはセキュリティ事故の温床だ。IDや状態コードのみに留めるのがプロの作法である。
分散トレーシングは、単なる可視化ツールではない。それは「見えないネットワークの挙動を、エンジニアの意志で言語化する」ための言語だ。
設計の段階から「どうトレースするか」を意識してAPIを作る。これこそが、障害に強い堅牢なシステムを構築するための第一歩である。さあ、皆さんのサービスにも、この「灯火」を灯してみてほしい。
コメント