🔭 Jaeger×OpenTelemetryでAIエージェントの意思決定→ツール実行をトレースする

起点: CNCF Blog「How Jaeger is Evolving to Trace AI Agents with OpenTelemetry」(2026-05-26)
検証日: 2026-05-27 / 対象読者: 実装エンジニア・SRE・LLMOps

AI エージェントの実行は「プロンプト組み立て → LLM 呼び出し → ツール選択 → ツール実行 → 外部 API → 再計画」という非線形な連鎖で進みます。従来のマイクロサービス向け分散トレーシングでは、LLM 呼び出し単位のレイテンシは可視化できても、「なぜそのツールを選んだのか」という意思決定の層が欠落します。

この記事では、Jaeger v2 と OpenTelemetry GenAI Semantic Conventions を使って、エージェントの「意思決定 → ツール実行」の経路を 1 本のトレースに載せる方法を、構造・データ・実装・運用の順に整理します。

概要

なぜエージェント観測に分散トレーシングが必要か

エージェント観測に分散トレーシングが必要な理由は 3 点に集約されます。

1. 実行経路の可視化: 単一リクエストが複数の LLM 呼び出し・ツール実行にまたがる連鎖を、1 本のトレースとして可視化できます。
2. 因果関係の追跡: invoke_agent → chat → execute_tool の親子関係により、「どの意思決定がどのツール実行を引き起こしたか」を span の親子構造で追えます。
3. 共通語彙の確立: OpenTelemetry GenAI Semantic Conventions が計装・バックエンド・観測ツールをまたぐ共通語彙を提供し、フレームワーク・ベンダ横断での相互運用を可能にします。

本番稼働組織の 71.5% が個別ステップまで見るフルトレーシングを保有しているという調査結果もあります（LangChain 2025/12 調査、二次情報）。

Jaeger v2 とは何か

Jaeger は Uber が 2015 年に開発し、2019-10-31 に CNCF Graduated Project に昇格した分散トレーシング基盤です（GitHub star 約 22,800、2026-05-27 時点）。v2（最新 v2.18.0 = 2026-05-13）では OpenTelemetry Collector のカスタムディストリビューションとして全面再構築されました。

「OTLP をそのまま受ける」構造が、OTel ベースの GenAI 計装ライブラリ（OpenLLMetry / OpenInference / Logfire 等）を設定変更だけで接続できる土台になっています。

OpenTelemetry GenAI Semantic Conventions とは何か

OTel GenAI Semantic Conventions は、LLM・エージェント・ツール実行を OTel の span・属性・メトリクスで表現するための共通語彙を定義する仕様です。span operation は 9 種定義されており、エージェント観測に特に重要なものは次の 3 つです。

LLM 専用観測プラットフォームとの位置づけ

Jaeger は個別トレースを精査する道具として機能します。一方、Langfuse・Phoenix・LangSmith・Braintrust などの LLM 専用観測プラットフォームは、trace に加えて eval・プロンプト管理・コスト集計を統合した上位レイヤとして機能します。

両者は対立ではなく補完関係です。LLM 専用 PF も OTel / OpenInference を ingest 経路に採用しており、「OTel が共通土台」という流れはむしろ補強されます。現実解は SpanProcessor 二重登録による併用（Jaeger=精査、Langfuse/Phoenix=集計・eval）です。

エコシステムと標準動向（MCP / ACP / AG-UI）

「観測性がプロダクト個別実装からプロトコル側へ寄っている」という見方は半分正しく、正確にはプロトコル本体ではなく、横断標準の OpenTelemetry GenAI / MCP semconv へ寄っています。

MCP が観測性標準化の最前線、AGNTCY が分離設計の好例です。プロトコル"内"標準化は未完です。

構造

システムコンテキスト図

エージェント観測パイプラインが「誰」と「何」に囲まれているかを示します。

コンテナ図

観測パイプライン内部を、協調するプロセス群・ライブラリで分解します。

コンポーネント図

Jaeger v2 内部を OTel Collector のコンポーネントモデルでドリルダウンします。

データ

OTel GenAI Semantic Conventions（Development）が定義するトレースのデータ構造を、概念モデルと情報モデルの 2 層で示します。

概念モデル

エンティティ名のみを記載します。所有は subgraph、利用は矢印で示します。

情報モデル

主要属性のみ記載します。型は汎用名（string / int / list / map / float / bool）を使います。

補足は次のとおりです。

