LangChain OTEL Observability (Python)

概要

エンジニアが OpenTelemetry をセットアップし、プロンプトとレスポンスが Honeycomb に表示されることを期待しています。トレースは到着しますが、タイミング、モデル名、トークン数だけが表示されます。プロンプトの本文は空白です。これは バグではありません。OTEL GenAI セマンティック規約のプライバシー安全デフォルト (P27) であり、OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT がオフになっているためです。フラグをオンにして先に進もうという衝動に駆られます。マルチテナント ワークロードでその切り替えはリークになります。次のエンジニアがテナント A のトレースを検索すると、結果にテナント B の個人情報が表示されます。なぜなら、リダクションはアップストリームで実行されるはずだったのに、実行されなかったからです。

2 番目の落とし穴は LangGraph の内部に存在します。親の実行可能オブジェクトにアタッチされた BaseCallbackHandler は、内部エージェント ツール呼び出しでは発火しません。LangGraph がサブグラフごとに子ランタイムを作成し、コールバックが継承されないためです (P28)。サブグラフ内のスパンはウォーターフォール内で孤立して表示されるか、まったく表示されません。SLO ダッシュボードは、最も重要なネストされたエージェント ループでのレイテンシーをカウント不足にしています。

このスキルは LangChain 1.0 / LangGraph 1.0 を OTEL ネイティブ バックエンド (Jaeger、Honeycomb、Grafana Tempo、Datadog) にワイアします。正しいコンテンツキャプチャ ポリシー、サブグラフ対応のスパン伝播、5 つの LLM 固有 SLO (p95/p99 レイテンシ、エラー率、リクエストあたりのコスト、TTFT) および バーンレート アラート付きです。ピン留め: langchain-core 1.0.x、langgraph 1.0.x、opentelemetry-instrumentation-langchain >= 0.33、2026-04 現在の OTEL GenAI semconv。ペイン カタログ アンカー: P27、P28 (およびクロスリファレンス P04、P34、P37)。

前提条件

• Python 3.10+
• langchain-core >= 1.0, < 2.0、langgraph >= 1.0, < 2.0
• 選択された OTEL ネイティブ バックエンド: Jaeger (開発)、Honeycomb / Tempo / Datadog (本番)
• マルチテナントの場合: アップストリーム リダクション ミドルウェアが既に配置されていること (langchain-security-basics および langchain-middleware-patterns を参照)
• デプロイ時に環境変数を設定するアクセス権 (OTLP_ENDPOINT、API キー)

手順

ステップ 1 — SDK とインストルメンタをインストール、エクスポーターを設定

pip install \
  opentelemetry-api \
  opentelemetry-sdk \
  opentelemetry-exporter-otlp-proto-http \
  "opentelemetry-instrumentation-langchain>=0.33"

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

resource = Resource.create({
    "service.name": "my-langchain-app",
    "service.version": "1.0.0",
    "deployment.environment": os.getenv("ENV", "dev"),
})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(
    OTLPSpanExporter(
        endpoint=os.environ["OTLP_ENDPOINT"],       # per-backend; see matrix
        headers=_parse_headers(os.getenv("OTLP_HEADERS", "")),
    ),
    max_queue_size=2048,        # spans buffered before drop; raise for high volume
    max_export_batch_size=512,  # batched export keeps per-span overhead under 1ms
))
trace.set_tracer_provider(provider)

LangchainInstrumentor().instrument()   # emits gen_ai.* attrs on every run

BatchSpanProcessor は 1 ms 以下の非常に低いスパンあたりのオーバーヘッドを保ちます。SimpleSpanProcessor はローカル開発でのみ使用してください。スパンごとに呼び出しパスをブロックします。

バックエンドごとの OTLP_ENDPOINT とヘッダー設定は Backend Setup Matrix にあります。Jaeger、Honeycomb、Grafana Tempo、Datadog。

ステップ 2 — GenAI 属性スキーマを確認

1 つの呼び出しをトリガーして、バックエンドに到着したものを検査します。LangChain 1.0 は、すべてのチャット モデル スパンでこれらの gen_ai.* 属性をネイティブに発行します:

属性	例
gen_ai.system	anthropic
gen_ai.request.model	claude-sonnet-4-6
gen_ai.request.temperature	0.0
gen_ai.usage.input_tokens	1234
gen_ai.usage.output_tokens	567
gen_ai.response.finish_reasons	["stop"]

何か足りませんか? おそらく古いインストルメンタ バージョンまたは古いプロバイダー パッケージです。発行されたカスタム マトリックス全体と LangGraph のスパン タクソノミー (LangGraph.invoke → LangGraph.node.* → LangGraph.subgraph.*) は GenAI Semantic Conventions にあります。

ステップ 3 — プロンプト コンテンツ キャプチャを決定 (重要 — スキップしないこと)

エンジニアの本能は、キャプチャ フラグをオンにしてプロンプトを見ることです。オンにする前に、ワークロードを次のいずれかのカテゴリに分類してください:

