> 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-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. > **Info** > > ElevenLabs überträgt Traces nicht direkt an Ihren OTLP-Collector. Sie erhalten JSON im OTLP-Format über > einen Webhook, eine API oder einen Monitoring-WebSocket und leiten es an Ihr Backend weiter. ## Ü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 | Schnittstelle | Wann Sie Daten erhalten | Geeignet für | | -------------------- | ---------------------------------------------- | ---------------------------------------------------------- | | Post-Call-Webhook | Nach Gesprächsende und abgeschlossener Analyse | Batch-Pipelines, Abrechnung und QA, dauerhafte Speicherung | | GET Conversation API | Bei Bedarf, nachdem das Gespräch existiert | Backfill, Debugging, erneute Verarbeitung | | Monitoring-WebSocket | Während eines laufenden Gesprächs | Live-Dashboards, Warnmeldungen, Human-in-the-Loop | ### 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 ```json { "type": "post_call_transcription_otel", "event_timestamp": 1700000000, "data": { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "otlp_traces": { "resourceSpans": [] } } } ``` ### OpenTelemetry-Transkripte aktivieren #### Über das Dashboard konfigurieren ### Workspace-Webhook erstellen Erstellen Sie im ElevenAgents Dashboard einen Workspace-Webhook mit Ihrer HTTPS-URL und Authentifizierung. ### Post-Call-Webhook zuweisen Öffnen Sie die [Agent-Einstellungen](https://elevenlabs.io/app/agents/settings), weisen Sie den Webhook als Post-Call-Webhook zu, aktivieren Sie das Ereignis **Transcript** und schalten Sie **OpenTelemetry-Transkript-Payloads** ein. ![Post-Call-Webhook-Einstellungen](/docs/_fern-img/eb5d768612d6461a21bc3127611f60724be3e1a55005af43faf48f2d7bf23807.webp) #### Über die CLI konfigurieren > **Note** > > Workspace-weite Post-Call-Webhooks werden im Dashboard oder über den API-Tab konfiguriert. Verwenden Sie die CLI, um > Webhook-Einstellungen für einen bestimmten Agenten zu überschreiben. ### Agentenkonfiguration abrufen ```bash elevenlabs agents pull --agent "" ``` ### `agent_configs/.json` bearbeiten Setzen Sie `platform_settings.workspace_overrides.webhooks`: ```json { "platform_settings": { "workspace_overrides": { "webhooks": { "post_call_webhook_id": "wh_01jqz7x8y9z0a1b2c3d4e5f6", "events": ["transcript"], "transcript_format": "opentelemetry" } } } } ``` ### Änderungen übertragen ```bash elevenlabs agents push --agent "" ``` #### Über die API konfigurieren **`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", }, }); ``` Übergeben Sie für einen einzelnen Agenten dasselbe `webhooks`-Objekt unter `platform_settings.workspace_overrides` in [Agent aktualisieren](/docs/de/api-reference/agents/update). > **Warning** > > OpenTelemetry-Transkript-Webhooks enthalten kein Audio. Verwenden Sie `post_call_audio`, wenn Sie > Aufzeichnungen benötigen. > > Geben Sie für Erfolg **2xx** zurück. **4xx** und **5xx** gelten als Fehler. > > Wiederholungen gelten für Transkript-Webhooks (einschließlich OpenTelemetry) und Audio-Webhooks nur, wenn **Wiederholungen > aktivieren** für den Workspace-Webhook eingeschaltet ist. Vorübergehende Fehler (\*\* 5xx \*\*, \*\*429 \*\*, \*\*408 \*\*) werden bis zu > 5-mal wiederholt; **4xx** nicht. Wiederholte Fehler können den Webhook automatisch deaktivieren. Details und HIPAA- > Ausnahmen finden Sie unter [Post-Call-Webhooks](/docs/de/eleven-agents/workflows/post-call-webhooks). ### Zustellung | Thema | Details | | -------------- | ------------------------------------------------------------------------------ | | Methode | `POST` mit JSON-Body | | Auth | `ElevenLabs-Signature: t={unix},v0={hmac}` über `{timestamp}.{body}` | | Wiederholungen | Erfordert **Wiederholungen aktivieren** für den Webhook; siehe obige Warnung | | Größe | Lange Tool-Parameter und -Ergebnisse werden bei 4 KB pro Span-Attribut gekürzt | ### Trace-Struktur Jede Zustellung ist ein vollständiger Trace: ein Root-Span plus untergeordnete Spans. ```text 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](/docs/de/eleven-agents/customization/llm#reasoning-summary) 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](/docs/de/api-reference/conversations/get) an, um dasselbe `otlp_traces`-Objekt wie beim OpenTelemetry-Post-Call-Webhook sowie das vollständige Gesprächsmodell zu erhalten. ```http GET /v1/convai/conversations/{conversation_id}?format=opentelemetry ``` Erfordert einen API-Key mit `CONVAI_READ`. Mit `format=json` (Standard) wird `otlp_traces` ausgelassen. ```json { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "status": "done", "transcript": [], "otlp_traces": { "resourceSpans": [] } } ``` | Thema | Details | | ---------- | --------------------------------------------------------------------------------------- | | Timing | Derselbe transkriptbasierte Builder wie beim Post-Call-Webhook | | Transkript | `transcript` wird weiterhin zurückgegeben; `otlp_traces` wird zusätzlich bereitgestellt | | Datei-URLs | Signierte URLs in Span-Attributen laufen nach etwa 15 Minuten ab | **`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' ``` Erwartete Span-Namen sind unter anderem `elevenlabs.conversation`, `elevenlabs.recv.user_transcript` und `elevenlabs.recv.agent_response`. ## Monitoring-WebSocket > **Note** > > Echtzeit-Monitoring erfordert einen Enterprise-Workspace oder das Feature-Flag `realtime-monitoring`. > Konfiguration, Steuerbefehle und Zugriffsanforderungen finden Sie unter [Echtzeit-Monitoring](/docs/de/eleven-agents/guides/realtime-monitoring). 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. ### Monitoring für den Agenten aktivieren Setzen Sie vor dem Anruf `monitoring_enabled: true` und konfigurieren Sie `monitoring_events`. Siehe [Echtzeit-Monitoring](/docs/de/eleven-agents/guides/realtime-monitoring#configuration). ### Mit OpenTelemetry-Format verbinden Hängen Sie `events_format=opentelemetry` an die Monitoring-WebSocket-URL an. > **Warning** > > VAD-, Turn-Probability- und Ping-Ereignisse sind nicht verfügbar, wenn benutzerdefinierte `monitoring_events` > konfiguriert sind. Der Stream enthält nur Text und Metadaten, kein Roh-Audio. ### 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](/docs/de/eleven-agents/guides/realtime-monitoring#control-commands). ### Trace-Struktur ```text elevenlabs.conversation ├── elevenlabs.turn.0 │ ├── elevenlabs.event.user_transcript │ └── elevenlabs.tool.{name} └── elevenlabs.turn.1 ``` | Aspekt | Post-Call und GET | Monitoring | | ---------------- | ------------------------------------- | ------------------------------------------------------------------------------- | | Granularität | Ein Trace pro Webhook oder Anfrage | Viele Nachrichten pro Gespräch | | Ereignis-Spans | Transkript-Turns | `elevenlabs.event.{type}` | | Turn-Gruppierung | Implizit in der Transkriptreihenfolge | Explizit `elevenlabs.turn.N` | | Reihenfolge | Stabile Transkriptreihenfolge | Ereignisse können außerhalb der strikten chronologischen Reihenfolge eintreffen | Strukturierte Ereignisse werden speziellen Attributen zugeordnet (zum Beispiel `elevenlabs.user.text`, `elevenlabs.agent.text`). Unbekannte Ereignisse verwenden `elevenlabs.event.data` mit gekürztem JSON. > **Info** > > Gehen Sie nicht davon aus, dass die Ereignisreihenfolge der Sprechreihenfolge entspricht. Korrelieren Sie Live-Spans mit Post-Call-Daten über > dieselbe `traceId`. ### Beispielverbindung **`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-Struktur OpenTelemetry-Traces aller Schnittstellen verwenden dasselbe OTLP-JSON-Batch-Layout: ```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 } } ] } ] } ] } ``` ## 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](/docs/de/eleven-agents/workflows/post-call-webhooks) * [Echtzeit-Monitoring](/docs/de/eleven-agents/guides/realtime-monitoring)