API 레퍼런스OpenTelemetry

OpenTelemetry 스팬 참조

Copy page



Claude API와 Claude SDK가 내보내는 OpenTelemetry 스팬 및 스팬 속성입니다.

내보내기를 설정하려면 Claude SDK에서 OpenTelemetry 사용하기 및 Claude API에서 OpenTelemetry 사용하기를 참조하세요.

스팬 이름 및 종류

• 요청에 대한 스팬은 요청의 API 메서드 이름을 가집니다. 즉, anthropic. 뒤에 API 참조에서의 메서드 경로가 오며, 슬래시 대신 점을 사용하고 beta는 포함하지 않습니다. 예를 들어, client.beta.sessions.events.send()는 세션 이벤트 전송 요청을 보내며, 그 스팬의 이름은 anthropic.sessions.events.send입니다.
• 도구 스팬은 고정된 이름, 공백, 도구 이름으로 구성됩니다. 예: anthropic.tool_use bash.

스팬 상태

• OK: 단계가 완료되었습니다.
• ERROR: 단계가 실패했습니다.
• Unset(설정되지 않음): 애플리케이션이 단계를 취소했습니다. 예를 들어 user.interrupt 이벤트를 보낸 경우입니다.

스트림의 스팬은 스트림이 끝날 때 종료됩니다. 애플리케이션이 스트림을 일찍 닫으면 SDK 스팬의 상태는 설정되지 않으므로, anthropic.sessions.events.stream처럼 완료되지 않는 스트림의 SDK 스팬은 상태가 설정되지 않거나 ERROR입니다.

속성

속성은 해당하는 것이 있는 경우 생성형 AI를 위한 OpenTelemetry 시맨틱 규칙(gen_ai.*)을 사용합니다. Anthropic 속성은 anthropic.으로 시작합니다. 스팬은 2026년 9월 24일의 커밋 e57c543b 시점의 규칙을 따릅니다. 이 규칙은 아직 개발 중입니다.

공통 속성

설명에 달리 명시된 경우를 제외하고, 요청에 대한 모든 스팬에는 다음 속성이 있습니다. 다른 스팬에는 처음 세 가지 속성만 있을 수 있습니다:

Claude Platform on AWS에서는 API 스팬에 server.address, server.port, url.full이 포함되지 않습니다.

세션 속성

Managed Agents 세션에서 스팬에는 다음 속성이 있습니다. 세션의 스팬은 둘 이상의 트레이스에 있을 수 있으므로, 트랜스크립트와 같은 세션 뷰를 구성하려면 이 ID로 스팬을 그룹화하세요.

콘텐츠 속성

Content 태그가 붙은 속성은 SDK와 API 모두에서 콘텐츠 모드의 스팬에만 있습니다. 가이드에서 콘텐츠 모드의 차이점을 참조하세요. 이 콘텐츠가 너무 크면 SDK와 API는 콘텐츠를 줄이고 anthropic.content.truncated를 true로 설정합니다. Anthropic의 안전장치가 응답에서 콘텐츠를 보류하면 API의 스팬에도 해당 콘텐츠가 포함되지 않습니다.

메시지 속성은 OpenTelemetry GenAI 규칙의 메시지 형식을 따르는 JSON 문자열입니다. Messages API와 agent.message 같은 Managed Agents 메시지 이벤트에서 각 Anthropic 콘텐츠 블록은 하나의 GenAI 규칙 메시지 파트가 됩니다:

각 Managed Agents 도구 사용 또는 도구 결과 이벤트도 하나의 GenAI 규칙 메시지 파트가 됩니다:

토큰 사용량

다음 스팬에는 토큰 사용량 속성이 있습니다: anthropic.messages.create, anthropic.model_request, anthropic.compaction, anthropic.session.outcome_evaluation. 값은 요청, 모델 요청, 압축 등 해당 스팬의 단계에 대한 것입니다. 각 토큰을 한 번씩만 세려면 가이드의 토큰 계산 방법을 참조하세요.

스팬

"Span"(스팬)은 애플리케이션의 SDK 또는 API에서 올 수 있으므로, 이 참조의 각 스팬에는 그 출처가 나열되어 있습니다. Messages API: 또는 Managed Agents:로 시작하는 설명은 해당 제품의 스팬에 대한 것입니다. SDK: 또는 API:처럼 출처로 시작하는 속성 설명은 해당 출처의 스팬에 대한 것입니다.

anthropic.messages.create

