OpenTelemetry 추적

ElevenLabs Agents는 대화를 OTLP JSON(resourceSpans)으로 인코딩된 OpenTelemetry 트레이스로 내보낼 수 있습니다. Datadog, Grafana Tempo, Honeycomb 또는 OTLP를 수집하는 모든 백엔드로 전달하세요.

개요

세 가지 방식으로 트레이스를 내보낼 수 있습니다. 세 방식 모두 대화당 동일한 트레이스 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입니다(JSON 트랜스크립트를 반환하는 post_call_transcription이 아님).

웹훅 페이로드

{
  "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 형식을 요청하면 통화 후 OpenTelemetry 웹훅과 동일한 otlp_traces 객체와 전체 대화 모델을 받을 수 있습니다.

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

대화가 진행되는 동안 OpenTelemetry 트레이스 데이터를 OTLP JSON으로 스트리밍합니다. 각 메시지는 통화 종료 시의 단일 트레이스가 아니라 작은 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 엔드포인트로 직접 푸시할 수 없습니다.
• 페이로드는 전송 중인 원시 protobuf가 아니라 OTLP 내보내기 형태의 JSON입니다.

관련 문서

• 통화 후 웹훅
• 실시간 모니터링