---
title: Claude API용 OpenTelemetry
url: https://platform.claude.com/docs/ko/manage-claude/opentelemetry
description: Claude SDK와 Claude API의 OpenTelemetry 스팬으로 Messages API 요청, 도구 사용, Managed Agents 세션을 추적합니다.
featureMetadata:
  topic:
    title: OpenTelemetry
    url: https://platform.claude.com/docs/en/manage-claude/opentelemetry
  status: beta
---

<Note>
  OpenTelemetry 내보내기는 베타 단계입니다. [서비스별 약관](https://www.anthropic.com/legal/service-specific-terms)의 베타 서비스 섹션을 포함하여 Anthropic과의 계약에 따라 제공됩니다.
</Note>

Claude API와 SDK는 [OpenTelemetry](https://opentelemetry.io/)를 사용하여 Messages API 요청, 도구 사용, Managed Agents 세션을 추적할 수 있습니다. 이러한 트레이스는 이미 사용 중인 관측성 플랫폼에서 확인할 수 있습니다. 트레이스를 사용하여 실패하거나 느린 요청을 디버깅하고, 토큰 사용량과 "latency"(지연 시간)를 추적하고, 실제 트래픽으로 평가(eval)를 구축할 수 있습니다. 또한 애플리케이션 자체 트레이스 안에서 각 요청을 확인할 수 있으며, 해당 요청을 보낸 사용자나 기능과 연결됩니다.

OpenTelemetry는 대부분의 관측성 플랫폼이 지원하는 벤더 중립적 표준입니다. *"trace"*(트레이스)는 시스템을 통과하는 하나의 요청에 대한 전체 기록입니다. *"span"*(스팬)은 모델 요청이나 도구 사용과 같은 트레이스 내의 한 단계입니다. API와 SDK는 [GenAI 시맨틱 규칙](https://github.com/open-telemetry/semantic-conventions-genai)의 속성을 사용하므로, 이 규칙을 지원하는 플랫폼은 추가 설정 없이 스팬을 인식할 수 있습니다.

## 시작하기

SDK 추적, API 추적 또는 둘 다를 설정할 수 있습니다. [예제 트레이스](https://platform.claude.com/docs/ko/manage-claude/opentelemetry#example-traces-and-how-to-read-them)에서처럼 요청의 SDK 스팬과 API 스팬을 하나의 트레이스에서 보려면 둘 다 설정하세요. Claude Platform on AWS에 대한 요청의 경우, API 스팬은 대신 별도의 트레이스에 있습니다.

<CardGroup cols={3}>
  <Card title="SDK 추적 설정" icon="code-brackets" href="https://platform.claude.com/docs/ko/manage-claude/opentelemetry/sdk" layout="horizontal">
    SDK를 설치하고 트레이서 프로바이더를 등록합니다.
  </Card>

  <Card title="API 추적 설정" icon="cloud" href="https://platform.claude.com/docs/ko/manage-claude/opentelemetry/api" layout="horizontal">
    Claude Console에서 대상을 추가합니다.
  </Card>

  <Card title="스팬 레퍼런스" icon="book" href="https://platform.claude.com/docs/ko/api/opentelemetry/spans" layout="horizontal">
    스팬과 해당 속성을 조회합니다.
  </Card>
</CardGroup>

| 제공 항목                                                                                                              | SDK 트레이싱                                                                  | API 트레이싱                                                                                 | 함께 사용                                                                                    |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [Messages API](https://platform.claude.com/docs/ko/api/messages/create) 요청                                         | ✅                                                                         | ✅                                                                                        | ✅                                                                                        |
| [Sessions API](https://platform.claude.com/docs/ko/managed-agents/sessions) 요청                                     | ✅                                                                         | ✅                                                                                        | ✅                                                                                        |
| [토큰 사용량](https://platform.claude.com/docs/ko/manage-claude/opentelemetry#count-tokens)                             | ✅                                                                         | ✅                                                                                        | ✅                                                                                        |
| 요청 내 각 모델 실행                                                                                                       | —                                                                         | ✅                                                                                        | ✅                                                                                        |
| [Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview) 턴                                    | —                                                                         | ✅                                                                                        | ✅                                                                                        |
| API가 실행하는 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools)                      | —                                                                         | ✅                                                                                        | ✅                                                                                        |
| [도구 실행기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)가 실행하는 클라이언트 도구                 | ✅                                                                         | —                                                                                        | ✅                                                                                        |
| [자체 호스팅 샌드박스](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/sdk#trace-a-self-hosted-sandbox)의 도구 | ✅                                                                         | —                                                                                        | ✅                                                                                        |
| 파일 업로드 등 기타 API 요청                                                                                                 | ✅                                                                         | —                                                                                        | ✅                                                                                        |
| 설정                                                                                                                 | [코드](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/sdk) | [Console](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/api)           | 둘 다                                                                                      |
| 필요한 권한                                                                                                             | 없음                                                                        | [관리자](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/api#what-you-need) | [관리자](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/api#what-you-need) |
| 적용 범위                                                                                                              | SDK를 사용하는 클라이언트                                                           | 모든 클라이언트                                                                                 | 모든 클라이언트                                                                                 |
| 클라우드 플랫폼 지원                                                                                                        | 모두                                                                        | Claude Platform<br />Claude Platform on AWS                                              | Claude Platform<br />Claude Platform on AWS                                              |

Claude Code, Agent SDK 또는 Cowork의 경우 [Claude Code 모니터링](https://code.claude.com/docs/en/monitoring-usage), [Agent SDK 관측성](https://code.claude.com/docs/en/agent-sdk/observability) 또는 [Cowork 활동 모니터링](https://support.claude.com/en/articles/14477985-monitor-claude-cowork-activity-with-opentelemetry)을 참조하세요.

## 파트너 플랫폼으로 트레이스 전송

다음 파트너를 포함하여 OTLP를 수신하는 모든 관측성 플랫폼으로 트레이스를 보내세요:

<CardGroup cols={3}>
  <Card title="Arize AI" image="https://platform.claude.com/docs/images/partner-logos/arize.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/arize-dark.svg" imageOffsetLeft={2} href="https://arize.com/docs/ax/integrations/platforms/claude-managed-agents/claude-managed-agents-tracing">
    AI를 위한 통합 관측성 및 평가 플랫폼입니다.
  </Card>

  <Card title="Braintrust" image="https://platform.claude.com/docs/images/partner-logos/braintrust.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/braintrust-dark.svg" imageHeight={25} imageOffsetLeft={1} href="https://www.braintrust.dev/docs/integrations/ai-providers/anthropic#export-opentelemetry-traces-from-the-claude-api">
    에이전트를 위한 능동형 관측성 플랫폼입니다.
  </Card>

  <Card title="Databricks" image="https://platform.claude.com/docs/images/partner-logos/databricks.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/databricks-dark.svg" imageHeight={26} imageOffsetLeft={1} href="https://docs.databricks.com/aws/en/ai-gateway/unified-trace-table">
    관측성 및 평가를 위한 통합 AI 컨트롤 플레인입니다.
  </Card>

  <Card title="Datadog" image="https://platform.claude.com/docs/images/partner-logos/datadog.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/datadog-dark.svg" imageHeight={28} imageOffsetLeft={2} href="https://docs.datadoghq.com/llm_observability/instrument/otel_instrumentation/?tab=python#using-claude-managed-agents">
    AI 기반 관측성 및 보안입니다.
  </Card>

  <Card title="Grafana Cloud" image="https://platform.claude.com/docs/images/partner-logos/grafana.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/grafana-dark.svg" imageHeight={34} imageOffsetLeft={2} href="https://grafana.com/docs/grafana-cloud/observe-and-act/agent-observability/guides/send-claude-platform-traces/">
    완전 관리형 개방형 관측성 플랫폼입니다.
  </Card>

  <Card title="Honeycomb" image="https://platform.claude.com/docs/images/partner-logos/honeycomb.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/honeycomb-dark.svg" imageHeight={36} imageOffsetLeft={4} href="https://docs.honeycomb.io/send-data/use-cases/claude-platform">
    새로운 형태의 소프트웨어를 위한 관측성 플랫폼입니다.
  </Card>

  <Card title="Langfuse" image="https://platform.claude.com/docs/images/partner-logos/langfuse.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/langfuse-dark.svg" imageHeight={26} imageOffsetLeft={1} href="https://langfuse.com/integrations/model-providers/claude-platform">
    오픈 소스 에이전트 관측성 및 평가 플랫폼입니다.
  </Card>

  <Card title="LangSmith" image="https://platform.claude.com/docs/images/partner-logos/langchain.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/langchain-dark.svg" imageHeight={29} href="https://docs.langchain.com/langsmith/trace-anthropic">
    LangSmith 에이전트 엔지니어링 플랫폼입니다.
  </Card>

  <Card title="New Relic" image="https://platform.claude.com/docs/images/partner-logos/new-relic.svg" imageHeight={27} imageOffsetLeft={1} href="https://docs.newrelic.com/docs/ai-monitoring/opentelemetry-ai-monitoring/#anthropic">
    지능형 관측성 플랫폼입니다.
  </Card>

  <Card title="PostHog" image="https://platform.claude.com/docs/images/partner-logos/posthog.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/posthog-dark.svg" imageHeight={29} href="https://posthog.com/docs/ai-observability/installation/anthropic?tab=Claude+Platform&utm_source=anthropic&utm_campaign=anthropic-otel">
    성공적인 제품을 만들기 위한 올인원 플랫폼입니다.
  </Card>

  <Card title="Sentry" image="https://platform.claude.com/docs/images/partner-logos/sentry.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/sentry-dark.svg" imageHeight={25} href="https://sentry.io/cookbook/trace-claude-platform-with-opentelemetry/">
    망가진 코드와 오작동하는 에이전트를 디버깅하세요.
  </Card>

  <Card title="Splunk" image="https://platform.claude.com/docs/images/partner-logos/splunk.svg" imageDark="https://platform.claude.com/docs/images/partner-logos/splunk-dark.svg" imageHeight={27} imageOffsetLeft={1} href="https://agent-observability-docs.splunk.com/sdk-api/third-party-integrations/claude">
    에이전트를 관측하고 평가하고 보호하세요.
  </Card>
</CardGroup>

## 콘텐츠 모드

각 대상과 각 SDK 클라이언트에는 스팬에 모델 프롬프트와 응답을 포함할지 여부를 설정하는 콘텐츠 모드가 있습니다. [대상을 추가](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/api#add-a-destination)하거나 [SDK를 구성](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/sdk#configure-the-sdk)할 때 설정하세요.

* **Metadata only**(SDK에서는 `metadata_only`): 기본값입니다. 스팬에 식별자, 타이밍, 상태, 토큰 수, 그리고 에이전트와 도구의 이름 및 설명, MCP 서버의 이름 등 직접 지정한 텍스트가 포함됩니다.
* **Full content**(SDK에서는 `content`): 가장 높은 가시성을 제공합니다. 스팬에는 모델 프롬프트와 응답, 그리고 Metadata only의 모든 항목이 포함됩니다.

Full content를 사용하면 실행이 실패하거나 느렸던 이유를 확인하고, 전체 대화를 읽고, 실제 트레이스로 평가를 구축할 수도 있습니다. [OpenTelemetry 스팬 레퍼런스](https://platform.claude.com/docs/ko/api/opentelemetry/spans)에서 프롬프트와 응답을 담는 속성에는 <Badge>Content</Badge> 태그가 붙어 있습니다.

<Info>
  관측성 플랫폼은 자체 접근 및 보존 설정에 따라 이 콘텐츠를 저장하므로, 해당 설정이 조직의 요구 사항을 충족하는지 확인하세요.
</Info>

조직에 Anthropic과의 HIPAA, FERPA 또는 K-12 데이터 처리 제한이 있는 경우, 대상은 콘텐츠 모드와 관계없이 메타데이터만 내보냅니다. SDK 스팬은 영향을 받지 않습니다.

[제로 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention)을 사용하는 경우에도 Full content를 사용할 수 있습니다. Messages API 요청의 경우, API는 내보낸 콘텐츠를 대상으로 전달할 때까지만 메모리에 보관합니다. [Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)는 제로 데이터 보존 대상이 아니며, OpenTelemetry를 사용하더라도 데이터 보존 방식은 동일하게 유지됩니다.

### 콘텐츠 제한

Full content를 사용하면 각 스팬에는 기본적으로 최대 0.75 MB의 콘텐츠가 포함됩니다. 이 값은 200k 토큰 컨텍스트 윈도우를 영어 텍스트로 가득 채운 분량에 맞으면서도, 많은 관측성 플랫폼과 프록시의 1 MB 요청 제한 아래로 유지됩니다. **Provider**로 파트너 플랫폼을 선택하면 Console이 해당 플랫폼이 허용하는 제한을 설정합니다.

콘텐츠가 제한을 넘으면 SDK 또는 API는 콘텐츠를 줄이고 `anthropic.content.truncated`를 `true`로 설정합니다. 요청 스팬에서는 시스템 프롬프트와 가장 오래된 메시지가 먼저 제거되고, 도구 스팬에서는 결과의 끝에서부터 블록이 제거됩니다. 이미지와 문서는 유형만 표시됩니다.

다음과 같은 경우 제한을 변경하세요.

* **관측성 플랫폼이 더 큰 페이로드를 허용하는 경우:** 긴 프롬프트와 응답을 온전히 유지하려면 제한을 높이거나 없애세요. 1M 토큰 컨텍스트 윈도우를 가득 채우려면 약 4 MB가 필요합니다.
* **관측성 플랫폼 또는 그 앞에 있는 프록시가 큰 요청을 거부하는 경우:** 제한을 낮추세요.

SDK에서는 `traces.max_content_bytes` (typescript, java, php: `traces.maxContentBytes`; csharp: `Traces.MaxContentBytes`; go: `option.WithOpenTelemetryTracesMaxContentBytes()`)를 설정하세요. Console에서는 [대상을 추가](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/api#add-a-destination)할 때 **Content mode**를 **Full content**로 설정한 다음, **Advanced settings**에서 **Maximum content size in MB**를 설정하세요.

## 예제 트레이스와 읽는 방법

### Messages API 요청

[메시지를 생성](https://platform.claude.com/docs/ko/api/messages/create)하는 요청의 API 스팬 아래에, API는 각 모델 요청에 대한 스팬과 API가 실행하는 서버 도구 또는 MCP 커넥터 도구의 각 사용에 대한 도구 스팬을 추가합니다.

이 예제에서 애플리케이션은 도구를 실행하고 그 결과를 Claude에 다시 보내는 SDK 헬퍼인 [도구 실행기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)를 호출합니다. 도구 실행기가 보내는 각 요청에는 SDK의 클라이언트 스팬과 API의 서버 스팬이 있습니다. 스팬은 다음 순서로 나타납니다:

1. 애플리케이션이 `answer_question` 스팬을 시작하고 그 안에서 Messages 도구 실행기를 호출합니다([`anthropic.messages.tool_runner`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-messages-tool-runner) 스팬으로 표시됨).
2. 도구 실행기가 첫 번째 요청을 보냅니다(첫 번째 [`anthropic.messages.create`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-messages-create) 클라이언트 스팬과 그 아래의 스팬으로 표시됨). 이 요청에서 API는 두 모델 요청 사이에 웹 검색 도구를 실행합니다.
3. 두 번째 모델 요청에서 모델이 사용자 정의 `get_weather` 도구 사용을 요청하므로 첫 번째 요청이 종료됩니다.
4. 도구 실행기가 `get_weather`를 실행합니다(`anthropic.custom_tool_use get_weather` 스팬으로 표시됨).
5. 도구 실행기가 도구 결과와 함께 두 번째 요청을 보냅니다(두 번째 `anthropic.messages.create` 클라이언트 스팬과 그 아래의 스팬으로 표시됨).
6. 두 번째 요청에서 모델이 최종 답변을 제공합니다.

![Messages tool runner(도구 실행기) 트레이스 예시: client span(클라이언트 스팬)과 server span(서버 스팬), model request(모델 요청), web\_search, get\_weather가 포함된 두 개의 요청](https://platform.claude.com/docs/images/opentelemetry-sdk-trace-shape.svg)

애플리케이션의 SDK는 [`anthropic.messages.tool_runner`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-messages-tool-runner) 스팬, [`anthropic.custom_tool_use`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) 스팬, 그리고 각 요청의 클라이언트 스팬을 생성합니다. 이러한 스팬을 받으려면 [SDK 추적을 설정](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/sdk)하세요.

각 요청의 토큰 사용량은 여러 스팬에 기록됩니다. 각 토큰을 한 번만 계산하려면 [토큰 계산](https://platform.claude.com/docs/ko/manage-claude/opentelemetry#count-tokens)을 참조하세요.

[Full content](https://platform.claude.com/docs/ko/manage-claude/opentelemetry#choose-a-content-mode)를 사용하면 `anthropic.messages.create` 서버 스팬에 프롬프트와 응답이 포함됩니다. 시스템 프롬프트는 `gen_ai.system_instructions`에, 요청의 메시지는 `gen_ai.input.messages`에, 응답은 `gen_ai.output.messages`에 있습니다.

각 스팬과 해당 속성은 [OpenTelemetry 스팬 레퍼런스](https://platform.claude.com/docs/ko/api/opentelemetry/spans)를 참조하세요.

### Managed Agents 세션

세션에는 각 Sessions API 요청에 대한 span과 각 에이전트 턴에 대한 턴 span이 있습니다. 요청이 시작한 턴은 해당 요청 span의 자식입니다. 턴에는 각 모델 요청과 API가 실행하는 각 도구에 대한 span이 포함되며, [도구 span 참조에 나열된 경우](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use)는 예외입니다. 또한 각 결과 평가에 대한 span도 포함됩니다.

이 예시는 애플리케이션이 세션에 메시지를 보내고 사용자 정의 도구를 실행하는 하나의 채팅 요청을 따라갑니다. 트레이스에는 애플리케이션과 API 양쪽의 span이 다음 순서로 포함됩니다:

1. 애플리케이션이 사용자로부터 `POST /chat` 요청을 받습니다.
2. 애플리케이션이 SDK의 세션 도구 러너를 시작하며, 이 러너는 세션의 이벤트를 나열하고 스트리밍합니다(`anthropic.sessions.events.stream` 및 `anthropic.sessions.events.list` span으로 표시됨).
3. 애플리케이션이 `sessions.events.send`를 호출하여 사용자의 메시지를 세션에 보냅니다.
4. 턴이 시작되며 모델 요청, `bash` 도구 사용, 다른 스레드의 턴이 포함됩니다(첫 번째 `anthropic.session.turn` span과 그 아래의 span으로 표시됨).
5. 모델이 [사용자 정의 도구](https://platform.claude.com/docs/ko/managed-agents/tools) `list_issues`의 사용을 요청하므로, 턴은 중지 사유 `requires_action`으로 종료됩니다.
6. 세션 도구 러너가 `list_issues`를 실행하고(`anthropic.custom_tool_use list_issues` span으로 표시됨) `sessions.events.send`를 호출하여 그 결과를 보냅니다.
7. 도구 결과와 함께 두 번째 턴이 시작됩니다(마지막 `anthropic.session.turn` span으로 표시됨).

![Managed Agents 세션의 트레이스 예시: POST /chat 스팬, 세션 tool runner(도구 실행기)의 event stream(이벤트 스트림) 및 event list(이벤트 목록) 요청, 사용자 메시지를 보내는 요청의 client span(클라이언트 스팬)과 server span(서버 스팬), model request(모델 요청)와 bash 도구 사용 및 다른 thread(스레드)의 turn(턴)이 포함된 턴, list\_issues를 실행하는 실행기, 도구 결과를 보내는 요청의 클라이언트 스팬과 서버 스팬, 그리고 두 번째 턴.](https://platform.claude.com/docs/images/opentelemetry-trace-shape.svg)

애플리케이션의 SDK는 [`anthropic.custom_tool_use`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) span과 각 요청의 클라이언트 span을 내보냅니다. 이러한 span을 얻으려면 [SDK 트레이싱을 설정](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/sdk)하세요.

세션의 span은 여러 트레이스에 걸쳐 있을 수 있습니다. 예를 들어 새 루트 트레이스에서 이후 요청을 보내는 경우입니다. [멀티에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration)가 켜져 있으면 세션에 여러 스레드가 있을 수도 있습니다. 필요한 span을 찾으려면 ID로 그룹화하세요.

* **하나의 스레드:** 세션 스레드 ID를 담고 있는 `gen_ai.conversation.id`로 span을 그룹화하세요. 시작 시간순으로 정렬하면 스레드를 대화 기록처럼 읽을 수 있습니다.
* **모든 스레드를 포함한 전체 세션:** 트레이스 전반에 걸쳐 `anthropic.session.id`로 span을 그룹화하세요.

[Full content](https://platform.claude.com/docs/ko/manage-claude/opentelemetry#choose-a-content-mode)를 사용하면 세션의 span에서 세션의 콘텐츠를 읽을 수 있습니다.

* 턴의 콘텐츠를 읽으려면 해당 [턴 span](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-session-turn)을 사용하세요. 시스템 프롬프트는 스레드의 첫 번째 턴 span의 `gen_ai.system_instructions`에, 입력은 `gen_ai.input.messages`(사용자의 메시지와 도구 결과, `system.message` 이벤트, 다른 스레드의 메시지)에, 출력은 `gen_ai.output.messages`(에이전트의 메시지, 도구 사용, 도구 결과)에 있습니다.
* 도구 사용의 인수와 결과를 보려면 해당 [도구 span](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use)을 읽으세요. 인수는 `gen_ai.tool.call.arguments`에, 결과는 `anthropic.tool_result.content`에 있습니다.

각 span과 그 속성에 대해서는 [OpenTelemetry span 참조](https://platform.claude.com/docs/ko/api/opentelemetry/spans)를 참조하세요.

## 토큰 계산

각 토큰을 한 번만 계산하려면 각 요청에 대해 하나의 소스의 span만 합산하세요. Messages API 요청에 SDK span과 API span이 모두 있는 경우 API span을 합산하세요. 둘 다 이름이 `anthropic.messages.create`이므로 종류로 구분하세요. SDK span은 `CLIENT`이고, 그 자식인 API span은 `SERVER`입니다.

일부 사용량 속성은 API span의 여러 수준에서 반복되므로, 각 소스에 대해 다음 span만 합산하세요:

* **SDK span:** [`anthropic.messages.create`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-messages-create) span을 합산하세요. 요청에 [컴팩션](https://platform.claude.com/docs/ko/build-with-claude/compaction)이 있는 경우, `gen_ai.usage.*` 속성에는 컴팩션 토큰이 포함되지 않으므로 span의 `anthropic.usage.compaction.input_tokens`와 `anthropic.usage.compaction.output_tokens`도 더하세요. [폴백 모델](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback)이 요청을 처리한 경우, 해당 span에는 응답을 처리한 모델의 사용량만 포함됩니다.
* **Messages API 요청의 API span:** [`anthropic.messages.create`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-messages-create) span 또는 그 [`anthropic.model_request`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-model-request) span 중 하나만 합산하고, 둘 다 합산하지 마세요. 요청에 컴팩션이 있는 경우 해당 [`anthropic.compaction`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-compaction) span도 더하세요. `anthropic.messages.create` span의 `anthropic.usage.compaction.*` 속성은 같은 토큰을 담고 있으므로 추가로 더하지 마세요.
* **Managed Agents 세션의 API span:** `anthropic.model_request` 및 [`anthropic.session.outcome_evaluation`](https://platform.claude.com/docs/ko/api/opentelemetry/spans#anthropic-session-outcome-evaluation) span을 합산하세요.

예를 들어 전송이 재시도되면 span이 두 번 이상 도착할 수 있습니다. 관측성 플랫폼에서 중복을 제거하지 않는 경우, 트레이스 ID와 span ID를 기준으로 각 span을 한 번만 계산하세요.

`gen_ai.usage.input_tokens`에는 이미 프롬프트 캐시에서 읽거나 쓴 토큰이 포함되어 있으므로 캐시 속성을 더하지 마세요. 모든 사용량 속성에 대해서는 [토큰 사용량](https://platform.claude.com/docs/ko/api/opentelemetry/spans#token-usage)을 참조하세요.

<Note>
  내보낸 스팬이 API 사용량의 완전한 기록이라는 보장은 없습니다. 스팬 전송은 [최선 노력(best effort)](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/api#delivery-and-health) 방식이므로 스팬이 유실될 수 있습니다. 또한 호출자는 요청의 [`traceparent` 헤더](https://platform.claude.com/docs/ko/manage-claude/opentelemetry/api#connect-api-spans-to-your-own-traces)에서 sampled 플래그를 꺼서 해당 요청의 스팬을 제외할 수 있습니다. 예를 들어 유출된 키를 발견하기 위해 각 API 키의 사용량을 추적하려면 [Usage API](https://platform.claude.com/docs/ko/manage-claude/usage-cost-api#usage-api)를 사용하세요. 이 API는 스팬이 없는 요청의 사용량도 집계합니다.
</Note>