Tracce OpenTelemetry

Gli agenti ElevenLabs possono esportare le conversazioni come tracce OpenTelemetry codificate in OTLP JSON (resourceSpans). Inoltrale a Datadog, Grafana Tempo, Honeycomb o a qualsiasi backend che acquisisca OTLP.

Panoramica

Esporta le tracce da tre fonti. Tutte e tre condividono lo stesso ID traccia per conversazione e la denominazione degli attributi elevenlabs.*. La struttura e la tempistica degli span differiscono tra post-chiamata/GET (basati sulla trascrizione) e monitoraggio (basato sugli eventi).

Fonti di esportazione

Scegliere una fonte

• Ogni chiamata completata nel tuo data warehouse: webhook post-chiamata
• Esportazione o correzione una tantum: GET della conversazione con format=opentelemetry
• UI di supervisione o avvisi in tempo reale: WebSocket di monitoraggio
• Timeline completa e dettagliata 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 fonti. Combina il monitoraggio per le operazioni in tempo reale, i webhook per analisi durature e GET per il backfill.

Per ogni fonte ti serve un collector compatibile con OTLP o un fornitore 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 della chiave 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

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

Abilitare le trascrizioni OpenTelemetry

Consegna

Struttura della traccia

Ogni consegna è una traccia completa: uno span radice più elementi figlio.

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

Gli span delle risposte dell’agente includono elevenlabs.reasoning_content quando la consegna contiene un riepilogo del ragionamento.

La tempistica deriva da time_in_call_secs della trascrizione e dai metadati della chiamata. Lo span radice imposta elevenlabs.source = post_call_webhook e lo stato ERROR quando la chiamata non termina con una normale disconnessione del client.

GET della conversazione

Richiedi il formato OpenTelemetry in Ottieni conversazione per ricevere lo stesso oggetto otlp_traces del webhook OpenTelemetry post-chiamata, insieme al modello completo della conversazione.

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

Richiede una chiave API con CONVAI_READ. Con format=json (predefinito), otlp_traces viene omesso.

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

I nomi degli span previsti includono elevenlabs.conversation, elevenlabs.recv.user_transcript e elevenlabs.recv.agent_response.

WebSocket di monitoraggio

Trasmetti i dati delle tracce OpenTelemetry come OTLP JSON mentre è in corso una conversazione. Ogni messaggio è un piccolo batch resourceSpans, non una singola traccia di fine chiamata.

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

L’autenticazione richiede CONVAI_WRITE, xi-api-key (o Authorization) e accesso EDITOR al workspace dell’agente. Connettiti dopo l’avvio della conversazione.

Protocollo di sessione

1. Connettiti con gli header di autenticazione.
2. Ricevi {"type": "connected"}.
3. Ricevi un batch di span radice (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Ricevi la cronologia in cache (circa gli ultimi 100 eventi), quindi {"type": "history_complete"}.
5. Ricevi batch di span in tempo reale man mano che si verificano gli 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

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

Gli eventi strutturati vengono mappati ad attributi dedicati (ad esempio elevenlabs.user.text, elevenlabs.agent.text). Gli eventi sconosciuti usano elevenlabs.event.data con JSON troncato.

Esempio di connessione

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 });
  }
});

Struttura JSON OTLP

Le tracce OpenTelemetry di tutte le fonti condividono lo stesso layout batch JSON OTLP:

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

Limitazioni

• Nessun invio diretto al tuo endpoint OTLP gRPC.
• I payload sono JSON con la struttura dell’esportazione OTLP, non protobuf non elaborato trasmesso via rete.

Documentazione correlata

• Webhook post-chiamata
• Monitoraggio in tempo reale