Claude OpenTelemetry 추적: API 및 SDK 설정 가이드

Anthropic은 Claude Managed Agents, Messages API 및 Claude SDK를 위한 OpenTelemetry 추적 내보내기 기능을 도입했습니다. 2026년 10월 14일 발표된 이 기능은 공개 베타이며, OTLP를 지원하는 관측 가능성 플랫폼으로 표준 추적 데이터를 전송합니다.

목적은 실용적입니다. 에이전트를 호출한 애플리케이션과 함께 해당 에이전트의 모델 호출 및 도구 활동을 추적하는 것입니다. 팀은 지연 시간, 실패 및 토큰 사용량을 서로 다른 위치에서 조사하는 대신 기존 관측 가능성 시스템에서 관련 스팬을 검사할 수 있습니다.

두 가지 설정 경로와 하나의 추적 모델

**트레이스(trace)**는 시스템을 통과하는 요청의 경로를 기록합니다. **스팬(span)**은 모델 호출이나 도구 실행처럼 해당 경로 안의 하나의 작업을 기록합니다. Claude의 스팬은 OpenTelemetry의 GenAI 의미 체계를 따르므로, 호환 도구는 여러 모델 제공업체의 데이터를 해석하는 데 도움을 받을 수 있습니다.

Claude 트레이스는 에이전트 단계를 디버깅, 비용 추적 및 평가와 연결합니다

출처: Anthropic. 이 다이어그램은 측정된 성능 결과가 아니라 트레이스 구조와 분석 워크플로를 보여 줍니다.

데이터를 수집하는 두 가지 상호 보완적 방법이 있습니다.

기능	SDK 추적	API 추적
구성	애플리케이션 코드 및 트레이서 제공업체	Claude Console 대상
Claude의 특별 권한	필요 없음	대상을 추가하거나 변경하려면 관리자 역할 필요
요청 내부의 모델 실행	SDK 추적만으로는 개별 노출되지 않음	포함됨
Managed Agents 턴	SDK 추적만으로는 노출되지 않음	포함됨
API가 실행하는 도구	SDK 추적만으로는 노출되지 않음	포함됨
SDK 도구 실행기가 실행하는 클라이언트 도구	포함됨	API 추적만으로는 캡처되지 않음
자체 호스팅 샌드박스의 도구	지원되는 SDK 워커를 통해 포함됨	API 추적만으로는 캡처되지 않음
파일 업로드와 같은 기타 클라이언트 API 작업	포함됨	API 추적만으로는 캡처되지 않음

두 경로 모두 요청 스팬과 토큰 사용량을 기록합니다. 함께 사용하면 클라이언트 작업과 Claude API 내부에서 수행되는 작업을 모두 확인할 수 있습니다. 두 데이터를 동일한 백엔드로 전송하면 백엔드에서 이들의 관계도 표시할 수 있습니다.

Console에서 API 추적 구성하기

독립적인 API 트레이스를 받기 위해 일반 요청 코드를 변경할 필요는 없습니다. 관리자는 Claude가 트레이스를 전송할 위치를 지정하는 대상을 추가합니다.

Claude Console에서 조직의 OpenTelemetry 설정을 열고 대상 추가를 선택합니다.
목록에 있는 제공업체를 선택하거나 사용자 지정 OTLP/HTTP 엔드포인트 및 인증 헤더를 입력합니다.
대상에 포함할 워크스페이스를 선택하고 콘텐츠 모드를 지정합니다.
대상을 저장하고 테스트를 실행한 뒤 anthropic.test 스팬이 도착했는지 확인합니다.
포함된 워크스페이스에서 요청을 전송하고 대상 상태 및 생성된 트레이스를 확인합니다. API 스팬은 service.name = claude-platform을 사용합니다.

사용자 지정 대상의 경우, 문서화된 요구 사항은 443 포트의 HTTPS 호스트 이름에서 protobuf를 수신하는 OTLP/HTTP 엔드포인트입니다. 일반적인 4318 포트에서만 수신하는 Collector는 적절한 HTTPS 노출 또는 리버스 프록시가 필요합니다. 자격 증명은 헤더 값에 넣어야 합니다.