ワークロード	フラグ	注釈
合成入力を使用した開発/ステージング	true	問題ありません。これらのトレースを本番環境にコピーしないでください。
シングルテナント内部ツール	true	バックエンドの RBAC が厳しければ問題ありません。
シングルテナント製品、署名されたコンプライアンス成果物	true	BAA / DPIA が整っています。保持ポリシーはログ保持と一致します。
マルチテナント SaaS、アップストリーム リダクションなし	false	絶対にダメです。リダクションを先に修正してください。
マルチテナント SaaS、アップストリーム リダクションあり	true	安全です。スパンは既にリダクションされたテキストを見ます。
法的サインオフなしのヘルスケア/金融/法務	false	絶対にダメです。

# 信頼できるシングルテナントのみ
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
export TRACELOOP_TRACE_CONTENT=true   # OpenLLMetry エイリアス; 安全性のため両方を設定

他の場所では設定しないままにしてください (デフォルト)。マルチテナント システムでボディをキャプチャするには、モデル呼び出しの前にアップストリーム リダクション ミドルウェアをワイアしてください。Prompt Content Policy を参照し、クロスリファレンスしてください。パック兄弟スキル langchain-security-basics (PII リダクション ミドルウェア パターン、P34) および langchain-middleware-patterns (ミドルウェア順序: リダクション → キャッシュ → モデル、P24)。P27 失敗パターン — キャプチャが選択されたことがないためトレースから欠落しているプロンプト — は、最初の日の OTEL 不満の第 1 位です。本番環境でフラグを意外にひっくり返すのではなく、意図的に決定を下してください。

ステップ 4 — コールバックをサブグラフを通じて伝播 (P28)

LangGraph はサブグラフごとに子ランタイムを作成します。定義時に親にバインドされたコールバックは 継承されません:

# 間違い — サブエージェント スパンは孤立しているか欠落している (P28)
agent = create_react_agent(model=llm, tools=tools).with_config(
    callbacks=[my_handler]  # 定義時にバインド; 子は見えない
)
agent.invoke({"messages": [...]})

# 正解 — invocation 時に config 経由でコールバックを渡す; 下まで伝播
agent.invoke(
    {"messages": [...]},
    config={"callbacks": [my_handler]}  # invocation 時; 子によって継承
)

同じルールが カスタム属性ハンドラー (例: セマンティック規約参照の CostAttributeHandler) にも適用されます。これは各モデル スパンに gen_ai.usage.cost_usd をスタンプします。config["callbacks"] 経由でアタッチしてください。.with_config() を経由しないでください。P28 失敗パターンの症状: SLO ダッシュボードは低レイテンシーを示しています。遅いネストされたスパンが完全に欠落しているため、ネストされた呼び出しが高速だからではありません。

ステップ 5 — LLM SLO とダッシュボードを定義

5 つの SLI が初日から重要です。5 つ全てが gen_ai.* スパン属性から派生します。2 番目のパイプラインは不要です:

SLI	ターゲット例	理由
p95 レイテンシ (トップレベル チャット)	チャット UI で < 5 s	プロバイダーの分散が支配的
p99 レイテンシ	< 15 s	チャット上の末尾が重要; ツール付きエージェントはここに存在
エラー率	< 0.5%	429 + finish_reason IN ("length","content_filter") を含む
リクエストあたりのコスト (p95)	< $0.05	haiku→opus の回帰をキャッチ
TTFT p95 (ストリーミング)	< 2 s	認識レイテンシ、総期間ではない

各 SLI の具体的な Honeycomb / PromQL / Datadog クエリ、およびマルチウィンドウ マルチバーンレート アラート (14.4× / 1h ファスト バーン、6× / 6h スロー バーン) は LLM SLO Dashboards にあります。

ステップ 6 — サンプリングを調整

デフォルトはボリューム スペクトラムの両端に対して間違っています:

from opentelemetry.sdk.trace.sampling import TraceIdRatioBased

# 低/中程度のボリューム — デバッグ性のためにすべてを保持
# (< ~100 req/s) — SDK デフォルト 100% で問題ありません

# 高ボリューム — ヘッド サンプル、ただしテール サンプリング経由でエラー + 遅いスパンを除外
# OTEL Collector で (references/llm-slo-dashboards.md を参照)
provider = TracerProvider(
    resource=resource,
    sampler=TraceIdRatioBased(0.10),  # 10% ヘッド サンプル
)

注意: 10% でのヘッド サンプリングは、p99 外れ値の 90% がバックエンドに到達する前に破棄されることを意味します。p99 メトリックスがノイズしくなり、中央値に偏ります。テール レイテンシ SLO の場合、tailsamplingprocessor を使用して Collector にサンプリングを移動し、エラーと遅いスパン (latency > 5000ms) は常に保持され、残りは 10% で確率的にサンプリングされます。BatchSpanProcessor での 512 スパン バッチ サイズでの典型的なトレース オーバーヘッド: スパンあたり 1 ms 未満。高ボリューム本番環境の推奨サンプリング レート: 1-10%。

出力

