OpenTelemetry-Traces

ElevenLabs Agents können Gespräche als OpenTelemetry-Traces exportieren, die als OTLP-JSON (resourceSpans) kodiert sind. Leiten Sie sie an Datadog, Grafana Tempo, Honeycomb oder ein beliebiges Backend weiter, das OTLP aufnimmt.

Übersicht

Exportieren Sie Traces über drei Schnittstellen. Alle drei verwenden dieselbe Trace-ID pro Gespräch und die Attributbenennung elevenlabs.*. Die Struktur und das Timing der Spans unterscheiden sich zwischen Post-Call/GET (transkriptbasiert) und Monitoring (ereignisbasiert).

Exportschnittstellen

Auswahl einer Schnittstelle

• Jeder abgeschlossene Anruf in Ihrem Data Warehouse: Post-Call-Webhook
• Einmaliger Export oder Korrektur: GET Conversation mit format=opentelemetry
• Live-Supervisor-UI oder Warnmeldungen: Monitoring-WebSocket
• Vollständige Zeitachse im Nachhinein: Post-Call-Webhook oder GET Conversation
• Tool-, MCP- oder Guardrail-Ereignisse in Echtzeit: Monitoring-WebSocket

Verwenden Sie traceId oder elevenlabs.conversation_id, um Daten über Schnittstellen hinweg zu verknüpfen. Kombinieren Sie Monitoring für Live-Betrieb, Webhooks für dauerhafte Analysen und GET für Backfill.

Für jede Schnittstelle benötigen Sie einen OTLP-fähigen Collector oder Observability-Anbieter. Post-Call-Webhooks erfordern einen Workspace-Webhook-Endpunkt. Die GET API und der Monitoring-WebSocket haben jeweils eigene API-Key-Berechtigungen und Einstellungen. Weitere Informationen finden Sie in den folgenden Abschnitten.

Post-Call-Webhook

Nach Abschluss eines Gesprächs sendet ElevenLabs eine POST-Anfrage, wenn ein Post-Call-Webhook konfiguriert ist, events den Wert transcript enthält und transcript_format auf opentelemetry gesetzt ist.

Der Webhook-type lautet post_call_transcription_otel (nicht post_call_transcription, das JSON-Transkripte zurückgibt).

Webhook-Payload

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

OpenTelemetry-Transkripte aktivieren

Zustellung

Trace-Struktur

Jede Zustellung ist ein vollständiger Trace: ein Root-Span plus untergeordnete Spans.

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

Agentenantwort-Spans enthalten elevenlabs.reasoning_content, wenn die Zustellung eine Reasoning-Zusammenfassung enthält.

Das Timing basiert auf time_in_call_secs des Transkripts und Anrufmetadaten. Der Root-Span setzt elevenlabs.source = post_call_webhook und den Status ERROR, wenn der Anruf nicht mit einer normalen Client-Trennung endete.

GET Conversation

Fordern Sie das OpenTelemetry-Format bei Get conversation an, um dasselbe otlp_traces-Objekt wie beim OpenTelemetry-Post-Call-Webhook sowie das vollständige Gesprächsmodell zu erhalten.

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

Erfordert einen API-Key mit CONVAI_READ. Mit format=json (Standard) wird otlp_traces ausgelassen.

{
  "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

Erwartete Span-Namen sind unter anderem elevenlabs.conversation, elevenlabs.recv.user_transcript und elevenlabs.recv.agent_response.

Monitoring-WebSocket

Streamen Sie OpenTelemetry-Trace-Daten als OTLP-JSON, während ein Gespräch läuft. Jede Nachricht ist ein kleiner resourceSpans-Batch und kein einzelner Trace am Ende des Anrufs.

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

Für die Authentifizierung sind CONVAI_WRITE, xi-api-key (oder Authorization) und EDITOR-Zugriff auf den Agenten-Workspace erforderlich. Stellen Sie die Verbindung her, nachdem das Gespräch gestartet ist.

Sitzungsprotokoll

1. Stellen Sie die Verbindung mit Authentifizierungs-Headern her.
2. Empfangen Sie {"type": "connected"}.
3. Empfangen Sie einen Root-Span-Batch (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Empfangen Sie den zwischengespeicherten Verlauf (etwa die letzten 100 Ereignisse), dann {"type": "history_complete"}.
5. Empfangen Sie Live-Span-Batches, sobald Ereignisse auftreten.

Mit events_format=json (Standard) gibt der WebSocket rohe Client-Ereignisse statt resourceSpans zurück. Steuerbefehle entsprechen Echtzeit-Monitoring.

Trace-Struktur

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

Strukturierte Ereignisse werden speziellen Attributen zugeordnet (zum Beispiel elevenlabs.user.text, elevenlabs.agent.text). Unbekannte Ereignisse verwenden elevenlabs.event.data mit gekürztem JSON.

Beispielverbindung

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-Struktur

OpenTelemetry-Traces aller Schnittstellen verwenden dasselbe OTLP-JSON-Batch-Layout:

{
  "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 }
            }
          ]
        }
      ]
    }
  ]
}

Einschränkungen

• Kein direkter Push an Ihren OTLP-gRPC-Endpunkt.
• Payloads sind JSON im OTLP-Exportformat, nicht rohe Protobuf-Daten bei der Übertragung.

Zugehörige Dokumentation

• Post-Call-Webhooks
• Echtzeit-Monitoring