기본 엔드포인트에는 일반적으로 /v1/traces를 포함하지 않습니다. Claude가 이를 추가하기 때문입니다. 고급 트레이스 엔드포인트는 경로를 재정의할 수 있지만 동일한 호스트를 사용해야 합니다. 비공개 주소 엔드포인트와 리디렉션은 일반적인 전송 대상으로 지원되지 않습니다.

애플리케이션에서 SDK 추적 구성하기

SDK 추적은 현재 지원되는 Claude SDK를 설치하고, 추적할 첫 호출 이전에 OpenTelemetry 트레이서 제공업체를 등록하는 것으로 시작합니다. 애플리케이션은 스팬을 관측 가능성 백엔드로 전달하는 익스포터를 제공합니다. 따라서 “자동 SDK 내보내기”가 새로운 애플리케이션이 트레이서 제공업체와 대상 익스포터 없이 데이터를 어딘가로 전송한다는 의미는 아닙니다.

콘솔 익스포터는 원격 플랫폼에 연결하기 전에 로컬 계측을 확인하는 데 도움이 될 수 있습니다. 구성 후 SDK는 요청 스팬과 도구 실행기를 통해 실행된 도구의 스팬을 생성합니다. 애플리케이션 스팬 내부에서 이루어진 호출은 해당 스팬 아래에 중첩될 수 있습니다.

베타 기간에는 SDK 옵션, 스팬 이름 및 속성이 변경될 수 있습니다. Anthropic은 팀이 이러한 변경 사항을 언제 적용할지 선택할 수 있도록 SDK 버전을 고정할 것을 권장합니다.

트레이스 결합과 에이전트 세션 이해하기

SDK는 API 서버 스팬이 SDK 클라이언트 스팬 아래에 위치할 수 있도록 트레이스 컨텍스트를 전파합니다. Claude Platform on AWS에 대한 요청은 예외입니다. 해당 플랫폼은 아직 동일한 트레이스 컨텍스트 결합 동작을 지원하지 않으므로 API 스팬이 별도의 트레이스에 나타납니다.

Managed Agents 세션은 Sessions API 요청 스팬, 에이전트 턴 스팬, 모델 요청, API가 실행하는 도구 및 결과 평가를 노출합니다. 하나의 세션은 여러 트레이스와, 멀티에이전트 작업 시 여러 스레드에 걸칠 수 있습니다. 문서는 세션에는 anthropic.session.id, 스레드에는 gen_ai.conversation.id로 그룹화할 것을 권장합니다.

Claude Code, Agent SDK 및 Cowork에는 각각 고유한 모니터링 문서가 있습니다. 새로운 플랫폼 기능을 모든 제품의 기존 계측 지침을 대체하는 것으로 간주해서는 안 됩니다.

콘텐츠 모드, 제한 및 데이터 처리

각 Console 대상과 SDK 클라이언트에는 콘텐츠 모드가 있습니다. 기본값인 메타데이터만은 식별자, 타이밍, 상태, 토큰 수 및 도구 이름, 도구 설명, MCP 서버 이름과 같은 일부 설명 텍스트를 포함합니다. 모델 프롬프트와 응답은 제외하지만, 내보낸 모든 필드에 애플리케이션이 제공한 텍스트가 없음을 보장하는 것은 아닙니다.

전체 콘텐츠는 프롬프트와 응답도 포함합니다. 이 모드는 실패한 상호작용을 디버깅하고 실제 트래픽을 기반으로 평가를 구축하는 데 유용하지만, 대화 콘텐츠를 자체 접근 권한 및 보존 설정이 있는 별도의 시스템으로 이동시킵니다.

콘텐츠 크기와 잘림

