> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Ś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. > **Info** > > ElevenLabs nie wysyła śladów bezpośrednio do twojego kolektora OTLP. Otrzymujesz JSON w formacie OTLP z > webhooka, API lub monitorującego WebSocketu i przekazujesz go do swojego backendu. ## 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 | Źródło | Kiedy otrzymujesz dane | Najlepsze zastosowanie | | ---------------------- | ------------------------------------ | ------------------------------------------------------- | | Webhook po rozmowie | Po zakończeniu rozmowy i analizy | Potoki wsadowe, rozliczenia i QA, trwałe przechowywanie | | API GET rozmowy | Na żądanie, gdy rozmowa już istnieje | Uzupełnianie danych, debugowanie, ponowne przetwarzanie | | Monitorujący WebSocket | W trakcie aktywnej rozmowy | Dashboardy na żywo, alerty, człowiek w pętli | ### 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 ```json { "type": "post_call_transcription_otel", "event_timestamp": 1700000000, "data": { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "otlp_traces": { "resourceSpans": [] } } } ``` ### Włącz transkrypcje OpenTelemetry #### Konfiguracja w panelu ### Utwórz webhook workspace'u W panelu ElevenAgents utwórz webhook workspace'u z adresem HTTPS i uwierzytelnianiem. ### Podłącz webhook po rozmowie Otwórz [ustawienia Agents](https://elevenlabs.io/app/agents/settings), przypisz webhook jako webhook po rozmowie, włącz zdarzenie **Transcript** i opcję **OpenTelemetry transcript payloads**. ![Ustawienia webhooka po rozmowie](/docs/_fern-img/eb5d768612d6461a21bc3127611f60724be3e1a55005af43faf48f2d7bf23807.webp) #### Konfiguracja przez CLI > **Note** > > Webhooki po rozmowie dla całego workspace'u konfigurujesz w panelu lub na karcie API. Użyj CLI, aby > nadpisać ustawienia webhooka dla konkretnego agenta. ### Pobierz konfigurację agenta ```bash elevenlabs agents pull --agent "" ``` ### Edytuj `agent_configs/.json` Ustaw `platform_settings.workspace_overrides.webhooks`: ```json { "platform_settings": { "workspace_overrides": { "webhooks": { "post_call_webhook_id": "wh_01jqz7x8y9z0a1b2c3d4e5f6", "events": ["transcript"], "transcript_format": "opentelemetry" } } } } ``` ### Wyślij zmiany ```bash elevenlabs agents push --agent "" ``` #### Konfiguracja przez API **`Python`** ```python title="Python" import os from dotenv import load_dotenv from elevenlabs import ElevenLabs load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) elevenlabs.conversational_ai.settings.update( webhooks={ "post_call_webhook_id": "wh_01jqz7x8y9z0a1b2c3d4e5f6", "events": ["transcript"], "transcript_format": "opentelemetry", }, ) ``` **`TypeScript`** ```typescript title="TypeScript" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY, }); await elevenlabs.conversationalAi.settings.update({ webhooks: { postCallWebhookId: "wh_01jqz7x8y9z0a1b2c3d4e5f6", events: ["transcript"], transcriptFormat: "opentelemetry", }, }); ``` Dla jednego agenta przekaż ten sam obiekt `webhooks` w `platform_settings.workspace_overrides` w [Update agent](/docs/pl/api-reference/agents/update). > **Warning** > > Webhooki transkrypcji OpenTelemetry nie zawierają audio. Użyj `post_call_audio`, jeśli potrzebujesz > nagrań. > > Zwróć **2xx**, aby oznaczyć sukces. **4xx** i **5xx** są traktowane jako błędy. > > Ponowne próby dotyczą webhooków transkrypcji (w tym OpenTelemetry) tylko wtedy, gdy opcja **Enable retries** jest włączona > w webhooku workspace'u. Przejściowe błędy (**5xx**, **429**, **408**) są ponawiane do 5 razy; **4xx** > nie. Webhooki audio nigdy nie są ponawiane. Powtarzające się błędy mogą automatycznie wyłączyć webhook. Szczegóły i wyjątki HIPAA znajdziesz w > [Webhookach po rozmowie](/docs/pl/eleven-agents/workflows/post-call-webhooks). ### Dostarczanie | Temat | Szczegóły | | ---------------- | ----------------------------------------------------------------------------------------------- | | Metoda | `POST` z ciałem JSON | | Uwierzytelnianie | `ElevenLabs-Signature: t={unix},v0={hmac}` dla `{timestamp}.{body}` | | Ponowne próby | Tylko webhooki transkrypcji; wymagają **Enable retries** w webhooku; zobacz ostrzeżenie powyżej | | Rozmiar | Długie parametry i wyniki narzędzi są skracane do 4 KB na atrybut spanu | ### Struktura śladu Każde dostarczenie to jeden kompletny ślad: span główny i elementy podrzędne. ```text 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](/docs/pl/eleven-agents/customization/llm#reasoning-summary). 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](/docs/pl/api-reference/conversations/get), aby otrzymać ten sam obiekt `otlp_traces` co w webhooku OpenTelemetry po rozmowie oraz pełny model rozmowy. ```http GET /v1/convai/conversations/{conversation_id}?format=opentelemetry ``` Wymaga klucza API z `CONVAI_READ`. Przy `format=json` (domyślnie) `otlp_traces` jest pomijany. ```json { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "status": "done", "transcript": [], "otlp_traces": { "resourceSpans": [] } } ``` | Temat | Szczegóły | | ------------ | ----------------------------------------------------------------- | | Czas | Ten sam generator oparty na transkrypcji co webhook po rozmowie | | Transkrypcja | `transcript` jest nadal zwracany; `otlp_traces` jest dodatkiem | | URL-e plików | Podpisane URL-e w atrybutach spanów wygasają po około 15 minutach | **`Python`** ```python title="Python" 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 ``` **`TypeScript`** ```typescript title="TypeScript" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY, }); const conversation = await elevenlabs.conversationalAi.conversations.get({ conversationId: "conv_9001k1zph3fkeh5s8xg9z90swaqa", format: "opentelemetry", }); const otlpTraces = conversation.otlpTraces; ``` **`cURL`** ```bash title="cURL" curl -s "https://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa?format=opentelemetry" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ | jq '.otlp_traces.resourceSpans[0].scopeSpans[0].spans[].name' ``` Oczekiwane nazwy spanów to m.in. `elevenlabs.conversation`, `elevenlabs.recv.user_transcript` i `elevenlabs.recv.agent_response`. ## Monitorujący WebSocket > **Note** > > Monitoring w czasie rzeczywistym wymaga workspace'u Enterprise lub flagi funkcji `realtime-monitoring`. > Konfigurację, polecenia sterujące i wymagania dostępu znajdziesz w [Monitoringu w czasie rzeczywistym](/docs/pl/eleven-agents/guides/realtime-monitoring). 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. ### Włącz monitoring dla agenta Ustaw `monitoring_enabled: true` i skonfiguruj `monitoring_events` przed połączeniem. Zobacz [Monitoring w czasie rzeczywistym](/docs/pl/eleven-agents/guides/realtime-monitoring#configuration). ### Połącz się w formacie OpenTelemetry Dodaj `events_format=opentelemetry` do URL-a monitorującego WebSocketu. > **Warning** > > Zdarzenia VAD, prawdopodobieństwa tury i ping nie są dostępne, gdy skonfigurowano własne `monitoring_events`. > Strumień zawiera tylko tekst i metadane, bez surowego audio. ### 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](/docs/pl/eleven-agents/guides/realtime-monitoring#control-commands). ### Struktura śladu ```text elevenlabs.conversation ├── elevenlabs.turn.0 │ ├── elevenlabs.event.user_transcript │ └── elevenlabs.tool.{name} └── elevenlabs.turn.1 ``` | Aspekt | Po rozmowie i GET | Monitoring | | -------------- | ---------------------------------- | ----------------------------------------------------------------- | | Szczegółowość | Jeden ślad na webhook lub żądanie | Wiele wiadomości na rozmowę | | Spany zdarzeń | Tury transkrypcji | `elevenlabs.event.{type}` | | Grupowanie tur | Niejawne w kolejności transkrypcji | Jawne `elevenlabs.turn.N` | | Kolejność | Stabilna kolejność transkrypcji | Zdarzenia mogą przychodzić poza ścisłą kolejnością chronologiczną | 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. > **Info** > > Nie zakładaj, że kolejność zdarzeń odpowiada kolejności mówienia. Łącz spany na żywo z danymi po rozmowie za pomocą > tego samego `traceId`. ### Przykładowe połączenie **`TypeScript`** ```typescript title="TypeScript" 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 }); } }); ``` **`Python`** ```python title="Python" import asyncio import json import os import websockets from dotenv import load_dotenv load_dotenv() async def monitor_opentelemetry(): uri = ( "wss://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa/monitor" "?events_format=opentelemetry" ) headers = {"xi-api-key": os.getenv("ELEVENLABS_API_KEY")} async with websockets.connect(uri, extra_headers=headers) as ws: async for raw in ws: msg = json.loads(raw) if msg.get("type") in ("connected", "history_complete"): continue if msg.get("resourceSpans"): forward_to_collector({"resourceSpans": msg["resourceSpans"]}) asyncio.run(monitor_opentelemetry()) ``` ## Struktura OTLP JSON Ślady OpenTelemetry ze wszystkich źródeł mają ten sam układ partii OTLP JSON: ```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](/docs/pl/eleven-agents/workflows/post-call-webhooks) * [Monitoring w czasie rzeczywistym](/docs/pl/eleven-agents/guides/realtime-monitoring)