Claude API에서 OpenTelemetry 사용하기

OpenTelemetry를 사용하면 Claude API는 실행하는 각 모델 요청과 각 도구 사용에 대해 "span"(스팬)을 내보낼 수 있습니다. 코드를 변경하지 않고도 관측성 플랫폼에서 이러한 스팬을 확인할 수 있습니다.

API는 Messages API 요청과 Managed Agents 세션에 대한 스팬을 생성합니다. 이를 받으려면 Claude Console에서 "destination"(대상)을 추가하세요. 대상은 API에 관측성 플랫폼의 OTLP 엔드포인트와 인증 방법을 알려줍니다.

필요한 것

• Claude Console 조직의 관리자 역할. 대상을 추가하고 변경하려면 이 역할이 필요합니다. 개발자 역할로는 대상을 볼 수 있습니다. 조직이 Claude Platform on AWS를 사용하는 경우, 로그인에 설명된 대로 AWS Console을 통해 Console에 로그인하세요.
• 포트 443의 HTTPS URL에서 protobuf 인코딩을 허용하는 OTLP/HTTP 엔드포인트. 자체 OpenTelemetry Collector를 운영하는 경우, 해당 OTLP/HTTP 수신기는 기본적으로 포트 4318에서 수신 대기합니다. 수신기가 포트 443에서 HTTPS를 허용하도록 구성하거나, Collector 앞에 로드 밸런서 또는 리버스 프록시를 두세요.
• API 키와 같은 엔드포인트 자격 증명.

1. 대상 추가

1. Console에서 조직의 OpenTelemetry 설정 페이지를 열고 Add destination을 클릭하세요.

