オブザーバビリティ

OpenTelemetry による、すべてのエージェントインタラクションのトレース・メトリクス・ログ

オブザーバビリティが組み込まれている理由

エージェントはログを読むだけではデバッグが困難です。注目すべき振る舞いは、ネストされた LLM 呼び出し、ツールの実行、データベースとのやり取りの中にあるからです。Agent-Lab はオブザーバビリティを後付けの機能ではなく、フレームワークの機能として扱います。すべての HTTP リクエスト、モデル呼び出し、SQL クエリ、外部への HTTP 通信がスパンとなり、業界標準の OpenTelemetry でエクスポートされます（OpenLLMetry と OpenInference のセマンティック規約に準拠）。

エンドツーエンドで OTLP を使用しているため、コレクター互換のバックエンドであれば何でも利用できます。 Grafana スタック、Elastic、Langfuse、LangWatch、あるいは社内の既存の APM などです。

計装される対象

セットアップは agent_lab/infrastructure/metrics/tracer.py にあります。 OTEL_EXPORTER_OTLP_ENDPOINT を設定すると、以下が自動的にトレースされます。

インストルメンター	確認できる内容
FastAPI	リクエストごとに 1 つのサーバースパン（ルート、ステータス、所要時間を含む）
HTTPX	エージェントやサービスが行うすべての外部 HTTP 呼び出し
LangChain	トークン使用量を含む、すべての LLM／チェーンの呼び出し。エージェントのトレースの中核です
OpenAI	OpenAI ネイティブの呼び出し（OpenInference 規約）
SQLAlchemy	すべてのデータベースステートメント（リレーショナル、ベクトル検索、チェックポイント）

リソースの識別情報は SERVICE_NAME（デフォルトは Agent-Lab）と SERVICE_VERSION（デフォルトは snapshot）から取得されます。ノイズとなるパス（/status/*、/docs、 /openapi.json、favicon）は、カスタムサンプラーによって除外されます。

有効化する

コードの変更は不要で、エンドポイントを指定するだけです。 OTEL_EXPORTER_OTLP_ENDPOINT が設定されていると、スパンは OTLP/HTTP で <endpoint>/v1/traces、/v1/metrics、/v1/logs に送信されます。設定されていない場合、トレースは無効になります。

# Point the app at any OTLP/HTTP collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 uvicorn agent_lab.main:app --reload

ローカル開発では、事前設定済みの 2 つのスタックがすべての配線を行ってくれます（フレームワークのリポジトリから起動します）。

docker compose -f compose-grafana.yml up --build      # collector + Prometheus + Tempo + Loki + Grafana
docker compose -f compose-opensearch.yml up --build   # collector + Data Prepper + OpenSearch + Dashboards

各スタックには、それぞれ otel/grafana/ と otel/opensearch/ に独自の OpenTelemetry Collector の設定が同梱されています。これらのファイルが、トレース・メトリクス・ログのルーティング方法のリファレンスです。本番環境のトポロジーについてはデプロイガイドを参照してください。

LLM オブザーバビリティのバックエンド

Agent-Lab は素の OTel に加えて、TracingBackend 抽象化（agent_lab/core/container.py で DI プロバイダーとして配線）を通じて、専用の LLM オブザーバビリティプラットフォームとも連携します。同梱の 2 つのバックエンドはどちらも環境変数だけで有効化され、変数が欠けている場合は何も通知せずに自身を無効化するため、アプリは常に起動します。

Langfuse

Langfuse プロジェクトの 3 つの変数を設定すると、すべてのトレースが langfuse.trace.* 属性付きで Langfuse の OTLP エンドポイント（{LANGFUSE_HOST}/api/public/otel/v1/traces）にミラーリングされます。プロンプト、補完、トークン使用量、コストが記録され、そのままシミュレーション実験に利用できます。

変数	用途
`LANGFUSE_HOST`	Langfuse のベース URL
`LANGFUSE_PUBLIC_KEY`	`pk-lf-…`
`LANGFUSE_SECRET_KEY`	`sk-lf-…`

LangWatch

変数	用途
`LANGWATCH_ENDPOINT`	LangWatch のエンドポイント
`LANGWATCH_API_KEY`	LangWatch の API キー

LangWatch はメッセージごとに langwatch.trace() スパンを記録します。シミュレーションスイートはこの仕組みを使って、ジャッジのスコアを実験に紐づけて記録します。

リファレンスダッシュボード

スタック	ガイド	UI
Grafana + Prometheus + Tempo + Loki	otel/GRAFANA.md	http://localhost:3000
OpenSearch Dashboards	otel/OPENSEARCH.md	http://localhost:5601

どちらのガイドにも、ダッシュボードの動作を収録したデモ映像が含まれています。

拡張：独自のバックエンド

TracingBackend は公開 API の一部です。これをサブクラス化してスパンを独自のプラットフォームに転送し、 Container に登録します。

from agent_lab import Container, TracingBackend


class MyBackend(TracingBackend):
    ...  # export spans wherever your platform needs them


class MyContainer(Container):
    # replace or extend the shipped tracing_backends provider list
    ...

設定リファレンスには、オブザーバビリティ関連のすべての変数が 1 つの表にまとめられています。