OpenTelemetryトレース

ElevenLabs Agentsでは、会話をOpenTelemetryトレースとして、OTLP JSON（resourceSpans）形式でエクスポートできます。Datadog、Grafana Tempo、Honeycomb、またはOTLPを取り込む任意のバックエンドに転送できます。

概要

トレースは3つの経路からエクスポートできます。いずれも会話ごとに同じトレースIDとelevenlabs.*属性名を共有します。スパンの形状とタイミングは、通話後／GET（文字起こしベース）とモニタリング（イベントベース）で異なります。

エクスポート経路

経路の選び方

• データウェアハウス内のすべての完了済み通話：通話後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ペイロード

{
  "type": "post_call_transcription_otel",
  "event_timestamp": 1700000000,
  "data": {
    "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
    "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
    "otlp_traces": {
      "resourceSpans": []
    }
  }
}

OpenTelemetry文字起こしを有効にする

配信

トレースの構造

各配信は、ルートスパンとその子スパンからなる完全な1つのトレースです。

elevenlabs.conversation
├── elevenlabs.recv.user_transcript
├── elevenlabs.recv.agent_response
│   └── elevenlabs.tool.{name}
└── ...

配信に推論サマリーが含まれる場合、エージェント応答スパンにはelevenlabs.reasoning_contentが含まれます。

タイミングは文字起こしのtime_in_call_secsと通話メタデータから取得されます。通話が通常のクライアント切断で終了しなかった場合、ルートスパンはelevenlabs.source = post_call_webhookおよびステータスERRORを設定します。

会話GET

会話を取得でOpenTelemetry形式をリクエストすると、通話後OpenTelemetry Webhookと同じotlp_tracesオブジェクトに加え、完全な会話モデルを取得できます。

GET /v1/convai/conversations/{conversation_id}?format=opentelemetry

CONVAI_READを持つAPIキーが必要です。format=json（デフォルト）では、otlp_tracesは省略されます。

{
  "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "status": "done",
  "transcript": [],
  "otlp_traces": {
    "resourceSpans": []
  }
}

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

想定されるスパン名には、elevenlabs.conversation、elevenlabs.recv.user_transcript、elevenlabs.recv.agent_responseが含まれます。

モニタリングWebSocket

会話の進行中に、OpenTelemetryトレースデータをOTLP JSONとしてストリーミングします。各メッセージは小さなresourceSpansバッチであり、通話終了時の単一トレースではありません。

wss://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/monitor?events_format=opentelemetry

認証にはCONVAI_WRITE、xi-api-key（またはAuthorization）、およびエージェントワークスペースのEDITORアクセスが必要です。会話開始後に接続してください。

セッションプロトコル

1. 認証ヘッダーを付けて接続します。
2. {"type": "connected"}を受信します。
3. ルートスパンバッチ（elevenlabs.conversation、elevenlabs.source = monitoring）を受信します。
4. キャッシュされた履歴（直近約100イベント）を受信後、{"type": "history_complete"}を受信します。
5. イベントの発生に応じてライブスパンバッチを受信します。

events_format=json（デフォルト）では、WebSocketはresourceSpansではなく生のクライアントイベントを返します。制御コマンドはリアルタイムモニタリングと同じです。

トレースの構造

elevenlabs.conversation
├── elevenlabs.turn.0
│   ├── elevenlabs.event.user_transcript
│   └── elevenlabs.tool.{name}
└── elevenlabs.turn.1

構造化イベントは専用属性にマッピングされます（例：elevenlabs.user.text、elevenlabs.agent.text）。不明なイベントでは、切り詰められたJSONを含むelevenlabs.event.dataが使用されます。

接続例

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 });
  }
});

OTLP JSON構造

すべての経路からのOpenTelemetryトレースは、同じOTLP 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
• リアルタイムモニタリング