2. 대상을 구성하세요:

   필드	입력할 내용
   Provider	사용하는 관측성 플랫폼, 또는 목록에 없는 경우 Custom. 목록에 있는 플랫폼을 선택하면 Console에서 OTLP endpoint URL, Request headers, OTLP traces endpoint URL 대신 API 키와 같은 해당 플랫폼의 세부 정보를 요청합니다.
   Name	선택 사항입니다. 예: "Acme의 관측성 플랫폼."
   OTLP endpoint URL	IP 주소가 아닌 호스트 이름을 사용하는 관측성 플랫폼 OTLP/HTTP 엔드포인트의 기본 HTTPS URL. 경로 접두사를 포함할 수 있습니다(예: https://gateway.example.com/otlp). API가 /v1/traces를 추가하므로 이를 직접 추가하지 마세요. OTLP traces endpoint URL을 설정한 경우 API는 그 URL을 대신 사용합니다.
   Request headers	API가 각 요청과 함께 보내는 헤더입니다(예: 관측성 플랫폼의 API 키 헤더). 자격 증명은 헤더 값에만 넣으세요. 저장한 후에는 Console에서 값을 다시 표시하지 않습니다.
   Content mode	Metadata only 또는 Full content. 콘텐츠 모드의 차이점을 참조하세요.
   Workspaces	대상이 스팬을 받을 워크스페이스: All, Selected 또는 All except. 대상의 워크스페이스 선택을 참조하세요.
   OTLP traces endpoint URL	선택 사항으로, Advanced settings 아래에 있습니다. 관측성 플랫폼 트레이스 엔드포인트의 전체 URL(예: https://gateway.example.com/custom/traces). 해당 플랫폼이 OTLP endpoint URL에 /v1/traces를 더한 URL이 아닌 다른 URL에서 트레이스를 받는 경우 설정하세요. OTLP endpoint URL과 동일한 호스트여야 합니다.
   Maximum content size in MB	선택 사항으로, 콘텐츠 모드가 Full content인 경우 Advanced settings 아래에 있습니다. API가 각 스팬에서 보내는 최대 콘텐츠 크기입니다. 선택한 Provider에 따라 Console이 이 값을 채웁니다. 관측성 플랫폼이 허용하는 크기에 맞게 변경하세요. 비워 두면 API가 허용하는 최대 크기까지 보냅니다. 콘텐츠 제한을 참조하세요.

3. Add destination을 클릭하여 저장하세요.

4. 대상의 More actions 메뉴에서 Test를 클릭하세요. 테스트 스팬이 컬렉터로 전송되었는지, 또는 전송이 어떻게 실패했는지 알려 주는 메시지가 표시됩니다(전송 오류 참조).

5. anthropic.test 스팬이 관측성 플랫폼에 도착했는지 확인하세요.

Admin API 및 CLI

Console 대신 Admin API를 통해 대상을 추가할 수도 있습니다. CLI에 관리자로 로그인하거나, ANTHROPIC_API_KEY에 Admin API 키를 사용하세요. Claude Platform on AWS에서는 대신 https://aws-external-anthropic.{region}.api.aws로 요청을 보내고, 요청 보내기에서와 같이 AWS 자격 증명으로 서명하세요. 이 경우 대상을 관리할 수 있는 사람은 IAM 정책에 따라 결정됩니다. 요청에는 해당 리전에 있는 AWS 계정의 워크스페이스만 포함할 수 있습니다.

client = anthropic.Anthropic()

destination = client.beta.organization.telemetry_destinations.create(
    endpoint_url="https://gateway.example.com/otlp",
    headers={"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
    traces={"content_mode": "metadata_only"},
    workspaces={"type": "all"},
)

print(destination.id)

생성 요청은 Provider를 제외한 Console의 설정을 받으므로, 관측성 플랫폼의 엔드포인트 URL과 헤더를 직접 입력하세요. 관측성 플랫폼이 허용하는 크기에 맞게 traces.max_content_bytes를 바이트 단위로 설정하세요(콘텐츠 제한 참조). 대상을 나열, 변경 또는 삭제하거나 워크스페이스 하나를 추가하거나 제거하려면 텔레메트리 대상 API의 다른 메서드를 사용하세요.

2. 대상의 워크스페이스 선택

대상은 자신이 포함하는 워크스페이스의 스팬을 받습니다. 대상을 추가할 때 워크스페이스를 선택하세요. Workspaces에서 다음 중 하나를 선택하세요:

• All: Default Workspace와 나중에 생성되는 워크스페이스를 포함하여 조직의 모든 워크스페이스.
• Selected: 선택한 워크스페이스만.
• All except: All과 같지만 선택한 워크스페이스는 제외.

Selected 또는 All except의 경우, 옵션 아래에 나타나는 검색 상자에서 워크스페이스를 선택하세요. 나중에 대상의 워크스페이스를 변경하려면, Workspace 필터가 All로 표시된 상태에서 OpenTelemetry 설정 페이지의 해당 대상 More actions 메뉴를 여세요. Edit을 클릭한 다음 다른 Workspaces 옵션을 선택하거나 검색 상자에서 워크스페이스를 변경하세요.

조직에서 개발자 역할이 있고 어떤 워크스페이스에서 Workspace Admin 역할을 가지고 있다면, Selected 대상에 해당 워크스페이스를 추가하거나 대상에서 제거할 수 있습니다. Workspace 필터를 해당 워크스페이스로 설정한 다음 대상의 More actions 메뉴를 여세요. Claude Platform on AWS에서는 Console에 Workspace Admin 역할이 없습니다. 이 경우 IAM 정책에 따라 누가 대상에 워크스페이스를 추가하거나 대상에서 제거할 수 있는지가 결정됩니다.

API는 요청이나 세션이 실행되는 워크스페이스를 포함하는 모든 활성화된 대상으로 스팬을 전송합니다.

3. 스팬 도착 확인

1. Console에서 해당 대상이 적용되는 워크스페이스를 선택하고 playground에서 Messages API 요청을 보내세요. 애플리케이션에서 Messages API 요청을 보내거나 해당 워크스페이스에서 Managed Agents 세션을 시작할 수도 있습니다. 세션을 시작하려면 Claude Managed Agents 시작하기의 단계를 따르세요.
2. Console의 OpenTelemetry 설정 페이지에서 대상의 Delivery 열에 Healthy가 표시되는지 확인하세요. 약 1분 정도 걸릴 수 있습니다.
3. 관측성 플랫폼에서 service.name = claude-platform으로 필터링하여 요청의 스팬을 찾으세요.

열에 Failing이 표시되면 포인터를 그 위에 올려 마지막 오류를 확인하세요. 가능한 원인을 찾으려면 전송 오류를 참조하세요.

4. API 스팬을 자체 트레이스에 연결

기본적으로 Messages API 요청이나 Managed Agents 세션의 API 스팬은 별도의 트레이스에 있습니다. 이를 애플리케이션의 트레이스에 연결하여 자체 스팬 아래에 중첩되도록 하세요.

API는 W3C traceparent 헤더에서 각 요청의 트레이스 컨텍스트를 읽습니다. 헤더의 sampled 플래그가 꺼져 있으면 API는 해당 요청의 스팬과 그 아래의 스팬을 생성하지 않습니다. Claude Platform on AWS는 아직 이 헤더를 지원하지 않습니다. sampled 플래그가 꺼져 있더라도 이 플랫폼으로 보내는 요청의 스팬은 항상 별도의 트레이스를 시작합니다.

from opentelemetry import trace

tracer = trace.get_tracer("my-service")

with tracer.start_as_current_span("summarize_issues"):
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    )

import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

headers = {
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
    "anthropic-beta": "managed-agents-2026-04-01",
    "content-type": "application/json",
}
# 활성 span의 trace context를 요청 헤더에 복사합니다.
TraceContextTextMapPropagator().inject(headers)

httpx2.post(
    f"https://api.anthropic.com/v1/sessions/{os.environ['SESSION_ID']}/events",
    headers=headers,
    json={
        "events": [
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    },
)

Messages API는 또한 MCP connector로 MCP 서버를 연결하면 그 서버로 트레이스를 전달하므로, 해당 서버가 자체 스팬을 API 스팬 아래에 둘 수 있습니다. API가 MCP 서버로 보내는 각 요청과 알림에는 params._meta에 W3C traceparent가 포함됩니다. tools/call 요청에서는 해당 도구 사용의 anthropic.mcp_tool_use 스팬을 가리킵니다. 그 외의 메시지에서는 anthropic.messages.create 스팬을 가리킵니다. traceparent 헤더의 sampled 플래그가 꺼져 있는 요청처럼 API가 트레이스하지 않는 요청의 경우, API는 traceparent를 보내지 않습니다.

다음 단계

전송 및 상태

API가 대상으로 보내는 스팬에는 다음 규칙이 적용됩니다.

• 최소 1회 전송: 대상은 같은 스팬을 두 번 이상 받을 수 있습니다. 중복을 제거하려면 트레이스 ID와 스팬 ID를 사용하세요.
• 최선 노력(best effort): 스팬은 전송 전에 유실될 수 있습니다. API는 유실된 스팬을 다시 보낼 수 없습니다.
• 압축: API는 모든 전송의 첫 번째 요청을 gzip으로 압축하고 Content-Encoding: gzip 헤더를 설정합니다. 엔드포인트가 해당 요청에 400 또는 415 응답을 반환하면, API는 즉시 압축 없이 같은 스팬을 다시 보냅니다.
• 재시도: 타임아웃, 연결·TLS·DNS 실패, 또는 408, 429, 5xx 응답 후에는 API가 제한된 횟수만큼 나중에 전송을 다시 시도합니다. 다른 실패에 대해서는 재시도하지 않습니다.
• 타임아웃: 각 요청에 대해 엔드포인트는 5초 이내에 TLS 핸드셰이크를 완료하고 5초 이내에 응답 헤더를 보내야 합니다. 각 전송은 압축 없이 다시 보내는 요청을 포함하여 총 10초 후에 타임아웃됩니다.
• 사용자 에이전트: 각 요청에는 User-Agent: Claude-Platform 헤더가 있습니다.

Delivery 열은 각 대상의 상태를 보여줍니다. 상태는 최대 1분까지 늦게 반영될 수 있습니다.

API는 다음과 같은 경우 대상을 비활성화합니다:

• 엔드포인트가 3xx 리디렉션을 보내는 경우.
• 엔드포인트의 호스트 이름이 공용이 아닌 IP 주소로 확인되는 경우.
• 24시간 동안 모든 전송이 실패하는 경우.

API는 비활성화된 대상에 span을 보내지 않습니다. 내보내기를 다시 시작하려면 원인을 해결하세요. 그런 다음 OpenTelemetry 설정 페이지의 Workspace 필터가 All을 표시하는 상태에서, 대상의 More actions 메뉴에서 Enable을 클릭하세요. 약 1분 이내에 내보내기가 다시 시작됩니다.

대상을 변경하려면 Workspace 필터가 All을 표시하는 상태에서 해당 대상의 More actions 메뉴를 여세요. 그런 다음 Edit, Disable, Enable 또는 Delete를 클릭하세요. OTLP endpoint URL의 호스트를 변경하는 경우 헤더 값을 다시 입력하세요. 대상에 OTLP traces endpoint URL이 있는 경우, 동일한 새 호스트를 지정하거나 값을 지우세요.

제한

문제 해결

전송 오류

전송이 실패하면 Delivery 열에 Failing이 표시됩니다. 그 위에 포인터를 올려 오류를 확인한 다음, 가능한 원인을 찾아보세요:

Compatibility