기본 콘텐츠 제한은 스팬당 0.75MB입니다. Anthropic은 이것이 약 200,000토큰의 영어 컨텍스트에 적합하며, 많은 관측 가능성 서비스와 프록시가 사용하는 1MB 요청 제한보다 낮게 유지된다고 설명합니다. 전체 100만 토큰 컨텍스트에는 약 4MB가 필요할 수 있으므로 기본값만으로는 모든 대형 프롬프트를 온전히 보존하기에 충분하지 않습니다.

스팬이 콘텐츠 제한을 초과하면 SDK 또는 API가 내용을 줄이고 anthropic.content.truncated를 true로 설정합니다. 요청 스팬은 시스템 프롬프트와 가장 이른 메시지부터 삭제합니다. 도구 스팬은 도구 결과의 끝부분부터 블록을 삭제합니다. 이미지와 문서는 완전한 미디어 페이로드가 아닌 유형으로 표시됩니다.

SDK는 제한을 제어하기 위해 traces.max_content_bytes를 사용합니다. Console 대상은 고급 설정에서 최대 콘텐츠 크기를 제공하며, 목록에 있는 제공업체에는 제공업체별 기본값이 있을 수 있습니다.

무료 · We0 AI 사용하기

몇 분 만에 쇼케이스 사이트를 만들고 리드를 늘리세요

아이디어를 한 문장으로 입력하면 We0 AI가 쇼케이스 사이트, 페이지, CMS를 생성하고 출시 후 고객과 트래픽 확보를 돕습니다.

무료 등록을 위한 하나의 완전한 프로젝트 생성

하나의 완전한 생성 흐름을 시도하고 첫 번째 프로젝트 초안을 빠르게 보는 데 가장 적합합니다.

무제-1

공들여 나열한 것

채우다

반지름

생성 중

제한된 데이터와 Zero Data Retention

Anthropic과 HIPAA, FERPA 또는 K–12 데이터 처리 제한이 적용된 조직은 선택한 콘텐츠 모드와 관계없이 API 대상을 통해 메타데이터만 내보냅니다. 문서에 따르면 이 제한은 SDK 스팬에는 적용되지 않으므로 SDK 구성은 별도로 검토해야 합니다.

전체 콘텐츠 내보내기는 API가 전송까지 내보내기 콘텐츠를 메모리에 보관하므로, 자격을 갖춘 Zero Data Retention Messages API 요청과 함께 사용할 수 있습니다. Managed Agents는 Zero Data Retention 대상이 아니며, OpenTelemetry를 활성화해도 보존 조건은 변경되지 않습니다.

토큰 이중 집계 방지하기

하나의 요청은 여러 스팬에 토큰 사용량을 기록할 수 있습니다. 따라서 트레이스의 모든 스팬을 합산하면 사용량을 과대평가할 수 있습니다.

Messages API 요청에 SDK와 API 스팬이 모두 있는 경우 API 소스를 사용합니다. 해당 소스 안에서는 요청 스팬 또는 모델 요청 스팬을 합산하되 둘 다 합산하지 않아야 하며, 컴팩션은 문서의 구체적인 규칙을 적용해야 합니다. Managed Agents의 경우 관련 API 스팬은 모델 요청 및 결과 평가입니다.

전송 재시도로 인해 중복 스팬이 생성될 수도 있습니다. 백엔드가 이미 처리하지 않는 경우 트레이스 ID와 스팬 ID를 사용해 중복을 제거합니다.

내보낸 트레이스는 디버깅 기록이지 완전성이 보장되는 청구 원장이 아닙니다. 전송은 최선의 노력 방식이며, 샘플링으로 요청이 누락될 수 있습니다. 완전한 API 키 사용량 추적이 필요한 팀에는 Anthropic이 Usage API를 안내합니다.

관측 가능성 통합과 고객 사례

Anthropic은 애플리케이션 로그 및 메트릭과 함께 에이전트 트레이스를 보기 위한 도구로 Grafana Cloud, Honeycomb, Sentry 및 Splunk를 언급합니다. 또한 트레이스를 평가 및 품질 개선과 연결하는 워크플로를 위해 Arize AI, Braintrust, Datadog, Langfuse, LangSmith, New Relic 및 PostHog를 나열합니다. Databricks Unity Gateway는 조직 단위 가시성 도구로 강조됩니다.

