OpenTelemetry-traces

ElevenLabs Agents kan gesprekken exporteren als OpenTelemetry-traces, gecodeerd als OTLP JSON (resourceSpans). Stuur ze door naar Datadog, Grafana Tempo, Honeycomb of een andere backend die OTLP verwerkt.

Overzicht

Exporteer traces via drie manieren. Alle drie gebruiken dezelfde trace-ID per gesprek en de naamgeving voor attributen elevenlabs.*. De vorm en timing van spans verschillen tussen na het gesprek/GET (op basis van het transcript) en monitoring (op basis van gebeurtenissen).

Exportmethoden

Een methode kiezen

• Elk voltooid gesprek in je datawarehouse: webhook na gesprek
• Eenmalige export of herstel: GET conversation met format=opentelemetry
• Live supervisor-UI of waarschuwingen: monitoring-WebSocket
• Tijdlijn met volledige details achteraf: webhook na gesprek of GET conversation
• Tool-, MCP- of guardrail-gebeurtenissen op het moment dat ze plaatsvinden: monitoring-WebSocket

Gebruik traceId of elevenlabs.conversation_id om gegevens van verschillende methoden te koppelen. Combineer monitoring voor live activiteiten, webhooks voor duurzame analyses en GET voor backfill.

Voor elke methode heb je een OTLP-compatibele collector of observability-provider nodig. Webhooks na gesprekken vereisen een webhookendpoint voor de workspace. De GET API en monitoring-WebSocket hebben elk hun eigen API-keyscopes en configuratie; zie de onderstaande secties.

Webhook na gesprek

Nadat een gesprek is afgerond, verstuurt ElevenLabs een POST-request wanneer een webhook na het gesprek is geconfigureerd, events transcript bevat en transcript_format is ingesteld op opentelemetry.

Het webhook-type is post_call_transcription_otel (niet post_call_transcription, dat JSON-transcripten retourneert).

Webhookpayload

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

OpenTelemetry-transcripten inschakelen

Bezorgen

Tracevorm

Elke levering is één volledige trace: een root span met onderliggende spans.

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

Spans voor agentreacties bevatten elevenlabs.reasoning_content wanneer de levering een redeneersamenvatting bevat.

De timing is gebaseerd op time_in_call_secs van het transcript en gespreksmetadata. De root span stelt elevenlabs.source in op post_call_webhook en de status op ERROR wanneer het gesprek niet eindigde met een normale clientverbinding die werd verbroken.

GET conversation

Vraag OpenTelemetry-indeling aan via Get conversation om hetzelfde otlp_traces-object te ontvangen als via de OpenTelemetry-webhook na het gesprek, plus het volledige gespreksmodel.

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

Hiervoor heb je een API-sleutel met CONVAI_READ nodig. Met format=json (standaard) wordt otlp_traces weggelaten.

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

Verwachte spannamen zijn onder meer elevenlabs.conversation, elevenlabs.recv.user_transcript en elevenlabs.recv.agent_response.

Monitoring-WebSocket

Stream OpenTelemetry-tracegegevens als OTLP JSON terwijl een gesprek bezig is. Elk bericht is een kleine batch resourceSpans, geen enkele trace aan het einde van een gesprek.

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

Authenticatie vereist CONVAI_WRITE, xi-api-key (of Authorization) en EDITOR-toegang tot de workspace van de agent. Maak verbinding nadat het gesprek is gestart.

Sessieprotocol

1. Maak verbinding met authenticatieheaders.
2. Ontvang {"type": "connected"}.
3. Ontvang een root-spanbatch (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Ontvang de gecachte geschiedenis (ongeveer de laatste 100 gebeurtenissen), gevolgd door {"type": "history_complete"}.
5. Ontvang live spanbatches wanneer gebeurtenissen plaatsvinden.

Met events_format=json (standaard) retourneert de WebSocket onbewerkte clientgebeurtenissen in plaats van resourceSpans. Besturingscommando’s komen overeen met Realtime monitoring.

Tracevorm

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

Gestructureerde gebeurtenissen worden gekoppeld aan specifieke attributen (bijvoorbeeld elevenlabs.user.text, elevenlabs.agent.text). Onbekende gebeurtenissen gebruiken elevenlabs.event.data met afgekapt JSON.

Voorbeeldverbinding

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

OpenTelemetry-traces van alle methoden gebruiken dezelfde OTLP JSON-batchindeling:

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

Beperkingen

• Geen rechtstreekse verzending naar je OTLP gRPC-endpoint.
• Payloads zijn JSON in de vorm van OTLP-export, niet onbewerkte protobuf via de verbinding.

Gerelateerde documentatie

• Webhooks na gesprekken
• Realtime monitoring