> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # OpenTelemetryトレース ElevenLabs Agentsでは、会話を**OpenTelemetryトレース**として、**OTLP JSON**（`resourceSpans`）形式でエクスポートできます。Datadog、Grafana Tempo、Honeycomb、またはOTLPを取り込む任意のバックエンドに転送できます。 > **Info** > > ElevenLabsがトレースをOTLPコレクターへ直接プッシュすることはありません。Webhook、API、またはモニタリングWebSocketからOTLP形式のJSONを受け取り、バックエンドへ転送します。 ## 概要 トレースは3つの経路からエクスポートできます。いずれも会話ごとに同じ**トレースID**と`elevenlabs.*`属性名を共有します。スパンの形状とタイミングは、通話後／GET（文字起こしベース）とモニタリング（イベントベース）で異なります。 ### エクスポート経路 | 経路 | データを取得するタイミング | 最適な用途 | | --------------- | ---------------- | ----------------------- | | 通話後Webhook | 会話終了後、分析が完了した時点 | バッチパイプライン、請求・QA、永続ストレージ | | 会話取得API | 会話が作成された後、必要に応じて | バックフィル、デバッグ、再処理 | | モニタリングWebSocket | ライブ会話中 | ライブダッシュボード、アラート、人による介入 | ### 経路の選び方 * **データウェアハウス内のすべての完了済み通話**：通話後Webhook * **単発のエクスポートまたは修復**：`format=opentelemetry`を指定した会話GET * **ライブ監視UIまたはアラート**：モニタリングWebSocket * **事後に完全なタイムラインを取得**：通話後Webhookまたは会話GET * **ツール、MCP、ガードレールのイベントをリアルタイムで取得**：モニタリングWebSocket `traceId`または`elevenlabs.conversation_id`を使用して、経路をまたいでデータを結合できます。ライブ運用にはモニタリング、永続的な分析にはWebhook、バックフィルにはGETを組み合わせてください。 どの経路でも、OTLP対応のコレクターまたは可観測性ベンダーが必要です。通話後WebhookにはワークスペースのWebhookエンドポイントが必要です。GET APIとモニタリングWebSocketにはそれぞれ固有のAPIキースコープとセットアップが必要です。詳しくは以下のセクションを参照してください。 ## 通話後Webhook 会話が終了すると、通話後Webhookが設定され、`events`に`transcript`が含まれ、`transcript_format`が`opentelemetry`に設定されている場合、ElevenLabsは`POST`リクエストを送信します。 Webhookの`type`は`post_call_transcription_otel`です（JSON文字起こしを返す`post_call_transcription`ではありません）。 ### Webhookペイロード ```json { "type": "post_call_transcription_otel", "event_timestamp": 1700000000, "data": { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "otlp_traces": { "resourceSpans": [] } } } ``` ### OpenTelemetry文字起こしを有効にする #### ダッシュボードで設定 ### ワークスペースWebhookを作成 ElevenAgentsダッシュボードで、HTTPS URLと認証情報を指定してワークスペースWebhookを作成します。 ### 通話後Webhookを紐付ける [Agents設定](https://elevenlabs.io/app/agents/settings)を開き、Webhookを通話後Webhookとして割り当て、**Transcript**イベントを有効にして、**OpenTelemetry transcript payloads**をオンにします。 ![通話後Webhook設定](/docs/_fern-img/eb5d768612d6461a21bc3127611f60724be3e1a55005af43faf48f2d7bf23807.webp) #### CLIで設定 > **Note** > > ワークスペース全体の通話後Webhookは、ダッシュボードまたはAPIタブで設定します。CLIを使用すると、特定のエージェントのWebhook設定を上書きできます。 ### エージェント設定を取得 ```bash elevenlabs agents pull --agent "" ``` ### `agent_configs/.json`を編集 `platform_settings.workspace_overrides.webhooks`を設定します。 ```json { "platform_settings": { "workspace_overrides": { "webhooks": { "post_call_webhook_id": "wh_01jqz7x8y9z0a1b2c3d4e5f6", "events": ["transcript"], "transcript_format": "opentelemetry" } } } } ``` ### 変更をプッシュ ```bash elevenlabs agents push --agent "" ``` #### APIで設定 **`Python`** ```python title="Python" import os from dotenv import load_dotenv from elevenlabs import ElevenLabs load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) elevenlabs.conversational_ai.settings.update( webhooks={ "post_call_webhook_id": "wh_01jqz7x8y9z0a1b2c3d4e5f6", "events": ["transcript"], "transcript_format": "opentelemetry", }, ) ``` **`TypeScript`** ```typescript title="TypeScript" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY, }); await elevenlabs.conversationalAi.settings.update({ webhooks: { postCallWebhookId: "wh_01jqz7x8y9z0a1b2c3d4e5f6", events: ["transcript"], transcriptFormat: "opentelemetry", }, }); ``` 単一のエージェントの場合は、[エージェントを更新](/docs/ja/api-reference/agents/update)で`platform_settings.workspace_overrides`の下に同じ`webhooks`オブジェクトを渡します。 > **Warning** > > OpenTelemetry文字起こしWebhookにはオーディオは含まれません。録音が必要な場合は`post_call_audio`を使用してください。 > > 成功時は**2xx**を返します。**4xx**と**5xx**は失敗として扱われます。 > > 文字起こし（OpenTelemetryを含む）とオーディオWebhookの再試行は、ワークスペースWebhookで**Enable retries**がオンの場合にのみ適用されます。一時的なエラー（**5xx**、**429**、**408**）は最大5回再試行されます。**4xx**は再試行されません。失敗が繰り返されるとWebhookが自動的に無効になる場合があります。詳細とHIPAAの例外については、[通話後Webhook](/docs/ja/eleven-agents/workflows/post-call-webhooks)を参照してください。 ### 配信 | トピック | 詳細 | | ---- | ------------------------------------------------------------------ | | メソッド | JSONボディを含む`POST` | | 認証 | `{timestamp}.{body}`に対する`ElevenLabs-Signature: t={unix},v0={hmac}` | | 再試行 | Webhookで**Enable retries**を有効にする必要があります。上記の警告を参照してください | | サイズ | 長いツールパラメータと結果は、スパン属性ごとに4 KBで切り詰められます | ### トレースの構造 各配信は、ルートスパンとその子スパンからなる完全な1つのトレースです。 ```text elevenlabs.conversation ├── elevenlabs.recv.user_transcript ├── elevenlabs.recv.agent_response │ └── elevenlabs.tool.{name} └── ... ``` 配信に[推論サマリー](/docs/ja/eleven-agents/customization/llm#reasoning-summary)が含まれる場合、エージェント応答スパンには`elevenlabs.reasoning_content`が含まれます。 タイミングは文字起こしの`time_in_call_secs`と通話メタデータから取得されます。通話が通常のクライアント切断で終了しなかった場合、ルートスパンは`elevenlabs.source` = `post_call_webhook`およびステータス`ERROR`を設定します。 ## 会話GET [会話を取得](/docs/ja/api-reference/conversations/get)でOpenTelemetry形式をリクエストすると、通話後OpenTelemetry Webhookと同じ`otlp_traces`オブジェクトに加え、完全な会話モデルを取得できます。 ```http GET /v1/convai/conversations/{conversation_id}?format=opentelemetry ``` `CONVAI_READ`を持つAPIキーが必要です。`format=json`（デフォルト）では、`otlp_traces`は省略されます。 ```json { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "status": "done", "transcript": [], "otlp_traces": { "resourceSpans": [] } } ``` | トピック | 詳細 | | ------- | ----------------------------------------- | | タイミング | 通話後Webhookと同じ文字起こしベースのビルダー | | 文字起こし | `transcript`は引き続き返され、`otlp_traces`が追加されます | | ファイルURL | スパン属性内の署名付きURLは約15分後に期限切れになります | **`Python`** ```python title="Python" import os from dotenv import load_dotenv from elevenlabs import ElevenLabs load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) conversation = elevenlabs.conversational_ai.conversations.get( conversation_id="conv_9001k1zph3fkeh5s8xg9z90swaqa", format="opentelemetry", ) otlp_traces = conversation.otlp_traces ``` **`TypeScript`** ```typescript title="TypeScript" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY, }); const conversation = await elevenlabs.conversationalAi.conversations.get({ conversationId: "conv_9001k1zph3fkeh5s8xg9z90swaqa", format: "opentelemetry", }); const otlpTraces = conversation.otlpTraces; ``` **`cURL`** ```bash title="cURL" curl -s "https://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa?format=opentelemetry" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ | jq '.otlp_traces.resourceSpans[0].scopeSpans[0].spans[].name' ``` 想定されるスパン名には、`elevenlabs.conversation`、`elevenlabs.recv.user_transcript`、`elevenlabs.recv.agent_response`が含まれます。 ## モニタリングWebSocket > **Note** > > リアルタイムモニタリングには、エンタープライズワークスペースまたは`realtime-monitoring`機能フラグが必要です。設定、制御コマンド、アクセス要件については、[リアルタイムモニタリング](/docs/ja/eleven-agents/guides/realtime-monitoring)を参照してください。 会話の進行中に、OpenTelemetryトレースデータをOTLP JSONとしてストリーミングします。各メッセージは小さな`resourceSpans`バッチであり、通話終了時の単一トレースではありません。 ``` wss://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/monitor?events_format=opentelemetry ``` 認証には`CONVAI_WRITE`、`xi-api-key`（または`Authorization`）、およびエージェントワークスペースの**EDITOR**アクセスが必要です。会話開始後に接続してください。 ### エージェントでモニタリングを有効にする 通話前に`monitoring_enabled: true`を設定し、`monitoring_events`を構成します。[リアルタイムモニタリング](/docs/ja/eleven-agents/guides/realtime-monitoring#configuration)を参照してください。 ### OpenTelemetry形式で接続 モニタリングWebSocket URLに`events_format=opentelemetry`を追加します。 > **Warning** > > カスタム`monitoring_events`が設定されている場合、VAD、ターン確率、pingイベントは利用できません。ストリームには生オーディオではなく、テキストとメタデータのみが含まれます。 ### セッションプロトコル 1. 認証ヘッダーを付けて接続します。 2. `{"type": "connected"}`を受信します。 3. ルートスパンバッチ（`elevenlabs.conversation`、`elevenlabs.source` = `monitoring`）を受信します。 4. キャッシュされた履歴（直近約100イベント）を受信後、`{"type": "history_complete"}`を受信します。 5. イベントの発生に応じてライブスパンバッチを受信します。 `events_format=json`（デフォルト）では、WebSocketは`resourceSpans`ではなく生のクライアントイベントを返します。制御コマンドは[リアルタイムモニタリング](/docs/ja/eleven-agents/guides/realtime-monitoring#control-commands)と同じです。 ### トレースの構造 ```text elevenlabs.conversation ├── elevenlabs.turn.0 │ ├── elevenlabs.event.user_transcript │ └── elevenlabs.tool.{name} └── elevenlabs.turn.1 ``` | 項目 | 通話後とGET | モニタリング | | --------- | ----------------------- | ------------------------- | | 粒度 | Webhookまたはリクエストごとに1トレース | 会話ごとに複数メッセージ | | イベントスパン | 文字起こしのターン | `elevenlabs.event.{type}` | | ターンのグループ化 | 文字起こし順に暗黙的 | 明示的な`elevenlabs.turn.N` | | 順序 | 安定した文字起こし順 | イベントは厳密な時系列順で届かない場合があります | 構造化イベントは専用属性にマッピングされます（例：`elevenlabs.user.text`、`elevenlabs.agent.text`）。不明なイベントでは、切り詰められたJSONを含む`elevenlabs.event.data`が使用されます。 > **Info** > > イベント順序が発話順序と一致するとは限りません。同じ`traceId`を使用して、ライブスパンと通話後データを関連付けてください。 ### 接続例 **`TypeScript`** ```typescript title="TypeScript" import WebSocket from "ws"; const ws = new WebSocket( "wss://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa/monitor?events_format=opentelemetry", { headers: { "xi-api-key": process.env.ELEVENLABS_API_KEY!, }, } ); ws.on("message", (raw) => { const msg = JSON.parse(raw.toString()); if (msg.type === "connected" || msg.type === "history_complete") return; if (msg.resourceSpans) { forwardToCollector({ resourceSpans: msg.resourceSpans }); } }); ``` **`Python`** ```python title="Python" import asyncio import json import os import websockets from dotenv import load_dotenv load_dotenv() async def monitor_opentelemetry(): uri = ( "wss://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa/monitor" "?events_format=opentelemetry" ) headers = {"xi-api-key": os.getenv("ELEVENLABS_API_KEY")} async with websockets.connect(uri, extra_headers=headers) as ws: async for raw in ws: msg = json.loads(raw) if msg.get("type") in ("connected", "history_complete"): continue if msg.get("resourceSpans"): forward_to_collector({"resourceSpans": msg["resourceSpans"]}) asyncio.run(monitor_opentelemetry()) ``` ## OTLP JSON構造 すべての経路からのOpenTelemetryトレースは、同じOTLP JSONバッチレイアウトを共有します。 ```json { "resourceSpans": [ { "resource": { "attributes": [ { "key": "service.name", "value": { "stringValue": "elevenlabs-convai" } }, { "key": "elevenlabs.conversation_id", "value": { "stringValue": "conv_9001k1zph3fkeh5s8xg9z90swaqa" } } ] }, "scopeSpans": [ { "scope": { "name": "elevenlabs.convai", "version": "1.0.0" }, "spans": [ { "traceId": "32_hex_chars", "spanId": "16_hex_chars", "name": "elevenlabs.recv.agent_response", "startTimeUnixNano": "1700000000000000000", "endTimeUnixNano": "1700000001000000000", "status": { "code": 1 } } ] } ] } ] } ``` ## 制限事項 * OTLP gRPCエンドポイントへの直接プッシュには対応していません。 * ペイロードはOTLPエクスポート形式のJSONであり、ワイヤ上の生protobufではありません。 ## 関連ドキュメント * [通話後Webhook](/docs/ja/eleven-agents/workflows/post-call-webhooks) * [リアルタイムモニタリング](/docs/ja/eleven-agents/guides/realtime-monitoring)