Anthropic Claude OpenTelemetry Export (베타) 사용법: Messages API 및 Managed Agents

2026년 10월 14일, Anthropic은 OpenTelemetry Export를 베타 버전으로 공개했습니다. 이를 통해 Messages API로의 요청과 Claude Managed Agents 세션을 자체 관측 가능성(observability) 기반에서 추적할 수 있게 됩니다.

Claude SDK는 Python / TypeScript / C# / Go / Java / PHP / Ruby의 7개 언어에서 클라이언트 측 스팬을 출력합니다.

LLM 앱이나 에이전트는 '어떤 호출이 느린지', '어떤 단계에서 실패했는지'가 눈에 잘 띄지 않는 경향이 있습니다. OpenTelemetry(OTel)이라는 표준 규격으로 트레이스를 확보할 수 있다면, 기존 모니터링 기반에 LLM 호출을 추가하여 다른 서비스와 같은 화면에서 조사할 수 있습니다.

📌 영향을 받는 사람

• Messages API를 프로덕션 서비스에서 사용하며 지연 시간이나 실패 원인을 추적하고 싶은 사람
• Claude Managed Agents로 에이전트를 운영하는 사람
• Python / TypeScript 등 7개 언어의 Claude SDK를 사용하는 개발자
• 이미 OpenTelemetry 대응 모니터링 기반을 보유한 SRE 및 플랫폼 팀

참고로, 이 기능은 베타 버전입니다. 사양이 변경될 수 있으므로, 프로덕션 도입 시에는 공식 문서를 통해 최신 정보를 확인해 주십시오.

트레이스는 '클라이언트 측(SDK)'과 'API 측'의 2개 계통에서 나옵니다. 이들을 결합함으로써 엔드투엔드 가시화가 가능하다고 생각됩니다.

💡 팁

SDK 측의 스팬만으로도 '앱에서 본 호출 시간'은 추적할 수 있다고 생각됩니다. 반면, API 측 스팬과 결합하면 에이전트 실행이나 API 호출을 일관되게 볼 수 있습니다. 먼저 SDK 측부터 시도해 보고, 다음으로 Console에서 전송지를 추가하는 단계적인 도입이 현실적입니다.

💡 팁

CLAUDE.md에 관측 가능성 정책을 작성해 두면, 팀원이나 AI 코딩 에이전트가 같은 전제하에서 작업할 수 있습니다. 예: 'OpenTelemetry Export (베타)는 Messages API와 Managed Agents 세션이 대상입니다. SDK는 7개 언어에서 스팬을 출력합니다. API 측 스팬은 Console에서 전송지 설정이 필요합니다'.

⚠️ 주의

제공된 정보에는, SDK에서의 스팬 활성화 방법이나 설정 키, Console의 구체적인 화면 조작은 포함되어 있지 않습니다. 따라서 확정된 구현 코드는 게재하지 않습니다. 아래는 일반적인 OpenTelemetry(Python)의 준비 코드이며, 수신처(Collector 측)를 준비하는 예시입니다. Claude SDK 고유의 활성화 절차는 공식 문서를 참조해 주십시오.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
...

• 2026년 10월 14일,
  OpenTelemetry Export가 베타 버전으로 공개되었습니다. - 대상은
  Messages API 요청과 Claude Managed Agents 세션입니다. -
  Claude SDK는 7개 언어(Python / TypeScript / C# / Go / Java / PHP / Ruby)에서 클라이언트 측 스팬을 출력합니다. -
  API 측의 스팬을 수신하려면, Claude Console에서 OpenTelemetry 전송지(destination)를 추가해야 합니다. - SDK 측과 API 측의 스팬을 결합하면, 에이전트 실행이나 API 호출을 엔드투엔드로 시각화할 수 있을 것으로 생각됩니다.
• 기존 코드에 파괴적인 변경은 없으며, 필수적으로 대응할 필요는 없습니다. 우선 개발 환경에서 테스트해보고, 베타 버전의 사양 변경에 대비하는 것이 좋습니다.

LLM 앱이 프로덕션 환경에 배포될수록, '가시성(visibility)'은 품질과 운영 비용에 직결됩니다. 이미 OpenTelemetry 기반을 갖춘 팀이라면, 먼저 SDK 측 스팬부터 시도해 보는 것을 추천합니다.