무엇이 바뀌었나
Anthropic Platform 문서는 Claude API와 SDK가 Messages API 요청, 도구 사용, Managed Agents 세션을 이미 돌리고 있는 관측 플랫폼으로 추적할 수 있다고 합니다. 트레이스는 요청 하나의 전체 기록입니다. 스팬은 모델 요청이나 도구 사용처럼 그 안의 한 단계입니다. 스팬은 GenAI 시맨틱 컨벤션 속성을 쓰므로, 그 컨벤션을 지원하는 플랫폼은 추가 설정 없이 알아볼 수 있습니다. 문서가 밝힌 용도는 실패하거나 느린 요청을 디버그하고, 토큰 지출과 지연을 추적하고, 실제 트래픽으로 평가를 만드는 일이며, 각 요청은 그것을 보낸 사용자나 기능과 연결됩니다.
출시 글은 같은 트레이스가 Claude Managed Agents, Messages API, Claude SDK에서 나올 수 있고, Platform에서 만든 에이전트가 이미 Claude Code나 Cowork 트레이스를 받는 도구에 나타날 수 있다고 합니다. Platform 문서는 Claude Code, Agent SDK, Cowork를 각자 모니터링 페이지로 보냅니다. 글은 Console에 목적지를 추가하면 에이전트 턴, 모델 호출, 도구 사용이 모두 지연, 토큰, ID를 담은 표준 OpenTelemetry 트레이스로 전달된다고 합니다. 문서는 전달이 best effort이며 스팬이 사라질 수 있다고 합니다. 호출하는 쪽은 그 요청의 샘플링 결정을 실어 나르는 traceparent 헤더에서 sampled 플래그를 꺼, 요청의 스팬을 빼낼 수도 있습니다.
누구를 위한 기능이며, 계정 밖으로 무엇이 나가는가
OTLP, 곧 OpenTelemetry 내보내기 프로토콜을 받는 플랫폼은 모두 목적지가 될 수 있습니다. 문서는 Arize AI, Braintrust, Databricks, Datadog, Grafana Cloud, Honeycomb, Langfuse, LangSmith, New Relic, PostHog, Sentry, Splunk를 이름 올리고, Langfuse를 오픈 소스라고 설명합니다. 출시 글은 Grafana Cloud, Honeycomb, Sentry, Splunk를 로그와 지표 옆의 디버깅으로, Arize AI, Braintrust, Datadog, Langfuse, LangChain의 LangSmith, New Relic, PostHog를 평가로, Databricks Unity Gateway를 팀별 토큰 사용량으로 묶습니다. 문서는 마지막 파트너를 Databricks로 적습니다.
Anthropic과 HIPAA, FERPA, 또는 K-12 데이터 처리 제한이 있는 조직은 콘텐츠 모드를 어떻게 두든 목적지가 메타데이터만 내보냅니다. 문서는 SDK 스팬이 그 제한의 영향을 받지 않는다고 합니다. 제로 데이터 보존에서도 Messages API 요청의 Full content는 그대로 동작하며, API는 내보낸 내용을 전달할 때까지 메모리에만 둡니다. Claude Managed Agents는 제로 데이터 보존 대상이 아니며, 문서는 OpenTelemetry를 써도 그 보존은 바뀌지 않는다고 합니다.
| 선택 | 문서가 밝힌 내용 |
|---|---|
| 메타데이터만 (metadata_only) | 기본값입니다. 식별자, 시간 정보, 상태, 토큰 수, 그리고 에이전트와 도구의 이름·설명, MCP 서버 이름처럼 직접 고른 텍스트가 들어갑니다. 프롬프트와 응답은 나가지 않습니다. |
| 전체 내용 (content) | 모델 프롬프트와 응답이 추가됩니다. 관측 플랫폼은 자체 접근 권한과 보존 설정 아래 이를 저장합니다. |
| 기본 크기 | 스팬당 0.75MB입니다. 문서는 영어 200k 토큰 컨텍스트에 맞고, 플랫폼과 프록시에 흔한 1MB 한도 아래에 머문다고 합니다. |
| 1M 토큰 창 | 1M 토큰 컨텍스트 창 전체에는 약 4MB가 필요합니다. 플랫폼이 더 큰 페이로드를 받으면 한도를 올리거나 없앱니다. |
| 파트너를 Provider로 | Console의 별도 선택입니다. 파트너 플랫폼을 Provider로 고르면 Console이 그 플랫폼이 받는 한도를 설정합니다. |
| 더 작은 상한 | 관측 플랫폼이나 그 앞의 프록시가 큰 요청을 거절하면 한도를 낮춥니다. |
| 상한을 넘으면 | 내용이 짧아지고 anthropic.content.truncated가 true가 됩니다. 요청 스팬은 시스템 프롬프트와 가장 앞선 메시지부터 뺍니다. 도구 스팬은 끝쪽 블록부터 뺍니다. 이미지와 문서는 유형만 나타납니다. |
| 바꾸는 곳 | SDK는 traces.max_content_bytes입니다. Console에서는 Full content를 설정한 뒤 Advanced settings의 Maximum content size in MB를 바꿉니다. |
켜는 방법, 그리고 토큰을 한 번만 세는 방법
SDK 추적은 SDK를 설치하고 tracer provider를 등록하는 일입니다. 문서는 SDK가 스팬을 내보내게 하는 등록 단계로 이것을 부릅니다. API 추적은 Claude Console에 목적지를 추가하는 일입니다. 출시 글은 Managed Agents와 Messages API에 그 Console 목적지가 필요하고, Claude SDK는 트레이스를 자동으로 내보낸다고 합니다. 문서는 SDK 스팬에 여전히 tracer provider를 요구합니다. 둘을 함께 설정하면 요청 하나의 SDK 스팬과 API 스팬을 한 트레이스에서 봅니다. Claude Platform on AWS로 가는 요청에서는 API 스팬이 자기 트레이스에 남는다고 문서는 말합니다.
문서는 SDK 추적, API 추적, 둘 다를 비교합니다. 그 열 순서대로 설정은 코드, 그다음 Console, 그다음 둘 다입니다. 필요한 권한은 None, 그다음 Admin, 그다음 Admin입니다. 범위는 SDK를 쓰는 클라이언트, 그다음 아무 클라이언트, 그다음 아무 클라이언트입니다.
문서의 Messages 예시에서 애플리케이션은 tool runner를 호출합니다. tool runner는 도구를 실행하고 그 결과를 돌려보내는 SDK 도우미입니다. SDK는 tool-runner 스팬, 커스텀 클라이언트 도구 스팬, 요청마다의 클라이언트 create 스팬을 내보냅니다. API는 서버 create 스팬, 모델 요청마다의 스팬, 그리고 API가 실행하는 서버 도구나 MCP 커넥터 도구마다의 도구 스팬을 내보냅니다.
Messages API 요청에 SDK 스팬과 API 스팬이 모두 있으면 API 스팬을 합합니다. 둘 다 이름은 anthropic.messages.create입니다. kind로 가릅니다. SDK 스팬은 CLIENT이고, 그 자식인 API 스팬은 SERVER입니다. API Messages 스팬의 합계는 두 묶음 중 하나입니다. anthropic.messages.create 스팬이거나 anthropic.model_request 스팬입니다. Managed Agents 세션은 anthropic.model_request와 anthropic.session.outcome_evaluation 스팬을 합합니다. 한 세션의 스팬은 여러 트레이스에 나뉠 수 있습니다. multiagent가 켜져 있으면 gen_ai.conversation.id가 스레드 하나를, anthropic.session.id가 세션 전체를 묶습니다. gen_ai.usage.input_tokens에는 프롬프트 캐시 읽기와 쓰기가 이미 들어 있습니다. 재시도가 같은 스팬을 다시 보내면 trace ID와 span ID로 한 번만 셉니다. 표는 출처마다 한 번만 더하는 목록입니다.
SDK create 스팬에서는 anthropic.usage.compaction.input_tokens와 anthropic.usage.compaction.output_tokens도 더합니다. gen_ai.usage.*에 컴팩션 토큰이 빠지기 때문입니다. 폴백 모델이 요청을 처리했다면 그 SDK 스팬에는 응답을 실제로 낸 모델의 사용량만 있습니다. API Messages 스팬에서는 그 요청의 anthropic.compaction 스팬을 더하고, create 스팬의 anthropic.usage.compaction.* 속성은 같은 합계에 넣지 않습니다. 같은 토큰을 담고 있기 때문입니다.
| 출처 | 합에 넣는 스팬 | 컴팩션과 폴백 |
|---|---|---|
| SDK 스팬과 API 스팬이 모두 있는 Messages 요청 | kind가 SERVER인 API anthropic.messages.create 스팬입니다. 같은 이름의 SDK 스팬은 kind가 CLIENT입니다. | 이어서 API Messages 행을 씁니다. |
| SDK create 스팬 | anthropic.messages.create | anthropic.usage.compaction.input_tokens와 anthropic.usage.compaction.output_tokens도 더합니다. 폴백 스팬에는 응답을 실제로 낸 모델의 사용량만 있습니다. |
| API Messages 스팬 | anthropic.messages.create 또는 anthropic.model_request 중 하나 | anthropic.compaction 스팬도 더합니다. create 스팬의 anthropic.usage.compaction.* 속성은 같은 토큰을 담으므로 이 합계에 넣지 않습니다. |
| Managed Agents 세션 | anthropic.model_request와 anthropic.session.outcome_evaluation | 집계 규칙은 이 스팬에 대한 별도의 컴팩션 가산을 적지 않습니다. 한 세션의 스팬은 여러 트레이스에 나뉠 수 있습니다. |
가격, 날짜, 인용이 재는 것
OpenTelemetry 문서와 출시 글은 가격, 요금제 등급, 내보내기 할당량, 정식 출시일을 밝히지 않습니다. 글 본문에는 자체 게시일도 없습니다. 베타 고지는 이 내보내기가 Anthropic과의 계약, 그중 Service Specific Terms의 Beta Services 절에 따라 제공된다고 합니다.
Ramp의 David Traina는 Langfuse 트레이스에 점수를 매기는 Reflect가 일부 에이전트에서 토큰 사용량을 이미 10–20% 줄이고 세션을 30% 빠르게 만들었다고 합니다. 그는 Claude API의 네이티브 내보내기가 그 개선 순환에 들어갈 수 있고, Reflect는 관찰한 것만 개선할 수 있다고 합니다. 이 비율은 Reflect의 기존 결과에 대한 그의 설명입니다. 글은 Foxglove의 Roman Shtylman이 제품 사용량 옆의 PostHog를 말한 대목, Sterling Labs의 Hyon Lee가 맞춤 계측 없이 Langfuse가 트레이스를 모두 받는다고 한 대목, 소속이 적히지 않은 인프라 책임자 Ankush Sharma가 장부 조정과 분개 워크플로 옆의 Grafana Cloud를 말한 대목도 인용합니다. Lee가 트레이스를 모두 받는다고 한 말은 문서의 best effort 전달과 나란히 있습니다.
Claude Code 변경 로그는 이와 별도로 Claude Code 트레이스 스팬에 GenAI 속성을 더합니다. gen_ai.provider.name, gen_ai.conversation.id, gen_ai.tool.name, error.type이 포함되고, api_request 이벤트에는 cache_creation_5m_tokens와 cache_creation_1h_tokens가 추가됩니다. 그 항목은 버전을 적지 않으며, 이 Console 목적지가 아니라 Claude Code 텔레메트리입니다.
출처
함께 본 출처
자료 및 작성 기준
이 브리프는 2026년 10월 15일 ClaudeDevs 게시물, Anthropic의 Platform OpenTelemetry 문서, 출시 글 “Trace agents with OpenTelemetry on the Claude Platform”을 모두 그날 읽은 내용에 기대고 있습니다. Claude Code 변경 로그의 GenAI 스팬 속성 대목은 Platform 내보내기와 구분하려고만 넣었습니다. 그 항목에는 버전 제목이 없습니다. Beta Services 약관, 스팬 속성 레퍼런스, 토큰 사용량 속성 페이지, 그리고 Claude Code, Agent SDK, Cowork 모니터링 페이지는 이번 열람 범위 밖입니다. 목적지를 설정하지 않았고, 트레이스도 내보내지 않았습니다.