Claude API OpenTelemetry 연동하기: SDK·API 추적으로 느린 요청 찾기

Claude API의 SDK·API 추적을 연결하면 느린 요청을 모델 실행·도구 호출 구간으로 나눠 볼 수 있습니다. Anthropic이 10월 14일 발표한 OpenTelemetry export는 베타입니다. Python의 직접 Messages API 호출을 기준으로 설명합니다.

먼저 구분할 용어

용어이 글에서의 의미

OpenTelemetry	요청의 실행 구간과 속성을 수집·전송하는 표준 도구 체계
span	시작·종료 시각과 속성을 담은 실행 구간
trace	한 요청에 연결된 span들의 묶음
OTLP	수집기로 추적 데이터를 보내는 프로토콜

SDK는 앱의 요청을, API는 서버의 모델 실행과 도구를 추적합니다. 양쪽 전송 설정이 필요합니다.

1. Python 앱에서 SDK span 출력하기

가상환경에 설치합니다. 기존 앱은 SDK 호환성을 확인하세요.

python -m pip install --upgrade anthropic opentelemetry-sdk

아래는 공식 문서 기반 예제이며 실행 미검증 코드입니다. 실행 환경에 ANTHROPIC_API_KEY와 사용할 모델 ID인 CLAUDE_MODEL을 설정한 뒤 파일로 저장해 실행합니다. API 요청 비용이 발생할 수 있습니다.

import os
from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    ConsoleSpanExporter, SimpleSpanProcessor,
)

provider = TracerProvider()
provider.add_span_processor(
    SimpleSpanProcessor(ConsoleSpanExporter())
)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer("claude-demo")

try:
    with tracer.start_as_current_span("ask_claude"):
        Anthropic().messages.create(
            model=os.environ["CLAUDE_MODEL"],
            max_tokens=128,
            messages=[{"role": "user", "content": "HTTP를 한 문장으로 설명해 주세요."}],
        )
finally:
    provider.shutdown()

Claude SDK 문서에 따라 첫 호출 전에 provider를 등록합니다. 터미널에서 anthropic.messages.create span을 확인하세요.

수집기로 전송하려면 OpenTelemetry Python Exporters 문서에 따라 opentelemetry-exporter-otlp-proto-http를 설치하고 OTLPSpanExporter와 BatchSpanProcessor로 바꿉니다. exporter의 endpoint에는 /v1/traces까지 포함한 전체 주소를 넣습니다.

2. Console에서 서버 API 추적 연결하기

Claude API 설정 문서가 요구하는 준비물은 조직 admin 권한과 HTTPS 443에서 protobuf를 받는 OTLP/HTTP 수신지, 해당 수신지의 인증 정보입니다.

1. Console의 OpenTelemetry 설정에서 destination을 생성합니다.
2. 수신지·인증 헤더·대상 workspace를 설정합니다.
3. 기본 OTLP endpoint URL에는 호스트명이 있는 기본 주소를 넣습니다. 여기는 /v1/traces를 붙이지 않습니다. 별도 OTLP traces endpoint URL에는 전체 경로를 넣습니다.
4. 저장 후 Test를 실행하고 수집 화면에 anthropic.test가 도착하는지 확인합니다.

이어서 대상 workspace의 API 키로 요청을 보냅니다. 위 예제처럼 활성 span 안에서 SDK를 호출하고, W3C traceparent가 전파되며, 양쪽 데이터를 같은 플랫폼으로 보내야 앱과 API 구간을 연결할 수 있습니다. sampled flag가 꺼져 있으면 API 요청과 하위 span은 내보내지지 않습니다.

3. 긴 요청에서 읽을 순서

긴 trace 하나를 골라 Anthropic의 OpenTelemetry span reference에 나온 항목을 비교합니다.

확인 항목읽는 방법

같은 이름의 요청 span	SDK는 CLIENT, API는 SERVER입니다. API의 service.name은 claude-platform입니다.
anthropic.model_request와 도구 span	하위 구간 중 어디에 시간이 많이 쓰였는지 좁힙니다.
gen_ai.response.time_to_first_chunk	첫 content_block_delta까지 걸린 초 단위 시간입니다. 전체 응답 시간과 구분합니다.

CLIENT와 SERVER 시간 차이를 그대로 네트워크 지연이라고 단정할 수는 없습니다. 스트리밍 SDK span은 끝까지 읽거나 닫아야 종료되므로, 읽기를 중단한 스트림을 닫지 않았는지도 점검하세요.

수집 범위는 작게 시작하기

Anthropic의 OpenTelemetry 개요에 따르면 기본 metadata_only는 시간·상태·토큰 수 등을 담습니다. 사용자 지정 도구명 같은 텍스트도 포함될 수 있습니다. content를 켜면 프롬프트와 응답까지 전송되므로 수집 플랫폼의 접근 권한과 보관 정책을 먼저 정해야 합니다.

SDK와 API 양쪽의 토큰 수를 합산하면 중복 집계됩니다. API span 전달은 손실이나 중복이 가능한 best effort 방식이므로 완전한 요청 장부로 취급하지 마세요.

테스트 요청의 SDK·API span을 연결한 뒤 긴 구간을 비교하세요. 실제 원인은 추가 계측으로 검증해야 합니다.

참고 링크

• Anthropic — Set up OpenTelemetry with the Claude SDK
• Anthropic — Set up OpenTelemetry with the Claude API