Hoppa till navigering

OpenTelemetry-spår

Exportera OpenTelemetry-spår till din observability-stack som OTLP JSON.

ElevenLabs Agents kan exportera konversationer som OpenTelemetry-spår kodade som OTLP JSON (resourceSpans). Vidarebefordra dem till Datadog, Grafana Tempo, Honeycomb eller valfri backend som importerar OTLP.

ElevenLabs skickar inte spår direkt till din OTLP-insamlare. Du får OTLP-formad JSON från en webhook, API eller övervaknings-WebSocket och vidarebefordrar den till din backend.

Översikt

Exportera spår från tre källor. Alla tre delar samma spår-ID per konversation och attributnamngivningen elevenlabs.*. Spannens utformning och tidssättning skiljer sig mellan efter samtal/GET (transkriptbaserat) och övervakning (händelsebaserat).

Exportkällor

KällaNär du får dataPassar bäst för
Webhook efter samtalNär konversationen slutar och analysen är klarBatchpipelines, fakturering och QA, beständig lagring
GET conversation APIVid behov, efter att konversationen har skapatsÅterfyllning, felsökning, ombearbetning
Övervaknings-WebSocketUnder en aktiv konversationLiveinstrumentpaneler, aviseringar, människa i loopen

Välja en källa

  • Varje slutfört samtal i ditt datalager: webhook efter samtal
  • Enstaka export eller reparation: GET conversation med format=opentelemetry
  • Livegränssnitt för handledare eller aviseringar: övervaknings-WebSocket
  • Tidslinje med full detaljnivå i efterhand: webhook efter samtal eller GET conversation
  • Verktygs-, MCP- eller guardrail-händelser när de inträffar: övervaknings-WebSocket

Använd traceId eller elevenlabs.conversation_id för att sammanfoga data mellan källor. Kombinera övervakning för liveåtgärder, webhooks för varaktig analys och GET för återfyllning.

Du behöver en OTLP-kompatibel insamlare eller observability-leverantör för varje källa. Webhooks efter samtal kräver en webhook-slutpunkt för arbetsytan. GET API och övervaknings-WebSocket har egna API-nyckelomfattningar och egen konfiguration. Se avsnitten nedan.

Webhook efter samtal

När en konversation avslutas skickar ElevenLabs en POST-begäran när en webhook efter samtal har konfigurerats, events innehåller transcript och transcript_format är opentelemetry.

Webhookens type är post_call_transcription_otel (inte post_call_transcription, som returnerar JSON-transkript).

Webhook-payload

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

Aktivera OpenTelemetry-transkript

1

Skapa en webhook för arbetsytan

I ElevenAgents Dashboard skapar du en webhook för arbetsytan med din HTTPS-URL och autentisering.

2

Koppla webhooken efter samtal

Öppna Agents settings, tilldela webhooken som webhook efter samtal, aktivera händelsen Transcript och slå på OpenTelemetry transcript payloads.

Inställningar för webhook efter samtal

OpenTelemetry-transkriptwebhooks innehåller inte ljud. Använd post_call_audio om du behöver inspelningar.

Returnera 2xx vid lyckat resultat. 4xx och 5xx räknas som fel.

Återförsök gäller endast transkriptwebhooks (inklusive OpenTelemetry) och ljudwebhooks när Enable retries är aktiverat för webhooken för arbetsytan. Tillfälliga fel (** 5xx **, **429 **, **408 **) försöks igen upp till 5 gånger; 4xx gör det inte. Upprepade fel kan automatiskt inaktivera webhooken. Se Post-call webhooks för detaljer och HIPAA- undantag.

Leverans

ÄmneDetalj
MetodPOST med JSON-brödtext
AutentiseringElevenLabs-Signature: t={unix},v0={hmac} över {timestamp}.{body}
ÅterförsökKräver Enable retries på webhooken; se varningen ovan
StorlekLånga verktygsparametrar och resultat trunkeras vid 4 KB per spannattribut

Spårstruktur

Varje leverans är ett komplett spår: ett rotspann plus underordnade spann.

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

Spann för agentsvar innehåller elevenlabs.reasoning_content när leveransen innehåller en sammanfattning av resonemang.

Tidssättningen kommer från transkriptets time_in_call_secs och samtalsmetadata:

  • Rotspannet omfattar hela samtalet, från start_time_unix_secs under call_duration_secs.
  • Varje transkriptspann börjar vid dess time_in_call_secs och slutar när nästa transkriptpost börjar. Det sista slutar med samtalet.
  • Ett verktygsspann börjar med sitt transkriptspann och varar under verktygets latens, när latensen är känd.

