Tracce OpenTelemetry
Esporta le tracce OpenTelemetry nel tuo stack di osservabilità come JSON OTLP.
Gli agenti di ElevenLabs possono esportare le conversazioni come tracce OpenTelemetry codificate come JSON OTLP (resourceSpans). Inoltrale a Datadog, Grafana Tempo, Honeycomb o a qualsiasi backend che acquisisca OTLP.
ElevenLabs non invia le tracce direttamente al tuo collector OTLP. Ricevi JSON in formato OTLP da un webhook, un’API o un WebSocket di monitoraggio e lo inoltri al tuo backend.
Panoramica
Esporta le tracce da tre superfici. Tutte e tre condividono lo stesso ID traccia per conversazione e la denominazione degli attributi elevenlabs.*. La struttura e le tempistiche degli span differiscono tra post-chiamata/GET (basati sulla trascrizione) e monitoraggio (basato sugli eventi).
Superfici di esportazione
Scegliere una superficie
- Ogni chiamata completata nel tuo data warehouse: webhook post-chiamata
- Esportazione o correzione una tantum: GET della conversazione con
format=opentelemetry - Interfaccia supervisore o avvisi in tempo reale: WebSocket di monitoraggio
- Timeline completa a posteriori: webhook post-chiamata o GET della conversazione
- Eventi di tool, MCP o guardrail nel momento in cui si verificano: WebSocket di monitoraggio
Usa traceId o elevenlabs.conversation_id per unire i dati tra le superfici. Combina il monitoraggio per le operazioni in tempo reale, i webhook per analisi durevoli e GET per il backfill.
Per ogni superficie ti serve un collector compatibile con OTLP o un provider di osservabilità. I webhook post-chiamata richiedono un endpoint webhook del workspace. L’API GET e il WebSocket di monitoraggio hanno ciascuno i propri scope per le chiavi API e la propria configurazione; consulta le sezioni seguenti.
Webhook post-chiamata
Al termine di una conversazione, ElevenLabs invia una richiesta POST quando è configurato un webhook post-chiamata, events include transcript e transcript_format è opentelemetry.
Il type del webhook è post_call_transcription_otel (non post_call_transcription, che restituisce trascrizioni JSON).
Payload del webhook
Abilitare le trascrizioni OpenTelemetry
Configura dalla dashboard
Configura tramite CLI
Configura tramite API
Crea un webhook del workspace
Nella Dashboard di ElevenAgents, crea un webhook del workspace con il tuo URL HTTPS e l’autenticazione.
Collega il webhook post-chiamata
Apri le impostazioni degli agenti, assegna il webhook come webhook post-chiamata, abilita l’evento Trascrizione e attiva i payload di trascrizione OpenTelemetry.