• 選択したバックエンド (Jaeger / Honeycomb / Tempo / Datadog) にワイアされた OTEL エクスポーター
• すべての LangChain および LangGraph スパンで gen_ai.* 属性を発行する opentelemetry-instrumentation-langchain
• ワークロード バケットに対して記録された明示的なプロンプト コンテンツ キャプチャ決定。マルチテナント ガードレール がアップストリームで適用される
• invocation 時に config["callbacks"] 経由で伝播されたコールバック。サブグラフ スパンが親ノードの下に正しくネストされる
• ダッシュボードと MWMBR バーンレート アラート付きの 5 つの LLM SLO (p95/p99 レイテンシ、エラー率、リクエストあたりのコスト、TTFT)
• ワークロード ボリュームと SLO 精度ニーズに一致するサンプリング戦略

エラー処理

症状	原因	修正
トレースは到着するがプロンプトと完了ボディが空	OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 未設定 (P27 — プライバシー安全デフォルト)	ステップ 3 のワークロード バケット のみ に対して true に設定してください。マルチテナントの場合、最初にアップストリーム リダクションをワイアしてください
サブグラフ / ツール呼び出しスパンが孤立しているか欠落している	定義時に .with_config() 経由でバインドされたコールバック (P28)	invocation 時に config["callbacks"] 経由で渡してください。子が継承するように
gen_ai.usage.cache_read_input_tokens が毎回リセット	コール単位の使用状況; 集計はあなたの仕事です (P04)	session.id によってキー設定されたコール全体を合計するカスタム コールバック。langchain-model-inference を参照してください
p99 ダッシュボードがノイズしく、中央値に偏っている	10% ヘッド サンプリングがバックエンド前に外れ値を削除	Collector tailsamplingprocessor に移動 — 常にエラーと latency > 5000ms を保持
トレースが表示されない	OTLPSpanExporter エンドポイント プロトコルが間違っている (4317 の gRPC と 4318 の HTTP)	curl -v $OTLP_ENDPOINT で確認。バックエンドが gRPC を期待する場合、proto-grpc エクスポーター パッケージに切り替えます
コスト属性がスパンから欠落している	LangChain 1.0 はネイティブに gen_ai.usage.cost_usd を発行しない	トークン × 価格から計算する BaseCallbackHandler を追加。セマンティック規約リファレンスを参照してください
PR レビュー がトレース属性の sk-... にフラグを立てている	gen_ai.prompt.content 経由でキャプチャされたプロンプト内のシークレット (P37 隣接)	アップストリーム リダクターはモデル呼び出し前に API キー パターンを削除する必要があります。0.1% サンプラー経由で監査してください
エクスポーターが黙ってスパンを削除	高ボリューム時のキュー オーバーフロー	max_queue_size を 4096+ に増加。SDK とバックエンド間に Collector を追加

例

開発ループ トレース用に Jaeger をローカルで実行

Docker で Jaeger をスピンアップし、SDK を http://localhost:4318/v1/traces にポイントします。コンテンツ キャプチャをオンのままにします (開発です。入力は合成です)。ジェネリック スパン ウォーターフォール が得られます。LLM 固有の UX はありませんが、インストルメンタが本番環境のバックエンド費用を払う前に何を発行するかを確認するのに適しています。

Backend Setup Matrix で docker run コマンドと SDK 設定を参照してください。

Honeycomb でエージェント レイテンシ インシデントを調査

Honeycomb の BubbleUp を gen_ai.request.model、gen_ai.usage.input_tokens、ツール呼び出し数の上で実行すると、「p95 が 14:00 でスパイクした」から「1 つの特定のツールが 20 s かかった。ベクトルストアが遅かったから」への最速パスです。デフォルトではコンテンツキャプチャオフにする必要があります。そうすれば、PII リーク心配なくチームを検索に出すことができます。

LLM SLO Dashboards で正確な Honeycomb クエリ形状を参照してください。

LangSmith → Tempo 移行中にデュアルエクスポート

2 つの BatchSpanProcessor を登録してください。1 つは LangSmith の OTLP エンドポイントへ、もう 1 つは Tempo へ。2 週間両方を実行し、ウォーターフォールを比較し、切り替えます。LangSmith は LLM 固有の分析を処理します。Tempo は Grafana スタックの LLM および非 LLM サービス全体の統一トレース検索を処理します。

Backend Setup Matrix デュアルエクスポート セクションを参照してください。

リソース

• OTEL GenAI semantic conventions
• OTEL Python SDK
• OpenLLMetry LangChain instrumentation
• Honeycomb OTLP ingest
• Grafana Tempo
• Datadog OTLP
• Google SRE — Alerting on SLOs
• パック クロスリファレンス: langchain-security-basics (リダクション、P34)、langchain-middleware-patterns (順序: リダクション → キャッシュ → モデル、P24)、langchain-model-inference (コスト コールバック パターン、P04)
• パック ペイン カタログ: docs/pain-catalog.md — P27 (コンテンツキャプチャ デフォルト)、P28 (サブグラフ コールバック伝播)、P04 (キャッシュ トークン集計)、P34 (プロンプト インジェクション)、P37 (環境/プロンプトのシークレット)