Ślady OpenTelemetry

ElevenLabs Agents może eksportować rozmowy jako ślady OpenTelemetry zakodowane jako OTLP JSON (resourceSpans). Przekaż je do Datadog, Grafana Tempo, Honeycomb lub dowolnego backendu obsługującego OTLP.

Przegląd

Eksportuj ślady z trzech źródeł. Wszystkie używają tego samego ID śladu dla każdej rozmowy i nazewnictwa atrybutów elevenlabs.*. Kształt spanów i czas różnią się między połączeniem po zakończeniu/GET (na podstawie transkrypcji) a monitoringiem (na podstawie zdarzeń).

Źródła eksportu

Wybór źródła

• Każde zakończone połączenie w twojej hurtowni danych: webhook po rozmowie
• Jednorazowy eksport lub naprawa: GET rozmowy z format=opentelemetry
• Panel nadzorcy na żywo lub alerty: monitorujący WebSocket
• Pełny harmonogram zdarzeń po fakcie: webhook po rozmowie lub GET rozmowy
• Zdarzenia narzędzi, MCP lub guardraili w chwili wystąpienia: monitorujący WebSocket

Użyj traceId lub elevenlabs.conversation_id, aby łączyć dane między źródłami. Połącz monitoring do działań na żywo, webhooki do trwałej analityki i GET do uzupełniania danych.

Dla każdego źródła potrzebujesz kolektora obsługującego OTLP lub dostawcy narzędzi obserwowalności. Webhooki po rozmowie wymagają endpointu webhooka workspace’u. API GET i monitorujący WebSocket mają własne zakresy kluczy API oraz konfigurację; szczegóły znajdziesz w sekcjach poniżej.

Webhook po rozmowie

Po zakończeniu rozmowy ElevenLabs wysyła żądanie POST, gdy skonfigurowany jest webhook po rozmowie, events zawiera transcript, a transcript_format ma wartość opentelemetry.

Webhook ma type równy post_call_transcription_otel (nie post_call_transcription, który zwraca transkrypcje JSON).

Payload webhooka

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

Włącz transkrypcje OpenTelemetry

Dostarczanie

Struktura śladu

Każde dostarczenie to jeden kompletny ślad: span główny i elementy podrzędne.

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

Spany odpowiedzi agenta zawierają elevenlabs.reasoning_content, gdy dostarczenie zawiera podsumowanie rozumowania.

Czas pochodzi z time_in_call_secs transkrypcji i metadanych połączenia. Span główny ustawia elevenlabs.source = post_call_webhook oraz status ERROR, gdy połączenie nie zakończyło się normalnym rozłączeniem klienta.

GET rozmowy

Poproś o format OpenTelemetry w Get conversation, aby otrzymać ten sam obiekt otlp_traces co w webhooku OpenTelemetry po rozmowie oraz pełny model rozmowy.

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

Wymaga klucza API z CONVAI_READ. Przy format=json (domyślnie) otlp_traces jest pomijany.

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

Oczekiwane nazwy spanów to m.in. elevenlabs.conversation, elevenlabs.recv.user_transcript i elevenlabs.recv.agent_response.

Monitorujący WebSocket

Przesyłaj dane śladów OpenTelemetry jako OTLP JSON podczas rozmowy. Każda wiadomość to mała partia resourceSpans, a nie jeden ślad na końcu połączenia.

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

Uwierzytelnianie wymaga CONVAI_WRITE, xi-api-key (lub Authorization) oraz dostępu EDITOR do workspace’u agenta. Połącz się po rozpoczęciu rozmowy.

Protokół sesji

1. Połącz się z nagłówkami uwierzytelniającymi.
2. Otrzymaj {"type": "connected"}.
3. Otrzymaj partię spanu głównego (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Otrzymaj historię z pamięci podręcznej (około ostatnich 100 zdarzeń), a następnie {"type": "history_complete"}.
5. Otrzymuj partie spanów na żywo w miarę występowania zdarzeń.

Przy events_format=json (domyślnie) WebSocket zwraca surowe zdarzenia klienta zamiast resourceSpans. Polecenia sterujące odpowiadają Monitoringowi w czasie rzeczywistym.

Struktura śladu

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

Zdarzenia strukturalne są mapowane na dedykowane atrybuty (np. elevenlabs.user.text, elevenlabs.agent.text). Nieznane zdarzenia używają elevenlabs.event.data ze skróconym JSON-em.

Przykładowe połączenie

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

Struktura OTLP JSON

Ślady OpenTelemetry ze wszystkich źródeł mają ten sam układ partii 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 }
            }
          ]
        }
      ]
    }
  ]
}

Ograniczenia

• Brak bezpośredniego wysyłania do endpointu OTLP gRPC.
• Payloady to JSON w formacie eksportu OTLP, a nie surowy protobuf przesyłany przez sieć.

Powiązana dokumentacja

• Webhooki po rozmowie
• Monitoring w czasie rzeczywistym