Rotspannet anger elevenlabs.source = post_call_webhook. Dess status är ERROR när konversationsstatusen är failed eller samtalsmetadata registrerar ett fel, och status.message innehåller felorsaken när en sådan finns. Se Attributreferens för alla attribut.

GET conversation

Begär OpenTelemetry-format i Get conversation för att få samma otlp_traces-objekt som i OpenTelemetry-webhooken efter samtal, plus hela konversationsmodellen.

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

Kräver en API-nyckel med CONVAI_READ. Med format=json (standard) utelämnas otlp_traces.

{
"conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
"agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
"status": "done",
"transcript": [],
"otlp_traces": {
"resourceSpans": []
}
}
ÄmneDetalj
TidssättningSamma transkriptbaserade byggare som webhooken efter samtal
Transkripttranscript returneras fortfarande; otlp_traces är ett tillägg
Fil-URL:erSignerade URL:er i spannattribut upphör efter cirka 15 minuter
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

Förväntade spannnamn är bland annat elevenlabs.conversation, elevenlabs.recv.user_transcript och elevenlabs.recv.agent_response.

Övervaknings-WebSocket

Realtidsövervakning kräver en Enterprise-arbetsyta eller funktionsflaggan realtime-monitoring. Se Realtidsövervakning för konfiguration, kontrollkommandon och åtkomstkrav.

Strömma OpenTelemetry-spårdata som OTLP JSON medan en konversation pågår. Varje meddelande är en liten resourceSpans-batch, inte ett enda spår vid samtalets slut.

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

Autentisering kräver CONVAI_WRITE, xi-api-key (eller Authorization) och EDITOR-åtkomst till agentens arbetsyta. Anslut när konversationen har startat.

1

Aktivera övervakning för agenten

Ange monitoring_enabled: true och konfigurera monitoring_events före samtalet. Se Realtidsövervakning.

2

Anslut med OpenTelemetry-format

Lägg till events_format=opentelemetry i URL:en för övervaknings-WebSocket.

VAD-, turordningssannolikhets- och pinghändelser är inte tillgängliga när anpassade monitoring_events har konfigurerats. Strömmen innehåller endast text och metadata, inte råljud.

Sessionsprotokoll

  1. Anslut med autentiseringsrubriker.
  2. Ta emot {"type": "connected"}.
  3. Ta emot en rotspannbatch (elevenlabs.conversation, elevenlabs.source = monitoring).
  4. Ta emot cachelagd historik (omkring de senaste 100 händelserna), sedan {"type": "history_complete"}.
  5. Ta emot live-spannbatcher när händelser inträffar.

Med events_format=json (standard) returnerar WebSocket råa klienthändelser i stället för resourceSpans. Kontrollkommandon följer Realtidsövervakning.

Spårstruktur

elevenlabs.conversation
├── elevenlabs.turn.0
│ ├── elevenlabs.event.user_transcript
│ └── elevenlabs.tool.{name}
└── elevenlabs.turn.1
AspektEfter samtal och GETÖvervakning
DetaljnivåEtt spår per webhook eller begäranMånga meddelanden per konversation
HändelsespannTranskriptturerelevenlabs.event.{type}
TurgrupperingImplicit i transkriptordningenExplicit elevenlabs.turn.N
OrdningStabil transkriptordningHändelser kan ankomma i annan än strikt kronologisk ordning

Strukturerade händelser mappas till särskilda attribut (till exempel elevenlabs.user.text, elevenlabs.agent.text). Okända händelser använder elevenlabs.event.data med trunkerad JSON. Se Övervakningsspann för attributen för varje händelse.

Anta inte att händelseordningen motsvarar talordningen. Kor­relera live-spann med data efter samtal med samma traceId.

Beteende för övervakningsspann

  • Ett spann per meddelande. Varje resourceSpans-meddelande innehåller exakt ett spann.
  • Turer. Den första händelsen öppnar elevenlabs.turn.0. En user_transcript öppnar en ny tur endast när den aktuella turen redan har en, så tur 0 innehåller agentens hälsning, användarens första meddelande och svaret på det. Från tur 1 börjar varje tur med en user_transcript.
  • Tidsstämplar. startTimeUnixNano är tiden då servern skickade händelsen, inte tiden då den sades. Uppspelad historik har uppspelningstiden.
  • Varaktighet. Rot-, tur- och händelsespann börjar och slutar samtidigt och uppdateras inte när samtalet avslutas. Endast elevenlabs.tool.{name}-spann har en varaktighet, från agent_tool_request till agent_tool_response.
  • Återanslutningar. Varje anslutning skapar ett nytt rotspann-ID, startar om turnumreringen vid 0 och spelar upp cachelagd historik med nya spann-ID:n. Ta bort dubbletter efter innehåll, inte spann-ID.
  • Valda händelser. Strömmen innehåller endast händelserna i agentens monitoring_events. Standard är user_transcript, agent_response och agent_response_correction. Ett verktygsspann skickas när agent_tool_response anländer; välj även agent_tool_request för att få dess starttid.