I webhook di trascrizione OpenTelemetry non includono l’audio. Usa post_call_audio se ti servono
le registrazioni.
Restituisci 2xx in caso di successo. 4xx e 5xx sono considerati errori.
I tentativi si applicano ai webhook di trascrizione (incluso OpenTelemetry) e audio solo quando Abilita ritentativi è attivo per il webhook del workspace. Gli errori transitori (** 5xx **, **429 **, **408 **) vengono ritentati fino a 5 volte; 4xx no. Errori ripetuti possono disabilitare automaticamente il webhook. Consulta Webhook post-chiamata per dettagli ed eccezioni HIPAA.
Consegna
Struttura della traccia
Ogni consegna è una traccia completa: uno span radice più elementi figlio.
Gli span di risposta dell’agente includono elevenlabs.reasoning_content quando la consegna contiene un riepilogo del ragionamento.
Le tempistiche derivano da time_in_call_secs della trascrizione e dai metadati della chiamata:
- Lo span radice copre l’intera chiamata, da
start_time_unix_secspercall_duration_secs. - Ogni span della trascrizione inizia al proprio
time_in_call_secse termina quando inizia la voce di trascrizione successiva. L’ultimo termina con la chiamata. - Uno span del tool inizia con il proprio span della trascrizione e dura per la latenza del tool, quando nota.
Lo span radice imposta elevenlabs.source = post_call_webhook. Il suo stato è ERROR quando lo stato della conversazione è failed o i metadati della chiamata registrano un errore, mentre status.message riporta il motivo dell’errore quando presente. Consulta il Riferimento degli attributi per tutti gli attributi.
GET della conversazione
Richiedi il formato OpenTelemetry in Ottieni conversazione per ricevere lo stesso oggetto otlp_traces del webhook OpenTelemetry post-chiamata, oltre al modello completo della conversazione.
Richiede una chiave API con CONVAI_READ. Con format=json (impostazione predefinita), otlp_traces viene omesso.
I nomi di span previsti includono elevenlabs.conversation, elevenlabs.recv.user_transcript e elevenlabs.recv.agent_response.
WebSocket di monitoraggio
Il monitoraggio in tempo reale richiede un workspace Enterprise o il feature flag realtime-monitoring.
Consulta Monitoraggio in tempo reale per configurazione,
comandi di controllo e requisiti di accesso.
Trasmetti dati delle tracce OpenTelemetry come JSON OTLP mentre è in corso una conversazione. Ogni messaggio è un piccolo batch resourceSpans, non una singola traccia di fine chiamata.
L’autenticazione richiede CONVAI_WRITE, xi-api-key (o Authorization) e accesso EDITOR al workspace dell’agente. Connettiti dopo l’avvio della conversazione.
Abilita il monitoraggio sull’agente
Imposta monitoring_enabled: true e configura monitoring_events prima della chiamata. Consulta Monitoraggio in tempo reale.
Connettiti con il formato OpenTelemetry
Aggiungi events_format=opentelemetry all’URL del WebSocket di monitoraggio.
Gli eventi VAD, di probabilità di turno e ping non sono disponibili quando sono configurati monitoring_events
personalizzati. Lo stream include solo testo e metadati, non audio non elaborato.
Protocollo della sessione
- Connettiti con gli header di autenticazione.
- Ricevi
{"type": "connected"}. - Ricevi un batch di span radice (
elevenlabs.conversation,elevenlabs.source=monitoring). - Ricevi la cronologia in cache (circa gli ultimi 100 eventi), quindi
{"type": "history_complete"}. - Ricevi batch di span in tempo reale al verificarsi degli eventi.
Con events_format=json (predefinito), il WebSocket restituisce eventi client non elaborati anziché resourceSpans. I comandi di controllo corrispondono a Monitoraggio in tempo reale.
Struttura della traccia
Gli eventi strutturati vengono mappati su attributi dedicati (ad esempio elevenlabs.user.text, elevenlabs.agent.text). Gli eventi sconosciuti usano elevenlabs.event.data con JSON troncato. Consulta Span di monitoraggio per gli attributi di ogni evento.
Non presumere che l’ordine degli eventi corrisponda all’ordine di conversazione. Correla gli span in tempo reale con i dati post-chiamata usando
lo stesso traceId.
Comportamento degli span di monitoraggio
- Uno span per messaggio. Ogni messaggio
resourceSpanscontiene esattamente uno span. - Turni. Il primo evento apre
elevenlabs.turn.0. Unuser_transcriptapre un nuovo turno solo quando quello corrente ne contiene già uno, quindi il turno 0 contiene il saluto dell’agente, il primo messaggio dell’utente e la relativa risposta. Dal turno 1, ogni turno inizia con unuser_transcript. - Timestamp.
startTimeUnixNanoè l’ora in cui il server ha inviato l’evento, non quella in cui è stato pronunciato. La cronologia riprodotta riporta l’ora della riproduzione. - Durate. Gli span radice, di turno e di evento iniziano e terminano nello stesso momento e non vengono aggiornati alla fine della chiamata. Solo gli span
elevenlabs.tool.{name}hanno una durata, daagent_tool_requestaagent_tool_response. - Riconnessioni. Ogni connessione crea un nuovo ID dello span radice, riavvia la numerazione dei turni da 0 e riproduce la cronologia in cache con nuovi ID degli span. Rimuovi i duplicati in base al contenuto, non all’ID dello span.
- Eventi selezionati. Lo stream contiene solo gli eventi in
monitoring_eventsdell’agente. L’impostazione predefinita èuser_transcript,agent_responseeagent_response_correction. Uno span del tool viene inviato quando arrivaagent_tool_response; seleziona ancheagent_tool_requestper ottenerne l’ora di inizio.
Esempio di connessione
Struttura JSON OTLP
Le tracce OpenTelemetry di tutte le superfici condividono lo stesso layout di batch JSON OTLP:
Riferimento degli attributi
Tutti gli attributi usano il prefisso elevenlabs.*, ad eccezione di service.name.
Codifica dei valori
- I valori usano i wrapper JSON OTLP
stringValue,intValue,doubleValueeboolValue.intValueè un numero codificato come stringa, ad esempio"3". - Un attributo con valore nullo o vuoto viene omesso.
- Gli attributi contrassegnati come JSON contengono una stringa codificata in JSON. I valori JSON e
elevenlabs.reasoning_contentvengono troncati a 4.096 caratteri, quindi un valore troncato potrebbe non essere analizzabile. - Ogni messaggio include gli attributi della risorsa
service.name(elevenlabs-convai),elevenlabs.conversation_ideelevenlabs.agent_id.
Span post-call e GET
Span radice (elevenlabs.conversation)
Span della trascrizione (elevenlabs.recv.user_transcript, elevenlabs.recv.agent_response)
Span degli strumenti (elevenlabs.tool.{name})
Span di monitoraggio
Ogni span evento include anche elevenlabs.event.type, impostato sul tipo di evento (agent_tool negli span degli strumenti). Per ottenere i risultati degli strumenti nello stream di monitoraggio, seleziona agent_tool_response_full_payload e leggi il relativo elevenlabs.event.data.
Metriche di latenza
Gli span della trascrizione dell’agente nelle tracce post-call e GET includono metriche di latenza per turno come elevenlabs.metric.{name}_ms. I valori sono espressi in millisecondi e arrotondati a 0,1 ms. Una metrica viene omessa da un turno quando non è stata misurata. Lo stream di monitoraggio non include metriche di latenza.
Le stesse metriche compaiono nella trascrizione JSON come conversation_turn_metrics.metrics.{name}.elapsed_time, in secondi.
Limitazioni
- Nessun invio diretto al tuo endpoint gRPC OTLP.
- I payload sono JSON con la struttura dell’esportazione OTLP, non protobuf non elaborati trasmessi via rete.