• 출처: SDK와 API.
• 종류: SDK에서는 CLIENT, API에서는 SERVER.
• SDK 스팬의 부모: 애플리케이션이 메서드를 호출할 때 현재 활성화된 스팬입니다. 현재 스팬이 없으면 부모가 없습니다.
• API 스팬의 부모: 요청의 traceparent 헤더에 있는 스팬으로, 요청이 SDK에서 온 경우 SDK 스팬입니다. 헤더가 없으면 API 스팬에는 부모가 없습니다. traceparent 헤더를 보내는 방법을 참조하세요.
• SDK 스팬의 자식: 같은 요청에 대한 API의 스팬.
• API 스팬의 자식: 각 모델 요청에 대한 anthropic.model_request 스팬, API가 요청에서 실행하는 서버 도구 또는 MCP 커넥터 도구의 각 사용에 대한 도구 스팬, 각 압축에 대한 anthropic.compaction 스팬.

SDK는 스트리밍 여부와 관계없이 각 Messages 요청에 대해 이 스팬을 내보냅니다.

API는 인증한 각 POST /v1/messages 요청에 대해 이 스팬을 내보냅니다. OpenAI 호환 엔드포인트인 POST /v1/chat/completions에 대한 요청에는 이 스팬을 내보내지 않습니다.

API는 폴백 모델이 요청을 처리하는 경우에도 요청당 하나의 스팬을 내보냅니다.

이 스팬에는 토큰 사용량 속성이 있습니다. SDK 스팬에는 모든 요청에 대한 SDK 스팬의 속성도 있습니다.

요청에 대한 스팬에는 web_search_requests와 같은 응답의 서버 도구 사용 횟수가 없습니다. 대신 API는 서버 도구의 각 사용에 대해 도구 스팬을 내보냅니다.

anthropic.messages.count_tokens

• 출처: SDK. API는 POST /v1/messages/count_tokens에 대한 스팬을 내보내지 않습니다.
• 종류: CLIENT.
• 부모: 애플리케이션이 메서드를 호출할 때 현재 활성화된 스팬이며, 현재 스팬이 없으면 없습니다.
• 자식: 없음.

anthropic.sessions.create

다음 자식과 속성을 제외하면 anthropic.sessions.<method>와 같습니다:

• SDK 스팬의 자식: 해당 요청에 대한 API의 스팬.
• API 스팬의 자식: 요청에 비어 있지 않은 initial_events가 있는 경우, 첫 번째 턴의 anthropic.session.turn 스팬.

anthropic.sessions.events.send

API 스팬의 자식을 제외하면 anthropic.sessions.<method>와 같습니다.

• SDK 스팬의 자식: 해당 요청에 대한 API의 스팬.
• API 스팬의 자식: 요청의 이벤트로 인해 시작되는 각 턴의 anthropic.session.turn 스팬.

anthropic.sessions.update

API 스팬의 자식을 제외하면 anthropic.sessions.<method>와 같습니다.

• SDK 스팬의 자식: 해당 요청에 대한 API의 스팬.
• API 스팬의 자식: 요청이 세션 예산을 늘리거나 제거하여 재개되는 각 턴의 anthropic.session.turn 스팬.

anthropic.session.turn

• 출처: Managed Agents 세션에 대한 API.
• 종류: INTERNAL.
• 부모: 턴이 시작된 이유에 따라 다릅니다:
  • 비어 있지 않은 initial_events로 생성된 세션의 첫 번째 턴인 경우, anthropic.sessions.create 스팬.
  • user.message 이벤트와 같은 이벤트로 인해 시작된 턴인 경우, 해당 이벤트가 전송된 요청에 대한 anthropic.sessions.events.send 스팬.
  • 요청을 통해 세션 예산이 늘어나거나 제거되어 재개되는 턴인 경우, anthropic.sessions.update 스팬.
  • 다른 스레드의 턴인 경우, 세션이 실행하는 에이전트가 이 턴을 시작한 해당 에이전트의 턴의 anthropic.session.turn 스팬.
  • 기본 에이전트가 호출한 에이전트처럼 다른 스레드의 에이전트가 응답하거나 턴을 마쳐서 시작되는 턴인 경우, 없음.
• 자식:
  • 턴 내 각 모델 요청에 대한 anthropic.model_request 스팬.
  • 도구 스팬 섹션에 나열된 경우를 제외하고, API가 턴에서 도구를 실행할 때마다 생성되는 도구 스팬.
  • 이 턴 동안 세션이 실행하는 에이전트가 다른 스레드에서 시작한 각 턴에 대한 anthropic.session.turn 스팬.
  • 이 턴이 시작하는 결과 평가의 각 반복에 대한 anthropic.session.outcome_evaluation 스팬.

턴은 해당 스레드가 running 상태에 들어갈 때 시작되고 스레드가 그 상태를 벗어날 때 끝납니다.