Exempel på anslutning

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-spår från alla källor delar samma batchlayout för 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 }
}
]
}
]
}
]
}

Attributreferens

Alla attribut använder prefixet elevenlabs.*, förutom service.name.

Värdekodning

  • Värden använder OTLP JSON-omslutenheterna stringValue, intValue, doubleValue och boolValue. intValue är ett tal som kodas som en sträng, till exempel "3".
  • Ett attribut med ett null- eller tomt värde utelämnas.
  • Attribut som är märkta JSON innehåller en JSON-kodad sträng. JSON-värden och elevenlabs.reasoning_content trunkeras vid 4 096 tecken, så ett trunkerat värde kanske inte kan parsas.
  • Varje meddelande innehåller resursattributen service.name (elevenlabs-convai), elevenlabs.conversation_id och elevenlabs.agent_id.

Spår efter samtal och GET

Rotspann (elevenlabs.conversation)

AttributTypBeskrivning
elevenlabs.agent_id, elevenlabs.agent_namestringAgenten som hanterade samtalet
elevenlabs.conversation_idstringSamtals-ID
elevenlabs.conversation_productstringProdukten som samtalet kördes på
elevenlabs.statusstringSamtalsstatus
elevenlabs.session.duration_msintSamtalslängd i millisekunder
elevenlabs.sourcestringAlltid post_call_webhook, även för GET-samtal
elevenlabs.user_id, elevenlabs.environmentstringAnvändar-ID och miljö, när de har angetts
elevenlabs.cost, elevenlabs.cost_fiatnumberKostnad för samtalet
elevenlabs.authorization_method, elevenlabs.termination_reasonstringHur samtalet godkändes och varför det avslutades
elevenlabs.analysis.{field}string, number, boolResultat från samtalsanalys, till exempel elevenlabs.analysis.call_successful. Sentimentanalys ingår inte
elevenlabs.analysis.{field}.{key}JSONEn post i ett kapslat resultat, till exempel elevenlabs.analysis.evaluation_criteria_results.{criterion_id}
elevenlabs.analysis.scoped[{i}].{field}string, boolResultat från avgränsad analys
elevenlabs.dynamic_variable.{name}string, number, boolDynamiska variabler som skickades när samtalet startade
elevenlabs.telephony.{field}string, numberMetadata för telefonsamtal, för telefonsamtal
elevenlabs.batch.{field}string, numberMetadata för batchsamtal, för batchsamtal
elevenlabs.visited_agents.{i}.{field}stringAgenter som samtalet passerade, i ordning

Transkriptspann (elevenlabs.recv.user_transcript, elevenlabs.recv.agent_response)

AttributTypBeskrivning
elevenlabs.event.typestringuser eller agent
elevenlabs.user.text, elevenlabs.agent.textstringMeddelandetext
elevenlabs.turn.indexintPosition i transkriptet, från 0. Räknar varje transkriptpost, inte varje utbyte mellan användare och agent
elevenlabs.turn.agent_id, elevenlabs.turn.branch_id, elevenlabs.turn.workflow_node_id, elevenlabs.turn.version_idstringAgent, gren, workflow-nod och version som skapade meddelandet
elevenlabs.producing_llm, elevenlabs.llm_overridestringLLM som skapade meddelandet och den åsidosättning som används
elevenlabs.voice_idstringRöst som användes för meddelandet
elevenlabs.interruptedboolFinns och är true när användaren avbröt meddelandet
elevenlabs.ignored_as_backchannelboolOm meddelandet behandlades som en bakgrundssignal
elevenlabs.platform_eventstringPlattformshändelse som registrerades för meddelandet
elevenlabs.metric.{name}_msdoubleLatensmått, endast för agentspann. Se Latensmått
elevenlabs.llm_usage.{model}.{category}JSONToken och pris för varje LLM- och tokenkategori, till exempel input eller input_cache_read
elevenlabs.rag.embedding_model, elevenlabs.rag.retrieval_querystringModell och fråga för hämtning från kunskapsbasen
elevenlabs.rag.latency_msdoubleHämtningstid från kunskapsbasen i millisekunder
elevenlabs.rag.chunksJSONHämtade segment med document_id, chunk_id och vector_distance
elevenlabs.rag.used_chunk_idsJSONID:n för de segment som svaret använde
elevenlabs.kb.document_idsJSONDokument från kunskapsbasen som lästes in i prompten
elevenlabs.file_input.file_id, .filename, .mime_type, .count, .file_ids, .url, .urlsmixedFiler som användaren bifogade. De attribut som står i singular beskriver den första filen
elevenlabs.reasoning_contentstringSammanfattning av resonemang, när den finns