이는 예시이며, 호환되는 도구의 전체 목록은 아닙니다. 필요한 표준 OTLP 내보내기를 수용할 수 있다면 다른 도구도 데이터를 받을 수 있습니다.

발표에는 Foxglove, Ramp, Sterling Labs 및 FloQast의 고객 발언이 포함되어 있습니다. 이들의 사용 사례에는 로보틱스 디버깅, 시장 에이전트 분석 및 회계 워크플로 추적이 포함됩니다.

Ramp는 Langfuse 트레이스를 평가하고 수정안을 제안하는 Reflect라는 내부 시스템을 설명합니다. 해당 기업의 엔지니어는 일부 에이전트에서 토큰 사용량 10~20% 감소와 세션 속도 30% 향상을 보고했습니다. 이는 해당 개선 워크플로에 대한 고객 보고 결과이며, 트레이스 내보내기만 활성화하면 이러한 효과가 발생한다는 보장은 아닙니다.

자주 묻는 질문

Claude OpenTelemetry 트레이스 내보내기란 무엇인가요?

Claude API 요청, 에이전트 턴, 모델 호출 및 지원되는 도구 활동을 설명하는 표준 스팬을 관측 가능성 백엔드로 전송합니다. 이 기능은 공개 베타이며 별도의 API 및 SDK 추적 경로를 지원합니다.

추적을 활성화하려면 관리자 역할이 필요한가요?

Claude Console에서 API 추적 대상을 추가하거나 변경하려면 관리자 역할이 필요합니다. SDK 추적은 애플리케이션 코드에서 구성하며, Claude 조직의 특별 권한은 필요하지 않습니다.

프롬프트와 응답은 기본적으로 내보내지나요?

아니요. 기본 모드는 메타데이터만입니다. 전체 콘텐츠는 프롬프트와 응답을 추가하지만, 콘텐츠 제한 및 특정 조직에 적용되는 문서화된 제한 사항의 영향을 받습니다.

자체 호스팅 OpenTelemetry Collector를 사용할 수 있나요?

예. API 대상이 문서화된 네트워크 및 프로토콜 요구 사항을 충족한다면 사용할 수 있습니다. 특히 API 내보내기에는 비공개 Collector 리스너만이 아니라 443 포트의 공용 HTTPS 호스트 이름을 통해 연결 가능한 OTLP/HTTP protobuf 수신기가 필요합니다.

SDK와 API 스팬이 동일한 트레이스에 표시될 수 있나요?

예. 트레이스 컨텍스트가 전파되고 스팬이 동일한 관측 가능성 백엔드에 도달하면 가능합니다. Claude Platform on AWS에 대한 요청의 API 스팬은 현재 별도 트레이스에 표시됩니다.

트레이스로 청구 총액을 위해 Usage API를 대체할 수 있나요?

아니요. 트레이스는 샘플링되거나 누락되거나 두 번 이상 전송될 수 있습니다. 분석에는 문서화된 집계 규칙을 사용하고, 완전한 사용량 회계가 필요할 때는 Usage API를 사용하세요.

요약

Claude의 OpenTelemetry 베타는 모델 호출과 에이전트 도구를 팀이 이미 사용하는 추적 시스템에 연결합니다. API 추적은 서버 측 활동을 노출하고, SDK 추적은 클라이언트 작업 및 도구를 추가합니다. 트레이스 결합이 지원되는 경우 두 기능을 결합하면 가장 명확한 애플리케이션 타임라인을 제공할 수 있습니다.

콘텐츠 모드를 신중하게 선택하고, 잘림 및 전송 상태를 확인하며, 단일한 적절한 소스에서 토큰을 집계하세요. 추적은 가시성을 개선하지만, 완전한 사용량 회계와 보존 제어는 여전히 별도의 책임입니다.