OpenTelemetry ट्रेसेस

ElevenLabs Agents बातचीत को OpenTelemetry traces के रूप में, OTLP JSON (resourceSpans) में एन्कोड करके एक्सपोर्ट कर सकता है। इन्हें Datadog, Grafana Tempo, Honeycomb या OTLP इनजेस्ट करने वाले किसी भी बैकएंड पर फ़ॉरवर्ड करें।

परिचय

तीन स्रोतों से ट्रेस एक्सपोर्ट करें। तीनों में हर बातचीत के लिए एक ही trace ID और elevenlabs.* एट्रिब्यूट नामकरण होता है। पोस्ट-कॉल/GET (ट्रांसक्रिप्ट-आधारित) और मॉनिटरिंग (इवेंट-आधारित) के बीच स्पैन का आकार और टाइमिंग अलग होते हैं।

एक्सपोर्ट स्रोत

स्रोत चुनना

• आपके डेटा वेयरहाउस में हर पूरी हुई कॉल: पोस्ट-कॉल webhook
• एक बार का एक्सपोर्ट या सुधार: format=opentelemetry के साथ GET conversation
• लाइव सुपरवाइज़र UI या अलर्टिंग: monitoring WebSocket
• बाद में पूरी फ़िडेलिटी वाली टाइमलाइन: पोस्ट-कॉल webhook या GET conversation
• टूल, MCP या गार्डरेल इवेंट, जैसे ही हों: monitoring WebSocket

अलग-अलग स्रोतों के डेटा को जोड़ने के लिए traceId या elevenlabs.conversation_id इस्तेमाल करें। लाइव ऑपरेशन के लिए monitoring, स्थायी एनालिटिक्स के लिए webhooks और बैकफिल के लिए GET को मिलाकर इस्तेमाल करें।

हर स्रोत के लिए आपको OTLP-सक्षम कलेक्टर या ऑब्ज़र्वेबिलिटी वेंडर चाहिए। पोस्ट-कॉल webhooks के लिए workspace webhook endpoint चाहिए। GET API और monitoring WebSocket, दोनों के अपने API key scopes और सेटअप हैं; नीचे दिए गए सेक्शन देखें।

पोस्ट-कॉल webhook

बातचीत खत्म होने के बाद, जब कोई पोस्ट-कॉल webhook कॉन्फ़िगर हो, events में transcript शामिल हो और transcript_format opentelemetry हो, तो ElevenLabs POST अनुरोध भेजता है।

webhook का type post_call_transcription_otel होता है (post_call_transcription नहीं, जो JSON ट्रांसक्रिप्ट लौटाता है)।

Webhook payload

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

OpenTelemetry ट्रांसक्रिप्ट चालू करें

डिलीवरी

ट्रेस संरचना

हर डिलीवरी एक पूरी ट्रेस होती है: एक रूट स्पैन और उसके चाइल्ड।

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

अगर डिलीवरी में reasoning summary हो, तो agent-response spans में elevenlabs.reasoning_content शामिल होता है।

टाइमिंग ट्रांसक्रिप्ट time_in_call_secs और कॉल मेटाडेटा से आती है। रूट स्पैन elevenlabs.source = post_call_webhook सेट करता है और अगर कॉल सामान्य client disconnect के साथ खत्म नहीं हुई हो, तो स्टेटस ERROR सेट करता है।

GET conversation

पोस्ट-कॉल OpenTelemetry webhook जैसा ही otlp_traces ऑब्जेक्ट, साथ में पूरा conversation model पाने के लिए Get conversation पर OpenTelemetry format का अनुरोध करें।

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

CONVAI_READ वाली API key चाहिए। format=json (डिफ़ॉल्ट) के साथ otlp_traces शामिल नहीं होता।

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

अपेक्षित स्पैन नामों में elevenlabs.conversation, elevenlabs.recv.user_transcript और elevenlabs.recv.agent_response शामिल हैं।

Monitoring WebSocket

बातचीत चल रही हो, तब OpenTelemetry trace data को OTLP JSON के रूप में स्ट्रीम करें। हर संदेश एक छोटा resourceSpans बैच होता है, न कि कॉल खत्म होने की एक ट्रेस।

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

Authentication के लिए CONVAI_WRITE, xi-api-key (या Authorization) और agent workspace पर EDITOR एक्सेस चाहिए। बातचीत शुरू होने के बाद कनेक्ट करें।

सेशन प्रोटोकॉल

1. authentication headers के साथ कनेक्ट करें।
2. {"type": "connected"} पाएं।
3. एक रूट स्पैन बैच पाएं (elevenlabs.conversation, elevenlabs.source = monitoring)।
4. कैश की गई हिस्ट्री (आखिरी लगभग 100 इवेंट) पाएं, फिर {"type": "history_complete"}।
5. इवेंट होते ही लाइव स्पैन बैच पाएं।

events_format=json (डिफ़ॉल्ट) के साथ WebSocket, resourceSpans के बजाय raw client events लौटाता है। कंट्रोल कमांड Real-time monitoring के अनुसार होते हैं।

ट्रेस संरचना

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

स्ट्रक्चर्ड इवेंट समर्पित एट्रिब्यूट में मैप होते हैं (उदाहरण के लिए elevenlabs.user.text, elevenlabs.agent.text)। अज्ञात इवेंट, ट्रंकेट किए गए JSON के साथ elevenlabs.event.data इस्तेमाल करते हैं।

उदाहरण कनेक्शन

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 संरचना

सभी स्रोतों के OpenTelemetry traces में एक ही 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 }
            }
          ]
        }
      ]
    }
  ]
}

सीमाएं

• आपके OTLP gRPC endpoint पर सीधे पुश नहीं किया जाता।
• Payloads OTLP export जैसे आकार वाले JSON हैं, wire पर raw protobuf नहीं।

संबंधित दस्तावेज़

• Post-call webhooks
• Real-time monitoring