• gen_ai.operation.name の値は chat / text_completion / embeddings / generate_content / retrieval / execute_tool / create_agent / invoke_agent / invoke_workflow の 9 種です。
• AgentSpan は invoke_agent または create_agent を operation に持つ Span の特化形です。
• Messages の各属性は Opt-In（PII を含みうるため明示有効化が必要）です。
• ToolCall.gen_ai.tool.call.id は chat の出力中の tool_call と execute_tool span を対応付けるキーです。
• EvaluationResult は Span 属性ではなく gen_ai.evaluation.result イベントとして emit されます。
• MCP Span は execute_tool の一種で、traceparent を params._meta に inject して伝播します（SHOULD / Development）。
• 全 gen_ai.* 属性は Development。error.type / server.address / server.port のみ Stable（汎用 semconv 由来）です。

構築方法

Jaeger v2 の起動

Jaeger v2（最新 v2.18.0、2026-05-13）は単一イメージ jaegertracing/jaeger で提供されます。OTLP レシーバはデフォルト有効のため追加設定は不要です。

前提条件は次のとおりです。

• Docker または Podman（ローカル検証時）
• Python 3.9+（計装コード側）
• ポート開放: 16686（UI）、4317（OTLP/gRPC）、4318（OTLP/HTTP）

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  jaegertracing/jaeger:2.18.0

起動確認:

curl -s http://localhost:16686/api/services   # {"data":[],...} が返れば OK

Jaeger v1 との差（後方互換メモ）

v1 を使う場合の起動例:

docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 -p 4317:4317 -p 4318:4318 \
  jaegertracing/all-in-one:latest

利用方法

必須パラメータ一覧

パターン A: OpenInference + LangChain → Jaeger（最短）

pip install openinference-instrumentation-langchain \
            opentelemetry-sdk opentelemetry-exporter-otlp-proto-http \
            langchain langgraph langchain-openai

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.langchain import LangChainInstrumentor

provider = TracerProvider(resource=Resource.create({"service.name": "agent-demo"}))
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter("http://localhost:4318/v1/traces"))
)
trace.set_tracer_provider(provider)
LangChainInstrumentor().instrument(tracer_provider=provider)
# 以降は通常通りエージェントを実行 → Jaeger UI で trace を閲覧

パターン B: OpenLLMetry（環境変数だけで送信）

pip install traceloop-sdk
export TRACELOOP_BASE_URL="http://localhost:4318"   # SDK が /v1/traces を自動付加

from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import workflow, agent, tool

Traceloop.init(app_name="agent-demo")

@tool(name="search_web")
def search_web(query: str) -> str: ...

@agent(name="researcher")
def researcher(query: str) -> str:
    return search_web(query)        # → execute_tool 子 span

@workflow(name="research_flow")
def main(query: str) -> str:
    return researcher(query)        # → invoke_agent 子 span を内包

パターン C: Google ADK 1.17.0+（コード変更ほぼ不要）

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://localhost:4318/v1/traces"

ADK 1.17.0 以降は OTel 内蔵で、agent 実行がそのままトレース対象になります。自動生成される span 階層（GenAI semconv 準拠）は次のとおりです。

invoke_agent {agent.name}          ← root span: エージェント実行全体
├── chat {model}                   ← 子 span: LLM 呼び出し（意思決定）
│     gen_ai.response.finish_reasons=tool_calls   ← ツール使用決定の証跡
├── execute_tool {tool.name}       ← 子 span: ツール実行
│     gen_ai.tool.call.id          ← 意思決定との紐付け
└── chat {model}                   ← 子 span: ツール結果を踏まえ再推論

パターン D: Jaeger + Langfuse への二重送信

BatchSpanProcessor を 2 つ登録し、同一トレースを Jaeger（精査）と Langfuse（eval・コスト）に同時送信します。

import base64
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.langchain import LangChainInstrumentor
from opentelemetry import trace

langfuse_auth = base64.b64encode(b"pk-lf-...:sk-lf-...").decode()
provider = TracerProvider()
# 宛先1: Jaeger（精査）
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter("http://localhost:4318/v1/traces"))
)
# 宛先2: Langfuse（eval・コスト。OTLP/HTTP のみ、gRPC 非対応）
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(
        endpoint="https://cloud.langfuse.com/api/public/otel/v1/traces",
        headers={"Authorization": f"Basic {langfuse_auth}"},
    ))
)
trace.set_tracer_provider(provider)
LangChainInstrumentor().instrument(tracer_provider=provider)

Jaeger UI で「意思決定→ツール実行」を読む

1. http://localhost:16686 にアクセスし、Service で agent-demo を選択 → Find Traces。
2. invoke_agent 親 span を展開する。
3. 子 span chat {model} の gen_ai.response.finish_reasons が tool_calls → LLM がツール使用を決定した証跡。
4. 続く execute_tool {tool.name} span の gen_ai.tool.call.id → どの決定がどの実行を引き起こしたかの紐付け。
5. timeline で「思考 → 実行 → 再思考」のサイクルが一望できる。

運用

trace の保持とサンプリング戦略

AI エージェントは長時間実行・多段ツール呼び出しで、1 trace あたりの span 数が数十〜数百に膨れやすいです。

