Claude Platform의 OpenTelemetry 내보내기는 모델 요청과 도구 실행을 기존 관측 도구의 타임라인으로 보내는 기능입니다. 에이전트가 느리거나 실패했을 때 최종 답변만 보는 대신, 어떤 모델 호출과 도구 실행에서 문제가 생겼는지 따라갈 수 있습니다.
Anthropic의 발표 ↗는 Managed Agents·Messages API·Claude SDK의 추적을 공개 베타로 소개합니다. 이 글은 연결 절차와 함께, 트레이스가 빠졌을 때 확인할 조건, 토큰을 중복 집계하지 않는 규칙, 프롬프트를 외부로 보내는 데이터 경계를 설명합니다.
기준: 2026-10-21 확인 · 공개 베타. 발표 페이지의 구조화 데이터상 게시일은 2026-10-14입니다. 베타의 SDK 옵션과 span 스키마는 바뀔 수 있으므로 사용 버전을 고정하고 업그레이드 때 쿼리도 확인합니다.
최종 응답 로그만으로는 느린 단계를 구분하기 어렵습니다
고객 문의에 답하는 에이전트를 생각해 보겠습니다. 한 번의 화면 요청 안에서 모델 호출, 사내 문서 검색, 주문 조회, 재시도가 이어집니다. “응답에 12초 걸렸다”는 기록만으로는 모델이 느렸는지, 주문 조회가 지연됐는지 구분할 수 없습니다.
OpenTelemetry(OTel)는 이런 실행 정보를 여러 도구에서 읽을 수 있게 만드는 벤더 중립 표준입니다. trace는 요청이 시스템을 통과한 실행 흐름이고, span은 그 안의 한 작업입니다. 모델 요청과 도구 호출을 각각 span으로 기록하면 부모·자식 관계와 시간을 함께 볼 수 있습니다. OTLP는 이 데이터를 수집기로 전달하는 프로토콜입니다. (공식 개요 ↗)
출처: Agent observability on the Claude Platform ↗. 왼쪽은 애플리케이션과 Claude 및 다른 공급자의 작업을 함께 보여 줍니다. 오른쪽은 오류가 난 도구 찾기, 요청별 토큰 사용 확인, 실행 사례를 평가에 재사용하는 흐름입니다. 그림의 토큰 수치는 제품 가격이나 성능 비교값이 아닙니다.
관측성은 도구를 더 많이 실행할 권한을 주는 기능과 다릅니다. 먼저 실패와 지연을 확인하고, 검증된 범위에서 접근 권한을 조정해야 합니다. 트레이스가 있다고 잘못된 외부 동작을 자동으로 막는 것은 아닙니다.
API 추적과 SDK 추적은 서로 다른 구간을 봅니다
공식 문서 ↗는 두 경로를 구분합니다.
API 추적은 Claude Console에서 destination을 설정합니다. destination은 수신할 OTLP 주소, 인증 헤더, 내보낼 작업공간과 콘텐츠 범위를 담은 전송 대상입니다. API 서버가 Messages API 요청, 내부 모델 실행, 서버에서 실행하는 도구와 Managed Agents의 turn 등을 내보냅니다.
SDK 추적은 애플리케이션에서 tracer provider를 등록합니다. tracer provider는 span을 만들고 exporter로 넘기는 OTel 객체입니다. SDK가 보낸 요청과 tool runner가 실행한 클라이언트 도구를 볼 수 있습니다. 애플리케이션에서 직접 실행하는 모든 함수를 자동으로 추적한다는 뜻은 아닙니다.
어느 쪽부터 시작할지는 보고 싶은 구간으로 정합니다.
- 서버 내부 모델 실행·서버 도구가 궁금하다면 API destination부터 설정합니다.
- 클라이언트 도구 실행과 애플리케이션 문맥이 필요하다면 SDK 추적을 추가합니다.
- 사용자 요청부터 모델·도구까지 이어 보려면 두 경로를 같은 관측 플랫폼으로 보내고 trace context를 연결합니다.
API 추적의 지원 플랫폼은 문서상 Claude Platform과 Claude Platform on AWS입니다. SDK 추적의 지원 범위는 별도로 확인합니다. Bedrock이나 Google Cloud에서 SDK를 쓴다고 동일한 서버 측 내보내기가 생기는 것으로 해석하지 않습니다.
Claude Code·Agent SDK·Cowork의 모니터링도 각각 별도 문서가 있습니다. 여기서 다루는 Claude API SDK 설정을 Claude Code의 설정과 혼동하지 않습니다.
Console에서 연결한 뒤 테스트 span과 실제 요청을 확인합니다
첫 연결은 기존 관측 플랫폼이나 운영 중인 OpenTelemetry Collector를 사용합니다. 새 대시보드나 별도 프록시를 직접 만들 필요는 없습니다. 공식 문서 ↗는 Grafana·Langfuse·Sentry 등과의 연결을 안내하며, 표준 OTLP 수신점도 지원합니다. 도구 선택 전에 기존 플랫폼의 수집량·보관 비용을 확인합니다.
준비 조건
API 설정 문서 ↗에 따르면 destination을 추가·변경하려면 Claude Console 조직의 admin 권한이 필요합니다. developer는 볼 수 있습니다.
수신점은 다음 조건을 갖춰야 합니다.
- OTLP/HTTP와 protobuf를 받는 HTTPS 주소이며 포트는 443입니다.
- IP 주소 대신 호스트 이름을 사용하고, 공개적으로 접근할 수 있어야 합니다.
- 수신 플랫폼이 요구하는 인증 헤더를 준비합니다.
자체 Collector의 기본 OTLP/HTTP 포트 4318을 그대로 Console에 입력하면 이 조건과 맞지 않습니다. 조직이 승인한 HTTPS 수신 계층을 구성하고, 인증 없이 Collector를 공개하지 않습니다.
연결 순서
- Console의 OpenTelemetry 설정 ↗에서 Add destination을 선택합니다.
- Provider에서 기존 플랫폼을 선택합니다. 목록에 없으면 Custom으로 설정합니다.
- endpoint와 인증을 입력합니다. Custom의 기본 endpoint에는 /v1/traces를 붙이지 않습니다. API가 덧붙입니다. 별도 경로가 필요한 경우에만 Advanced settings의 OTLP traces endpoint URL을 사용합니다.
- Content mode는 먼저 Metadata only를 선택합니다. Workspaces는 테스트 작업공간을 Selected로 지정해 전송 범위를 제한합니다.
- 저장 뒤 More actions의 Test를 실행합니다. 수신 도구에서 anthropic.test span이 도착했는지 확인합니다.
- 대상 작업공간의 playground ↗에서 민감 정보 없는 Messages API 요청을 보냅니다. 모델 호출에는 일반 API 사용료가 발생할 수 있습니다.
- Console의 Delivery가 Healthy인지 보고, 수신 도구에서 service.name = claude-platform으로 실제 요청의 span을 찾습니다. 상태 반영에는 약 1분이 걸릴 수 있습니다.
다음은 작성자 구성 설정 예시입니다. 실제 수신 주소나 비밀값이 아닙니다.
Provider: Custom
OTLP endpoint URL: https://otel.example.com/ingest
Content mode: Metadata only
Workspaces: Selected → 테스트 작업공간
기본 규칙으로 전송되는 경로:
https://otel.example.com/ingest/v1/traces인증값은 URL 쿼리나 경로가 아니라 Request headers의 값에 넣습니다. 문서상 저장 후에는 헤더 값을 다시 표시하지 않습니다. 잘못된 값으로 저장했다면 플랫폼에서 발급한 값을 안전하게 다시 입력합니다.
공식 영상으로 설정 흐름 보기
출처: Claude 공식 OpenTelemetry on the Claude Platform ↗. 발표문에 첨부된 소개 영상입니다. 연결할 destination과 관측 도구에서 확인할 트레이스의 관계를 위 절차와 함께 살펴볼 수 있습니다. 영상 없이 따라 하려면 테스트 span과 실제 요청 span이 모두 도착했는지를 기준으로 확인합니다.
한 trace로 묶으려면 애플리케이션 문맥을 전달합니다
API span은 기본적으로 자체 trace에 들어갑니다. DB 조회·HTTP 처리 같은 애플리케이션 span과 자동으로 연결된다고 가정하면 안 됩니다. API는 요청의 W3C traceparent 헤더에서 문맥을 읽습니다. (연결 문서 ↗)
SDK 경로라면 OTel tracer provider를 먼저 등록하고, 애플리케이션의 활성 span 안에서 SDK를 호출합니다. SDK와 API의 span을 같은 관측 도구로 보내면 애플리케이션 → SDK → API의 계층을 이어 볼 수 있습니다. SDK 설치와 언어별 설정은 공식 SDK 가이드 ↗를 따릅니다.
traceparent의 sampled 플래그가 꺼져 있으면 API는 그 요청과 하위 span을 내보내지 않습니다. destination이 Healthy인데 특정 요청만 안 보인다면 샘플링과 작업공간 범위부터 확인합니다.
Managed Agents의 세션 전체도 반드시 trace 하나와 같지는 않습니다. 나중 요청이 새 trace를 시작하거나 여러 thread가 생길 수 있습니다. 문서상 세션 전체는 anthropic.session.id, 한 thread는 gen_ai.conversation.id로 묶어 봅니다. 한 trace만 찾아서 세션의 나머지 실행이 사라졌다고 판단하지 않습니다.
토큰은 모든 span을 더하면 중복됩니다
같은 Messages API 요청에 SDK의 CLIENT span과 API의 SERVER span이 생길 수 있습니다. 둘 다 이름이 anthropic.messages.create이고 토큰 사용량을 담습니다. API 요청 아래의 anthropic.model_request에도 관련 사용량이 나타납니다.
토큰 집계 지침 ↗은 요청마다 한 출처와 한 집계 계층을 선택하라고 설명합니다.
- SDK와 API를 함께 수집한 Messages 요청: API 쪽을 기준으로 합니다. CLIENT와 SERVER를 모두 더하지 않습니다.
- Messages API의 서버 span: 요청 span 또는 내부 model_request span 중 하나만 합산합니다.
- Managed Agents: model_request와 session.outcome_evaluation span을 합산합니다.
- 재전송된 동일 span: trace ID와 span ID 조합으로 중복을 제거합니다.
일반적인 Messages 요청에서 같은 사용량이 CLIENT 1,000토큰, SERVER 1,000토큰으로 보인다고 가정해 보겠습니다. 이 둘을 합쳐 2,000토큰으로 계산하면 중복입니다. 이는 집계 원리를 설명하기 위한 가상 예시입니다.
gen_ai.usage.input_tokens에는 프롬프트 캐시에 읽고 쓴 토큰도 포함됩니다. 여기에 캐시 속성값을 다시 더하지 않습니다. compaction을 사용한다면 별도 토큰 반영 규칙도 필요합니다. API의 compaction span을 합산했다면 요청 span의 compaction 집계 속성을 또 더하지 않습니다. SDK만 수집하는 경우는 공식 지침의 별도 합산 조건을 확인합니다.
토큰 수를 비용으로 바꾸려면 모델·캐시·과금 조건도 적용해야 합니다. 트레이스의 토큰 합계를 그대로 청구액이라고 표시하지 않습니다.
Metadata only도 전송 내용을 점검해야 합니다
콘텐츠 모드 ↗의 기본값은 Metadata only입니다. 식별자·시간·상태·토큰 수 외에도 직접 정한 에이전트와 도구의 이름·설명, MCP 서버 이름 같은 텍스트가 포함될 수 있습니다. 프롬프트가 빠졌다고 민감 정보가 전혀 없다고 보장할 수는 없습니다.
Full content는 프롬프트와 응답까지 포함합니다. 실패한 대화를 평가 사례로 만들기 쉽지만, 외부 관측 플랫폼이 그 내용을 자체 접근 권한과 보관 정책으로 저장합니다. Anthropic의 데이터 정책과 수신 플랫폼의 데이터 정책을 따로 확인해야 합니다.
첫 도입에서는 다음 경계를 정합니다.
- 도구 이름·설명·리소스 식별자에 고객 정보나 비밀값을 넣지 않습니다.
- 콘텐츠 수집이 꼭 필요한 작업공간과 열람자를 제한합니다.
- 수신 플랫폼의 보관 기간·삭제·접근 권한을 정합니다.
- 실제 고객 데이터보다 비식별 테스트 데이터로 먼저 전송을 확인합니다.
Full content도 원문 전체를 항상 보존하지는 않습니다. 기본 콘텐츠 한도는 span당 0.75MB이며, 초과하면 줄이고 anthropic.content.truncated = true를 남깁니다. 이미지와 문서는 타입만 나타납니다. 잘린 입력을 완전한 대화로 취급해 평가하면 실패 원인을 오판할 수 있습니다.
HIPAA·FERPA·K-12 데이터 취급 제한이 있는 조직의 destination은 콘텐츠 모드와 무관하게 메타데이터만 내보냅니다. 이 제한이 SDK span에도 동일하게 적용된다고 가정하지 않습니다. 또한 Messages API의 ZDR 조건을 Managed Agents에 그대로 적용하지 않습니다. 문서상 Managed Agents는 ZDR 대상이 아닙니다.
전송 상태가 Healthy여도 완전한 감사 기록은 아닙니다
전달 규칙 ↗은 중복 수신 가능성과 best-effort 전달을 함께 설명합니다. 재시도로 같은 span이 두 번 올 수 있고, 전달 전에 잃어버린 span은 다시 보낼 수 없습니다. Healthy는 마지막 전달의 성공이지 전체 실행의 빠짐없는 보존을 뜻하지 않습니다.
API 사용량이나 키 유출 감시는 Usage API ↗로도 확인합니다. 샘플링이나 유실이 있는 trace만으로 “이 키는 사용되지 않았다”거나 “모든 동작이 감사 가능하다”고 결론 내리지 않습니다.
연결 문제는 다음 순서로 구분합니다.
- 테스트도 안 온다: endpoint 경로·인증·TLS와 공개 HTTPS 접근을 확인합니다. 401·403은 인증, 404는 경로부터 봅니다.
- 테스트는 오지만 실제 요청이 없다: 대상 작업공간이 destination 범위에 들어가는지 확인합니다. 이후 sampled 플래그를 봅니다.
- Delivery가 Disabled다: 3xx 리다이렉트, 비공개 IP로의 DNS 해석, 24시간 연속 전달 실패가 비활성화 원인인지 확인합니다. 원인을 고친 뒤 Console에서 Enable해야 합니다.
- Full content인데 대화가 비어 있다: 조직의 데이터 취급 제한과 truncation 여부를 확인합니다.
여기서 Console 상태 이름은 Healthy·Failing·No data·Disabled입니다. 애플리케이션 오류와 텔레메트리 전달 오류를 별개로 기록해야, 에이전트가 실패한 것인지 관측 데이터만 못 받은 것인지 구분할 수 있습니다.
첫 도입은 한 작업공간과 세 질문으로 제한합니다
다음은 팀 적용을 위한 작성자 제안입니다. 처음에는 Metadata only로 한 작업공간을 연결하고, 다음 질문에 답할 수 있는지 확인합니다.
- 긴 지연은 모델 호출, 서버 도구, 클라이언트 도구 중 어디에서 발생했는가?
- 재시도·도구 반복으로 토큰 사용이 늘었는가, 아니면 잘못된 집계로 늘어 보이는가?
- 실패 사례를 평가에 재사용할 때 빠진 span과 잘린 콘텐츠를 구분할 수 있는가?
이 질문에 답할 수 있으면 이후 콘텐츠 수집과 평가 자동화를 검토합니다. 실패를 설명할 수 없는 상태에서 대시보드 개수만 늘리기보다, 한 사용자 요청을 끝까지 이어 볼 수 있게 만드는 것부터 시작합니다.
참고 자료
- Agent observability on the Claude Platform ↗ — 공개 베타 발표·공식 도식·영상
- OpenTelemetry for the Claude API ↗ — 추적 범위·콘텐츠 모드·토큰 집계
- Set up OpenTelemetry with the Claude API ↗ — destination·테스트·trace 연결·전달 규칙
- Set up OpenTelemetry with the Claude SDK ↗ — tracer provider·SDK 추적·베타 변경 주의