anthropic.model_request

• 출처: Messages API 요청 및 Managed Agents 세션에 대한 API.
• 종류: INTERNAL.
• 부모:
  • Messages API: 요청에 대한 anthropic.messages.create 스팬.
  • Managed Agents: 요청을 수행하는 턴의 anthropic.session.turn 스팬.
• 자식: 없음.

Messages API에서 각 스팬은 API 요청 내의 하나의 모델 요청입니다.

이 스팬에는 토큰 사용량 속성이 있습니다.

anthropic.tool_use, anthropic.mcp_tool_use, anthropic.custom_tool_use

• 출처: SDK와 API.
• 이름: anthropic.tool_use <tool>, anthropic.mcp_tool_use <tool> 또는 anthropic.custom_tool_use <tool>이며, 여기서 <tool>은 도구의 이름입니다.
• 종류: INTERNAL.
• SDK 스팬의 부모: 도구가 시작될 때 애플리케이션에서 현재 활성화된 스팬으로, Messages 도구 러너에서는 anthropic.messages.tool_runner 스팬입니다. 현재 스팬이 없으면 부모가 없습니다.
• API 스팬의 부모:
  • Messages API: API가 도구를 실행하는 요청의 anthropic.messages.create 스팬.
  • Managed Agents: 도구가 실행되는 턴의 anthropic.session.turn 스팬. user.tool_confirmation 이벤트를 기다리는 도구 사용의 경우, 확인으로 인해 시작되는 턴입니다.
  • 다른 도구가 실행하는 코드에서의 도구 사용의 경우, 해당 도구의 도구 스팬. Messages API에서 그 도구는 코드 실행 도구입니다.
• SDK 스팬의 자식: 도구의 코드가 시작하는 스팬.
• API 스팬의 자식: 이 도구가 실행하는 코드에서의 각 도구 사용에 대한 도구 스팬. 예를 들어, 코드 실행 도구가 실행하는 코드는 web_search를 사용할 수 있습니다.

스팬 이름의 접두사는 도구 유형에 따라 다릅니다:

• anthropic.tool_use <tool>은 Messages API에서 서버 도구의 각 사용 또는 Managed Agents의 에이전트 도구 세트에 있는 도구의 각 사용에 대한 스팬입니다. API가 에이전트 도구 세트 도구를 실행하지만, 자체 호스팅 샌드박스에서는 환경 워커가 실행합니다.
• anthropic.mcp_tool_use <tool>은 SDK, Messages API 및 Managed Agents에서 MCP 도구를 사용할 때마다 생성되는 스팬입니다. SDK에서는 Messages 도구 러너 또는 세션 도구 러너가 실행하는 MCP 헬퍼의 도구입니다. Messages API에서는 도구가 MCP 커넥터에서 제공됩니다. Managed Agents에서 MCP 서버 연결이 실패하면 스팬 이름에 도구 이름이 포함되지 않습니다.
• anthropic.custom_tool_use <tool>은 애플리케이션이 정의하고 도구 러너가 실행하는 도구를 사용할 때마다 생성되는 스팬입니다. 이 스팬은 SDK만 내보냅니다.

API는 다음 경우에 도구 스팬을 내보내지 않습니다:

• 모델이 사용자 정의 도구와 같이 애플리케이션이 실행하는 도구의 사용을 요청하는 경우. SDK의 도구 러너가 도구를 실행하면 도구 러너가 해당 스팬을 내보냅니다.
• Managed Agents: 에이전트가 자체 호스팅 샌드박스에서 실행되는 도구를 사용하는 경우. 도구를 실행하는 SDK의 워커가 해당 스팬을 내보냅니다. 자체 호스팅 샌드박스를 트레이스하는 방법을 참조하세요.
• Managed Agents: 에이전트가 멀티에이전트 도구 또는 어드바이저 도구를 사용하는 경우.
• Managed Agents: 에이전트가 도구 사용을 요청했지만, 서버가 auto 권한 정책에 따라 사용을 거부하거나 애플리케이션이 user.tool_confirmation 이벤트에서 거부하는 경우.

anthropic.compaction

• 소스: Messages API 요청의 경우 API.
• 종류: INTERNAL.
• 부모: 요청에 대한 anthropic.messages.create span.
• 자식: 없음.

이 span에는 compaction의 토큰 사용량 속성이 있습니다. anthropic.messages.create에서는 compaction의 사용량이 gen_ai.usage.* 합계 대신 anthropic.usage.compaction.* 속성에 있습니다.

anthropic.session.outcome_evaluation