Verktygsspann (elevenlabs.tool.{name})

AttributTypBeskrivning
elevenlabs.event.typestringclient_tool_call
elevenlabs.tool.namestringVerktygsnamn
elevenlabs.tool_span_idstringSpann-ID för detta verktygsspann
elevenlabs.tool.latency_msdoubleVerktygets körningstid i millisekunder, när den är känd
elevenlabs.tool.paramsJSONParametrar för verktygsanrop
elevenlabs.tool.resultJSONVerktygsresultat
elevenlabs.turn.*stringAgentmetadata för transkriptposten som gjorde anropet

Övervakningsspann

SpannAttribut
elevenlabs.conversationelevenlabs.conversation_id, elevenlabs.agent_id, elevenlabs.source (monitoring)
elevenlabs.turn.{N}elevenlabs.turn.index (int)
elevenlabs.event.user_transcriptelevenlabs.user.text
elevenlabs.event.tentative_user_transcriptelevenlabs.user.text (tillfällig text; ett slutligt user_transcript följer)
elevenlabs.event.agent_responseelevenlabs.agent.text
elevenlabs.event.agent_response_correctionelevenlabs.agent.text (delen som sades innan användaren avbröt)
elevenlabs.event.client_tool_callelevenlabs.tool.name, elevenlabs.tool.params (JSON)
elevenlabs.event.mcp_tool_callelevenlabs.tool.name, elevenlabs.tool.params (JSON), elevenlabs.mcp.state
elevenlabs.event.mcp_connection_statuselevenlabs.mcp.integrations (JSON)
elevenlabs.event.guardrail_triggeredelevenlabs.guardrail.name
elevenlabs.event.client_errorelevenlabs.error.code (int), elevenlabs.error.name, elevenlabs.error.message. Status ERROR, med status.message inställt på [code] message
elevenlabs.event.audioInga. Endast en markör; strömmen innehåller inget ljud
elevenlabs.tool.{name}elevenlabs.tool.name, elevenlabs.tool.call_id, elevenlabs.tool.is_error (bool), elevenlabs.tool.is_blocked (bool). Status ERROR när verktyget misslyckades eller blockerades. Parametrar och resultat ingår inte
Alla andra elevenlabs.event.{type}elevenlabs.event.data (JSON): den råa händelsen, till exempel interruption, agent_tool_response_full_payload eller agent_response_metadata

Varje händelsespann innehåller också elevenlabs.event.type, inställt på händelsetypen (agent_tool för verktygsspann). Om du vill få verktygsresultat i övervakningsströmmen väljer du agent_tool_response_full_payload och läser dess elevenlabs.event.data.

Latensmått

Agenttranskriptspann i spår efter samtal och GET innehåller latensmått per tur som elevenlabs.metric.{name}_ms. Värdena är millisekunder, avrundade till 0,1 ms. Ett mått utelämnas från en tur när det inte har mätts. Övervakningsströmmen innehåller inga latensmått.

Samma mått visas i JSON-transkriptet som conversation_turn_metrics.metrics.{name}.elapsed_time, i sekunder.

AttributMäter
elevenlabs.metric.convai_ttf_audio_since_silence_msTiden från slutet av användarens tal (röstaktiviteten sjunker) till agentens första ljud. Detta är svarslatensen från början till slut. Registreras inte för timeout-turer
elevenlabs.metric.convai_turn_silence_before_initiation_msTystnad efter att användaren slutat tala, innan agentens tur började
elevenlabs.metric.convai_turn_asr_latency_msEftersläpande tal-till-text-latens för användarens senaste meddelande i turen
elevenlabs.metric.convai_turn_asr_excess_msDen del av tal-till-text-latensen som ökade svarstiden
elevenlabs.metric.convai_llm_service_ttfb_msTid till den första byten från LLM:en
elevenlabs.metric.convai_llm_service_ttf_sentence_msTid till den första fullständiga meningen från LLM:en
elevenlabs.metric.convai_llm_service_tt_last_sentence_msTid till den sista meningen från LLM:en
elevenlabs.metric.convai_llm_tool_request_generation_latency_msTid tills LLM:en hade förberett en verktygsbegäran
elevenlabs.metric.convai_tts_service_ttfb_msTid från att text-till-tal tog emot den första agenttexten till dess första ljudbyte
elevenlabs.metric.agents_rag_latency_msHämtningstid från kunskapsbasen

Begränsningar

  • Ingen direktöverföring till din OTLP gRPC-slutpunkt.
  • Nyttolaster är JSON formad som OTLP-export, inte rå protobuf över nätverket.

Relaterad dokumentation