開発

OpenTelemetryで分散システムを可観測にする最初の一歩 — AIエージェントの可視化まで

2026/08/28

1. 全部入れようとして止まるパターン

トレース・メトリクス・ログのすべてを一度に計装しようとして、設定の複雑さに挫折するチームは多い。現実的な出発点は、まず「リクエストが複数サービスをまたいでどう流れたか」が見えるように、分散トレーシングだけを最初に入れることだ。

2. 最小構成の順序

エントリポイントとなるサービスにトレーシングSDKを組み込み、リクエストIDを発行する
下流のサービス呼び出し（HTTP・DBクエリ・外部API）を自動計装で拾う
トレースを1箇所のバックエンドに集約し、遅いリクエストを可視化する
メトリクスとログの相関を、あとから同じトレースIDで結びつける

3. 計装は「あとから足せる」設計にしておく

最初から完璧な計装を目指す必要はない。重要なのは、あとからメトリクスやログを同じトレースコンテキストに紐づけられるように、リクエストIDの伝播だけは最初期の設計に組み込んでおくことだ。ここを後回しにすると、後から結合するコストが指数関数的に膨らむ。

4. AIエージェント時代の新しい計装対象 — GenAI Semantic Conventions

分散トレーシングの考え方は、近年ではAIエージェントの内部動作を可視化する用途にも拡張されている。OpenTelemetryプロジェクトは、LLM呼び出し・エージェントの推論ステップ・ツール実行・ベクトルデータベースへの問い合わせといった、生成AI特有の処理を標準化された形で記録するための仕様「GenAI Semantic Conventions」を、2024年4月からGenAI SIG（専門ワーキンググループ）を通じて策定している。

この仕様では、エージェント全体を表すinvoke_agentという最上位のスパン（トレースの単位）の下に、個々のLLM呼び出しを表すchatスパンや、ツール実行を表すexecute_toolスパンが子として連なる構造で、エージェントの推論過程全体を1本のトレースとして再現できるようにする。使用したモデル名（gen_ai.request.model）、入出力のトークン数（gen_ai.usage.input_tokensなど）、応答が終了した理由（gen_ai.response.finish_reasons）といった属性が、ベンダーを問わず共通の名前で記録される設計になっている。

すでにOpenAI・Anthropic・LangChain・LlamaIndexなど主要なフレームワーク向けの自動計装パッケージが用意されており、既存のOpenTelemetryの計装基盤に、これらのGenAI向けの計装を追加する形で、AIエージェントの「どのツールを、どの順番で、どんな入出力で呼び出したか」を通常のマイクロサービスのリクエストと同じトレーシング基盤上で追跡できるようになりつつある。ただし2026年3月時点では、多くの属性がまだ「実験的（experimental）」ステータスであり、仕様が完全に安定しているわけではない点には注意が必要だ。

5. 実務への示唆

分散システムの可観測性という考え方そのものは、AIエージェントの登場によって不要になるどころか、むしろ重要性を増している。本誌が別記事で扱った「判断ログ」の設計や、AIエージェントが自律的にツールを呼び出す一連の処理を追跡する必要性は、従来のマイクロサービス間の呼び出しを追跡する分散トレーシングの延長線上にある課題だ。すでにOpenTelemetryを導入している組織であれば、GenAI Semantic Conventionsに対応した計装ライブラリを追加するだけで、既存の可観測性基盤にAIエージェントの動作を統合できる可能性が高い。ゼロから作り直す必要はない、という点が実務上の朗報だといえる。