• 開発・デバッグ: 全量収集（AlwaysOn）。
• ステージング〜本番: ParentBased(root=TraceIdRatioBased) で調整。エージェントは 1 trace が長大なため tail-based sampling を推奨します。OTel Collector の tail_sampling で「エラー含む trace は 100% 保持、正常は 10%」を実現できます。
• 高コスト trace の全量保持: gen_ai.usage.input_tokens でフィルタする tail ルールを設けます。

processors:
  tail_sampling:
    decision_wait: 10s
    policies:
      - name: errors-policy
        type: status_code
        status_code: {status_codes: [ERROR]}
      - name: token-heavy-policy
        type: numeric_attribute
        numeric_attribute: {key: gen_ai.usage.input_tokens, min_value: 10000}
      - name: probabilistic-policy
        type: probabilistic
        probabilistic: {sampling_percentage: 10}

ストレージ backend 選定

保持期間はエージェントトレースの診断価値が高いため、デフォルト 2 日より長い 14〜30 日を推奨します（--es.max-span-age / Cassandra TTL で制御）。

トークン/コスト集計は別 metrics backend が必要

Jaeger は traces のみを対象とし、metrics を集計しません。gen_ai.usage.* は個別 span 属性として保存されますが、「モデル別の 1 日のトークン総量」のような集計ダッシュボードは Jaeger 単体では作れません。metrics（gen_ai.client.token.usage ヒストグラム）は Prometheus + Grafana か LLM 専用 PF に二重送信します。

ベストプラクティス

1. 計装を OTel GenAI semconv に統一する: gen_ai.operation.name を統一語彙に揃える。OTel ネイティブでないフレームワーク（OpenAI Agents SDK 等）は OpenLLMetry / OpenInference を挟む。
2. OTEL_SEMCONV_STABILITY_OPT_IN で版を固定する: semconv は Development で破壊的変更あり。gen_ai_latest_experimental を opt-in する際は CI でライブラリバージョンをピン留めし changelog を監視する。デフォルトは旧属性名固定の点に注意。
3. 意思決定の証跡を span に残す: 標準で取れる finish_reasons / gen_ai.tool.call.* を活用。reasoning の中身は Opt-In の gen_ai.input.messages / output.messages（PII マスキング方針を先に決める）。reasoning テキスト格納は未標準で、厚く記録するなら OpenInference の message_content.type=reasoning 拡張。
4. 精査用と集計用を分け SpanProcessor 二重送信する: Jaeger=trace 精査、Prometheus/Grafana か Langfuse/Phoenix=集計・eval。
5. MCP 境界の trace context 伝播を自前検証する: params._meta.traceparent が実際に渡っているかを Jaeger の span で確認し、tool server 側にも W3CTraceContextPropagator を入れる。

# reasoning を Opt-In かつマスキング付きで記録する例
import re
from opentelemetry import trace
tracer = trace.get_tracer(__name__)

def mask_pii(text: str) -> str:
    return re.sub(r'[\w.-]+@[\w.-]+', '[EMAIL]', text)

with tracer.start_as_current_span("chat gpt-4o") as span:
    response = llm.invoke(prompt)
    span.set_attribute("gen_ai.output.messages", mask_pii(str(response)))
    span.set_attribute("gen_ai.response.finish_reasons", response.finish_reasons)

トラブルシューティング

まとめ

AI エージェント観測の span 設計の正本は OpenTelemetry GenAI Semantic Conventions に収斂しつつあり、invoke_agent > chat > execute_tool の階層で「意思決定 → ツール実行」を 1 トレースに載せられます。Jaeger v2 は OTLP をネイティブ受信するため計装の宛先を向けるだけで着きますが、semconv が Development である点・GenAI 向け UI が未完（Issue #8401）である点・metrics 非対応でコスト集計が別系になる点を踏まえ、Jaeger を「精査用」、Langfuse/Phoenix や metrics backend を「集計・eval 用」として併用するのが現実解です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

公式ドキュメント・標準

• Jaeger Architecture
• Jaeger v2 Configuration
• OpenTelemetry GenAI semantic conventions
• GenAI Agent Spans
• GenAI Events
• GenAI MCP semconv
• Google ADK Traces
• Langfuse OpenTelemetry

GitHub

• Jaeger Issue #8401 (GenAI 可視化)
• Jaeger Issue #8252 (AG-UI→ACP PoC)
• OpenLLMetry (traceloop)
• OpenInference (Arize)
• semantic-conventions v1.37.0 gen-ai

記事・反証・事例

• How Jaeger is Evolving to Trace AI Agents with OpenTelemetry (CNCF Blog)
• Agent traces need to cross the MCP boundary
• Distributed tracing for agentic workflows (Red Hat)
• Best LLM tracing tools 2026 (Braintrust)