• 소스: Managed Agents 세션의 경우 API.
• 종류: INTERNAL.
• 부모: 반복(iteration)을 시작한 턴의 anthropic.session.turn span이며, 해당 턴이 반복보다 먼저 끝나는 경우에도 마찬가지입니다.
• 자식: 없음.

결과가 interrupted이면 상태는 설정되지 않으며, 그 외의 결과에서는 OK입니다.

이 span에는 토큰 사용량 속성 중 두 가지, 즉 gen_ai.usage.input_tokens와 gen_ai.usage.output_tokens가 있습니다.

anthropic.messages.tool_runner

• 소스: SDK.
• 종류: INTERNAL.
• 부모: 루프가 시작될 때 애플리케이션에서 현재 활성화된 span이며, 현재 span이 없으면 없음.
• 자식: 루프 내 각 요청의 anthropic.messages.create span과 runner가 실행하는 각 도구 사용의 도구 span.

이 span은 루프와 함께 종료됩니다. 애플리케이션이 runner를 중지하면 상태는 설정되지 않습니다. 도구의 코드에서 오류가 발생하면 해당 도구 span의 상태는 ERROR가 되고 루프는 계속됩니다. 이 span에는 사용량 속성이 없으므로, 사용량은 자식인 anthropic.messages.create span에서 읽으세요.

anthropic.messages.batches.<method>

• 소스: 모든 Message Batches 메서드의 경우 SDK.
• 종류: CLIENT.
• 부모: 애플리케이션이 메서드를 호출할 때 현재 활성화된 span이며, 현재 span이 없으면 없음.
• 자식: 없음.

이 span에는 모든 요청에 대한 SDK span의 속성도 있습니다.

anthropic.sessions.<method>

• 소스: SDK와 API.
• 종류: SDK에서는 CLIENT, API에서는 SERVER.
• SDK span의 부모: 애플리케이션이 메서드를 호출할 때 현재 활성화된 span이며, 현재 span이 없으면 없음.
• API span의 부모: 요청의 traceparent 헤더에 있는 span으로, 요청이 SDK에서 온 경우 SDK span이며, 헤더가 없으면 없음.
• SDK span의 자식: 동일한 요청에 대한 API의 span.
• API span의 자식: 없음.

API는 Sessions API의 엔드포인트에 대한 인증된 각 요청마다 anthropic.sessions.<method> span을 내보냅니다. Claude Console에서 보낸 메시지나 예약된 배포가 시작하는 세션처럼 플랫폼이 사용자를 대신하여 보내는 요청에도 span이 있으며, 각각 새 trace에 속합니다.

이 span에는 세션 속성이 있습니다. SDK span에는 모든 요청에 대한 SDK span의 속성도 있습니다.

anthropic.environment.work

• 소스: CLI와 Python, TypeScript, Go의 SDK.
• 종류: INTERNAL.
• 부모: environment worker 또는 work poller가 작업 항목을 가져올 때 애플리케이션에서 현재 활성화된 span이며, 현재 span이 없으면 없음. ant beta:worker poll에서는 이 span이 루트 span입니다.
• 자식: environment worker가 작업 항목을 처리하는 동안 보내는 요청에 대한 span과, 작업 항목을 위해 실행하는 각 도구의 도구 span.

environment worker와 work poller는 self-hosted sandbox에서 작업 항목을 가져가는 SDK 헬퍼입니다. 이들은 각 작업 항목마다 하나의 anthropic.environment.work span을 내보내며, 이 span은 poll이 작업 항목을 반환한 시점부터 해당 항목의 처리가 끝날 때까지를 포함합니다.

anthropic.<resources>.<method>

• 소스: SDK.
• 종류: CLIENT.
• 부모: 애플리케이션이 메서드를 호출할 때 현재 활성화된 span이며, 현재 span이 없으면 없음.
• 자식: 없음.

요청을 보내면서 이 페이지에 별도 섹션이 없는 각 SDK 메서드는 anthropic.<resources>.<method> span을 내보냅니다. 예를 들어 anthropic.models.list 또는 anthropic.files.upload입니다. 목록의 이후 각 페이지에 대한 요청은 자체 span을 가집니다.

span은 재시도를 포함하여 요청 전체를 포괄하며, SDK가 값을 가지고 있는 경우 동일한 이름의 API span의 각 속성을 가집니다. SDK는 span을 시작할 때 http.request.method와 http.route를 설정하므로, sampler가 이를 사용할 수 있습니다.

anthropic.messages.create, anthropic.messages.count_tokens, anthropic.messages.batches.<method>를 포함한 모든 요청에 대한 SDK span에는 다음 속성이 있습니다: