관리자OpenTelemetry

Claude API용 OpenTelemetry

Copy page



Claude SDK와 Claude API의 OpenTelemetry 스팬으로 Messages API 요청, 도구 사용, Managed Agents 세션을 추적합니다.

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

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

시작하기

SDK 추적, API 추적 또는 둘 다를 설정할 수 있습니다. 예제 트레이스에서처럼 요청의 SDK 스팬과 API 스팬을 하나의 트레이스에서 보려면 둘 다 설정하세요. Claude Platform on AWS에 대한 요청의 경우, API 스팬은 대신 별도의 트레이스에 있습니다.

Claude Code, Agent SDK 또는 Cowork의 경우 Claude Code 모니터링, Agent SDK 관측성 또는 Cowork 활동 모니터링을 참조하세요.

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

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

콘텐츠 모드

각 대상과 각 SDK 클라이언트에는 스팬에 모델 프롬프트와 응답을 포함할지 여부를 설정하는 콘텐츠 모드가 있습니다. 대상을 추가하거나 SDK를 구성할 때 설정하세요.

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

Full content를 사용하면 실행이 실패하거나 느렸던 이유를 확인하고, 전체 대화를 읽고, 실제 트레이스로 평가를 구축할 수도 있습니다. OpenTelemetry 스팬 레퍼런스에서 프롬프트와 응답을 담는 속성에는 Content 태그가 붙어 있습니다.

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

제로 데이터 보존을 사용하는 경우에도 Full content를 사용할 수 있습니다. Messages API 요청의 경우, API는 내보낸 콘텐츠를 대상으로 전달할 때까지만 메모리에 보관합니다. Claude Managed Agents는 제로 데이터 보존 대상이 아니며, 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를 설정하세요. Console에서는 대상을 추가할 때 Content mode를 Full content로 설정한 다음, Advanced settings에서 Maximum content size in MB를 설정하세요.

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

Messages API 요청

메시지를 생성하는 요청의 API 스팬 아래에, API는 각 모델 요청에 대한 스팬과 API가 실행하는 서버 도구 또는 MCP 커넥터 도구의 각 사용에 대한 도구 스팬을 추가합니다.

이 예제에서 애플리케이션은 도구를 실행하고 그 결과를 Claude에 다시 보내는 SDK 헬퍼인 도구 실행기를 호출합니다. 도구 실행기가 보내는 각 요청에는 SDK의 클라이언트 스팬과 API의 서버 스팬이 있습니다. 스팬은 다음 순서로 나타납니다:

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

애플리케이션의 SDK는 anthropic.messages.tool_runner 스팬, anthropic.custom_tool_use 스팬, 그리고 각 요청의 클라이언트 스팬을 생성합니다. 이러한 스팬을 받으려면 SDK 추적을 설정하세요.

각 요청의 토큰 사용량은 여러 스팬에 기록됩니다. 각 토큰을 한 번만 계산하려면 토큰 계산을 참조하세요.

Full content를 사용하면 anthropic.messages.create 서버 스팬에 프롬프트와 응답이 포함됩니다. 시스템 프롬프트는 gen_ai.system_instructions에, 요청의 메시지는 gen_ai.input.messages에, 응답은 gen_ai.output.messages에 있습니다.

각 스팬과 해당 속성은 OpenTelemetry 스팬 레퍼런스를 참조하세요.

Managed Agents 세션

세션에는 각 Sessions API 요청에 대한 span과 각 에이전트 턴에 대한 턴 span이 있습니다. 요청이 시작한 턴은 해당 요청 span의 자식입니다. 턴에는 각 모델 요청과 API가 실행하는 각 도구에 대한 span이 포함되며, 도구 span 참조에 나열된 경우는 예외입니다. 또한 각 결과 평가에 대한 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. 모델이 사용자 정의 도구 list_issues의 사용을 요청하므로, 턴은 중지 사유 requires_action으로 종료됩니다.
6. 세션 도구 러너가 list_issues를 실행하고(anthropic.custom_tool_use list_issues span으로 표시됨) sessions.events.send를 호출하여 그 결과를 보냅니다.
7. 도구 결과와 함께 두 번째 턴이 시작됩니다(마지막 anthropic.session.turn span으로 표시됨).

애플리케이션의 SDK는 anthropic.custom_tool_use span과 각 요청의 클라이언트 span을 내보냅니다. 이러한 span을 얻으려면 SDK 트레이싱을 설정하세요.

세션의 span은 여러 트레이스에 걸쳐 있을 수 있습니다. 예를 들어 새 루트 트레이스에서 이후 요청을 보내는 경우입니다. 멀티에이전트가 켜져 있으면 세션에 여러 스레드가 있을 수도 있습니다. 필요한 span을 찾으려면 ID로 그룹화하세요.

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

Full content를 사용하면 세션의 span에서 세션의 콘텐츠를 읽을 수 있습니다.

• 턴의 콘텐츠를 읽으려면 해당 턴 span을 사용하세요. 시스템 프롬프트는 스레드의 첫 번째 턴 span의 gen_ai.system_instructions에, 입력은 gen_ai.input.messages(사용자의 메시지와 도구 결과, system.message 이벤트, 다른 스레드의 메시지)에, 출력은 gen_ai.output.messages(에이전트의 메시지, 도구 사용, 도구 결과)에 있습니다.
• 도구 사용의 인수와 결과를 보려면 해당 도구 span을 읽으세요. 인수는 gen_ai.tool.call.arguments에, 결과는 anthropic.tool_result.content에 있습니다.

각 span과 그 속성에 대해서는 OpenTelemetry span 참조를 참조하세요.

토큰 계산

각 토큰을 한 번만 계산하려면 각 요청에 대해 하나의 소스의 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 span을 합산하세요. 요청에 컴팩션이 있는 경우, gen_ai.usage.* 속성에는 컴팩션 토큰이 포함되지 않으므로 span의 anthropic.usage.compaction.input_tokens와 anthropic.usage.compaction.output_tokens도 더하세요. 폴백 모델이 요청을 처리한 경우, 해당 span에는 응답을 처리한 모델의 사용량만 포함됩니다.
• Messages API 요청의 API span: anthropic.messages.create span 또는 그 anthropic.model_request span 중 하나만 합산하고, 둘 다 합산하지 마세요. 요청에 컴팩션이 있는 경우 해당 anthropic.compaction span도 더하세요. anthropic.messages.create span의 anthropic.usage.compaction.* 속성은 같은 토큰을 담고 있으므로 추가로 더하지 마세요.
• Managed Agents 세션의 API span: anthropic.model_request 및 anthropic.session.outcome_evaluation span을 합산하세요.

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

gen_ai.usage.input_tokens에는 이미 프롬프트 캐시에서 읽거나 쓴 토큰이 포함되어 있으므로 캐시 속성을 더하지 마세요. 모든 사용량 속성에 대해서는 토큰 사용량을 참조하세요.