OpenTelemetry ट्रेस

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

जानकारी

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

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

स्रोत चुनना

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

विभिन्न स्रोतों के डेटा को जोड़ने के लिए traceId या elevenlabs.conversation_id का इस्तेमाल करें। लाइव ऑपरेशन के लिए मॉनिटरिंग, टिकाऊ एनालिटिक्स के लिए वेबहुक और बैकफ़िल के लिए GET को मिलाकर इस्तेमाल करें।

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

पोस्ट-कॉल वेबहुक

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

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

वेबहुक पेलोड

{
  "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}
└── ...

एजेंट-रिस्पॉन्स स्पैन में elevenlabs.reasoning_content शामिल होता है, जब डिलीवरी में रीज़निंग सारांश हो।

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

GET बातचीत

पोस्ट-कॉल OpenTelemetry वेबहुक जैसा ही otlp_traces ऑब्जेक्ट पाने के लिए, पूरे बातचीत मॉडल के साथ, Get conversation पर OpenTelemetry फ़ॉर्मैट का अनुरोध करें।

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

CONVAI_READ वाले API की की ज़रूरत है। 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 शामिल हैं।

मॉनिटरिंग WebSocket

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

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

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

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

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

events_format=json (डिफ़ॉल्ट) के साथ WebSocket resourceSpans की जगह रॉ क्लाइंट इवेंट लौटाता है। कंट्रोल कमांड रीयल-टाइम मॉनिटरिंग से मेल खाते हैं।

ट्रेस संरचना

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 ट्रेस एक ही 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 एंडपॉइंट पर कोई सीधा पुश नहीं।
• पेलोड OTLP एक्सपोर्ट जैसे JSON होते हैं, नेटवर्क पर रॉ protobuf नहीं।

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

• पोस्ट-कॉल वेबहुक
• रीयल-टाइम मॉनिटरिंग