> 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. # OpenTelemetry ट्रेस ElevenLabs Agents बातचीत को **OpenTelemetry ट्रेस** के रूप में एक्सपोर्ट कर सकते हैं, जो **OTLP JSON** (`resourceSpans`) में एन्कोड होते हैं। इन्हें Datadog, Grafana Tempo, Honeycomb या OTLP लेने वाले किसी भी बैकएंड पर फ़ॉरवर्ड करें। > **Info** > > ElevenLabs ट्रेस को सीधे आपके OTLP कलेक्टर पर नहीं भेजता। आपको वेबहुक, API या मॉनिटरिंग WebSocket से > OTLP के अनुरूप JSON मिलता है, जिसे आप अपने बैकएंड पर फ़ॉरवर्ड करते हैं। ## जानकारी तीन स्रोतों से ट्रेस एक्सपोर्ट करें। तीनों में हर बातचीत के लिए एक ही **trace ID** और `elevenlabs.*` एट्रिब्यूट नाम होते हैं। पोस्ट-कॉल/GET (ट्रांसक्रिप्ट-आधारित) और मॉनिटरिंग (इवेंट-आधारित) के बीच स्पैन की संरचना और टाइमिंग अलग होती है। ### एक्सपोर्ट स्रोत | स्रोत | डेटा कब मिलता है | सबसे उपयुक्त | | ------------------- | --------------------------------------------- | ----------------------------------------- | | पोस्ट-कॉल वेबहुक | बातचीत खत्म होने और विश्लेषण पूरा होने के बाद | बैच पाइपलाइन, बिलिंग और QA, टिकाऊ स्टोरेज | | GET बातचीत API | मांग पर, बातचीत उपलब्ध होने के बाद | बैकफ़िल, डीबगिंग, दोबारा प्रोसेसिंग | | मॉनिटरिंग WebSocket | लाइव बातचीत के दौरान | लाइव डैशबोर्ड, अलर्टिंग, ह्यूमन-इन-द-लूप | ### स्रोत चुनना * **अपने डेटा वेयरहाउस में हर पूरी हुई कॉल**: पोस्ट-कॉल वेबहुक * **एक बार का एक्सपोर्ट या सुधार**: `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 ट्रांसक्रिप्ट लौटाता है)। ### वेबहुक पेलोड ```json { "type": "post_call_transcription_otel", "event_timestamp": 1700000000, "data": { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "otlp_traces": { "resourceSpans": [] } } } ``` ### OpenTelemetry ट्रांसक्रिप्ट चालू करें #### डैशबोर्ड से कॉन्फ़िगर करें ### वर्कस्पेस वेबहुक बनाएं ElevenAgents डैशबोर्ड में, अपने HTTPS URL और ऑथेंटिकेशन के साथ एक वर्कस्पेस वेबहुक बनाएं। ### पोस्ट-कॉल वेबहुक जोड़ें [Agents settings](https://elevenlabs.io/app/agents/settings) खोलें, वेबहुक को पोस्ट-कॉल वेबहुक के रूप में असाइन करें, **Transcript** इवेंट चालू करें और **OpenTelemetry transcript payloads** ऑन करें। ![पोस्ट-कॉल वेबहुक सेटिंग्स](/docs/_fern-img/eb5d768612d6461a21bc3127611f60724be3e1a55005af43faf48f2d7bf23807.webp) #### CLI से कॉन्फ़िगर करें > **Note** > > वर्कस्पेस-व्यापी पोस्ट-कॉल वेबहुक डैशबोर्ड या API टैब में कॉन्फ़िगर किए जाते हैं। किसी खास एजेंट की > वेबहुक सेटिंग बदलने के लिए CLI इस्तेमाल करें। ### एजेंट कॉन्फ़िगरेशन पुल करें ```bash elevenlabs agents pull --agent "" ``` ### `agent_configs/.json` एडिट करें `platform_settings.workspace_overrides.webhooks` सेट करें: ```json { "platform_settings": { "workspace_overrides": { "webhooks": { "post_call_webhook_id": "wh_01jqz7x8y9z0a1b2c3d4e5f6", "events": ["transcript"], "transcript_format": "opentelemetry" } } } } ``` ### अपने बदलाव पुश करें ```bash elevenlabs agents push --agent "" ``` #### 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", }, }); ``` किसी एक एजेंट के लिए, [Update agent](/docs/hi/api-reference/agents/update) में `platform_settings.workspace_overrides` के अंतर्गत वही `webhooks` ऑब्जेक्ट पास करें। > **Warning** > > OpenTelemetry ट्रांसक्रिप्ट वेबहुक में ऑडियो शामिल नहीं होता। अगर आपको > रिकॉर्डिंग चाहिए, तो `post_call_audio` इस्तेमाल करें। > > सफलता के लिए **2xx** लौटाएं। **4xx** और **5xx** को विफलता माना जाता है। > > ट्रांसक्रिप्ट (OpenTelemetry समेत) और ऑडियो वेबहुक के लिए रिट्राई केवल तब लागू होते हैं, जब वर्कस्पेस वेबहुक में **Enable > retries** चालू हो। अस्थायी त्रुटियों (\*\* 5xx \*\*, \*\*429 \*\*, \*\*408 \*\*) पर अधिकतम 5 बार रिट्राई होता है; > **4xx** पर नहीं। बार-बार विफल होने पर वेबहुक अपने-आप बंद हो सकता है। विवरण और HIPAA > अपवादों के लिए [पोस्ट-कॉल वेबहुक](/docs/hi/eleven-agents/workflows/post-call-webhooks) देखें। ### डिलीवरी | विषय | जानकारी | | ---------- | --------------------------------------------------------------------------- | | तरीका | JSON बॉडी के साथ `POST` | | ऑथेंटिकेशन | `{timestamp}.{body}` पर `ElevenLabs-Signature: t={unix},v0={hmac}` | | रिट्राई | वेबहुक पर **Enable retries** ज़रूरी है; ऊपर दी गई चेतावनी देखें | | आकार | लंबे टूल पैरामीटर और नतीजे हर स्पैन एट्रिब्यूट पर 4 KB में ट्रंकेट होते हैं | ### ट्रेस संरचना हर डिलीवरी एक पूरा ट्रेस होती है: एक रूट स्पैन और उसके चिल्ड्रन। ```text elevenlabs.conversation ├── elevenlabs.recv.user_transcript ├── elevenlabs.recv.agent_response │ └── elevenlabs.tool.{name} └── ... ``` एजेंट-रिस्पॉन्स स्पैन में `elevenlabs.reasoning_content` शामिल होता है, जब डिलीवरी में [रीज़निंग सारांश](/docs/hi/eleven-agents/customization/llm#reasoning-summary) हो। टाइमिंग ट्रांसक्रिप्ट के `time_in_call_secs` और कॉल मेटाडेटा से आती है। रूट स्पैन `elevenlabs.source` = `post_call_webhook` सेट करता है और जब कॉल सामान्य क्लाइंट डिस्कनेक्ट के साथ खत्म नहीं हुई हो, तो स्टेटस `ERROR` सेट करता है। ## GET बातचीत पोस्ट-कॉल OpenTelemetry वेबहुक जैसा ही `otlp_traces` ऑब्जेक्ट पाने के लिए, पूरे बातचीत मॉडल के साथ, [Get conversation](/docs/hi/api-reference/conversations/get) पर OpenTelemetry फ़ॉर्मैट का अनुरोध करें। ```http GET /v1/convai/conversations/{conversation_id}?format=opentelemetry ``` `CONVAI_READ` वाले API की की ज़रूरत है। `format=json` (डिफ़ॉल्ट) के साथ `otlp_traces` शामिल नहीं होता। ```json { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "status": "done", "transcript": [], "otlp_traces": { "resourceSpans": [] } } ``` | विषय | जानकारी | | ------------- | --------------------------------------------------------------------- | | टाइमिंग | पोस्ट-कॉल वेबहुक जैसा ही ट्रांसक्रिप्ट-आधारित बिल्डर | | ट्रांसक्रिप्ट | `transcript` फिर भी लौटता है; `otlp_traces` अतिरिक्त है | | फ़ाइल URL | स्पैन एट्रिब्यूट में साइन किए गए URL करीब 15 मिनट बाद समाप्त होते हैं | **`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' ``` संभावित स्पैन नामों में `elevenlabs.conversation`, `elevenlabs.recv.user_transcript` और `elevenlabs.recv.agent_response` शामिल हैं। ## मॉनिटरिंग WebSocket > **Note** > > रीयल-टाइम मॉनिटरिंग के लिए Enterprise वर्कस्पेस या `realtime-monitoring` फ़ीचर फ़्लैग चाहिए। > कॉन्फ़िगरेशन, कंट्रोल कमांड और ऐक्सेस ज़रूरतों के लिए [रीयल-टाइम मॉनिटरिंग](/docs/hi/eleven-agents/guides/realtime-monitoring) देखें। बातचीत जारी रहने के दौरान OTLP JSON के रूप में OpenTelemetry ट्रेस डेटा स्ट्रीम करें। हर संदेश एक छोटा `resourceSpans` बैच होता है, कॉल खत्म होने के बाद का एक ट्रेस नहीं। ``` wss://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/monitor?events_format=opentelemetry ``` ऑथेंटिकेशन के लिए `CONVAI_WRITE`, `xi-api-key` (या `Authorization`) और एजेंट वर्कस्पेस पर **EDITOR** ऐक्सेस चाहिए। बातचीत शुरू होने के बाद कनेक्ट करें। ### एजेंट पर मॉनिटरिंग चालू करें कॉल से पहले `monitoring_enabled: true` सेट करें और `monitoring_events` कॉन्फ़िगर करें। [रीयल-टाइम मॉनिटरिंग](/docs/hi/eleven-agents/guides/realtime-monitoring#configuration) देखें। ### OpenTelemetry फ़ॉर्मैट के साथ कनेक्ट करें मॉनिटरिंग WebSocket URL में `events_format=opentelemetry` जोड़ें। > **Warning** > > कस्टम `monitoring_events` कॉन्फ़िगर होने पर VAD, टर्न प्रॉबेबिलिटी और पिंग इवेंट उपलब्ध नहीं होते। > स्ट्रीम में केवल टेक्स्ट और मेटाडेटा शामिल होता है, रॉ ऑडियो नहीं। ### सेशन प्रोटोकॉल 1. ऑथेंटिकेशन हेडर के साथ कनेक्ट करें। 2. `{"type": "connected"}` पाएं। 3. एक रूट स्पैन बैच पाएं (`elevenlabs.conversation`, `elevenlabs.source` = `monitoring`)। 4. कैश किया गया इतिहास (करीब पिछले 100 इवेंट) पाएं, फिर `{"type": "history_complete"}`। 5. इवेंट होने पर लाइव स्पैन बैच पाएं। `events_format=json` (डिफ़ॉल्ट) के साथ WebSocket `resourceSpans` की जगह रॉ क्लाइंट इवेंट लौटाता है। कंट्रोल कमांड [रीयल-टाइम मॉनिटरिंग](/docs/hi/eleven-agents/guides/realtime-monitoring#control-commands) से मेल खाते हैं। ### ट्रेस संरचना ```text elevenlabs.conversation ├── elevenlabs.turn.0 │ ├── elevenlabs.event.user_transcript │ └── elevenlabs.tool.{name} └── elevenlabs.turn.1 ``` | पहलू | पोस्ट-कॉल और GET | मॉनिटरिंग | | -------------- | --------------------------------- | ----------------------------------------------- | | ग्रैन्युलैरिटी | हर वेबहुक या अनुरोध पर एक ट्रेस | हर बातचीत पर कई संदेश | | इवेंट स्पैन | ट्रांसक्रिप्ट टर्न | `elevenlabs.event.{type}` | | टर्न ग्रुपिंग | ट्रांसक्रिप्ट क्रम में अंतर्निहित | स्पष्ट `elevenlabs.turn.N` | | क्रम | स्थिर ट्रांसक्रिप्ट क्रम | इवेंट सख्त कालानुक्रमिक क्रम से बाहर आ सकते हैं | स्ट्रक्चर्ड इवेंट समर्पित एट्रिब्यूट से मैप होते हैं (उदाहरण के लिए `elevenlabs.user.text`, `elevenlabs.agent.text`)। अज्ञात इवेंट ट्रंकेट किए गए JSON के साथ `elevenlabs.event.data` इस्तेमाल करते हैं। > **Info** > > यह न मानें कि इवेंट क्रम बोलने के क्रम से मेल खाता है। लाइव स्पैन को पोस्ट-कॉल डेटा से उसी > `traceId` के ज़रिए कोरिलेट करें। ### कनेक्शन उदाहरण **`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()) ``` ## OTLP JSON संरचना सभी स्रोतों के OpenTelemetry ट्रेस एक ही 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 } } ] } ] } ] } ``` ## सीमाएं * आपके OTLP gRPC एंडपॉइंट पर कोई सीधा पुश नहीं। * पेलोड OTLP एक्सपोर्ट जैसे JSON होते हैं, नेटवर्क पर रॉ protobuf नहीं। ## संबंधित दस्तावेज़ * [पोस्ट-कॉल वेबहुक](/docs/hi/eleven-agents/workflows/post-call-webhooks) * [रीयल-टाइम मॉनिटरिंग](/docs/hi/eleven-agents/guides/realtime-monitoring)