Claude SDK에서 OpenTelemetry 사용하기

OpenTelemetry를 사용하면 Claude SDK는 전송하는 각 요청과 도구 실행기가 실행하는 각 도구 사용에 대해 "span"(스팬)을 내보낼 수 있습니다. 이러한 스팬은 관측성 플랫폼에서 자체 트레이스 안에 중첩된 형태로 확인할 수 있습니다.

SDK는 애플리케이션 내에서 스팬을 생성합니다. 애플리케이션의 OpenTelemetry 익스포터(exporter)가 이를 관측성 플랫폼으로 전송합니다.

1. SDK 설치

Claude SDK의 최신 버전을 설치하거나 업그레이드하세요:

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. 트레이서 프로바이더 등록

"Tracer provider"(트레이서 프로바이더)는 스팬을 생성하고 이를 익스포터에 전달하는 OpenTelemetry 객체입니다. SDK는 애플리케이션이 등록한 트레이서 프로바이더를 사용하므로 SDK 호출 코드는 그대로 유지됩니다. 추적하려는 첫 번째 호출 전에 등록하세요.

다음 예제는 각 스팬을 콘솔에 출력하는 트레이서 프로바이더를 등록한 다음 한 번의 호출을 수행합니다. 관측성 플랫폼을 연결하기 전에 스팬을 확인하는 데 사용하세요:

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

# 각 span을 콘솔에 출력하는 tracer provider를 등록합니다.
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

client = Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)

콘솔에 하나의 anthropic.messages.create 스팬이 표시됩니다.

3. 관측성 플랫폼으로 스팬 전송

콘솔 익스포터를 관측성 플랫폼을 가리키는 OTLP 익스포터로 교체하세요. 사용하는 언어의 설정 방법은 OpenTelemetry 문서의 Python 익스포터, TypeScript 익스포터, .NET 익스포터, Go 익스포터, Java SDK 구성, PHP 익스포터, 또는 Ruby 익스포터를 참조하세요.

4. SDK 구성

다음 옵션을 사용하여 스팬에 포함될 내용과 스팬이 전송될 위치를 결정하세요. 각 옵션은 코드에서 설정하거나, 환경 변수가 있는 경우 옵션 이름 아래에 표시된 환경 변수로 설정할 수 있습니다.

다음 예제는 각 옵션을 사용하는 방법을 보여줍니다:

# 특정 tracer provider를 사용하고 콘텐츠를 기록합니다.
# open_telemetry를 설정하면 모든 ANTHROPIC_OPEN_TELEMETRY* 환경 변수가 재정의됩니다.
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# 한 클라이언트에 대해 span을 끕니다.
quiet_client = Anthropic(open_telemetry=False)

# 클라이언트의 복사본을 반환하는 with_options()로 대화 ID를 설정합니다.
# with_options()는 옵션 전체를 대체하므로 client.open_telemetry에서 시작하세요.
message = client.with_options(
    open_telemetry={**client.open_telemetry, "conversation_id": "conv_42"}
).messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

다음 단계

스트림 추적

스트림의 anthropic.messages.create 스팬은 코드가 스트림 전체를 읽거나 스트림을 닫을 때 종료되므로, 중간에 읽기를 멈춘 스트림은 닫아 주세요. 콘텐츠 모드에서는 messages.stream()로 스트림을 읽을 때만 스팬에 모델 응답이 포함됩니다.

스트림을 읽는 동안 시작한 스팬은 SDK 스팬의 자식이 아니라 형제 스팬이 됩니다. 이를 요청과 함께 그룹화하려면 호출과 읽기 루프를 모두 감싸는 자체 스팬을 시작하세요.

Managed Agents 자체 호스팅 샌드박스 추적

Managed Agents 자체 호스팅 샌드박스에서는 샌드박스가 도구를 실행하므로 도구 스팬이 API가 아닌 SDK에서 생성됩니다. Python, TypeScript, Go SDK의 환경 워커는 자신이 실행하는 각 도구와 보내는 각 요청에 대해 스팬을 생성합니다. 워커는 이러한 스팬을 각 작업 항목마다 하나의 anthropic.environment.work 스팬 아래에 묶습니다.

이러한 스팬을 받으려면 다음을 수행하세요:

1. 워커를 실행하는 프로세스에서 1~4단계와 같이 SDK 추적을 설정하세요.
2. 샌드박스에서 관측성 플랫폼 또는 OpenTelemetry Collector로의 네트워크 트래픽을 허용하세요.

워커가 도구 결과를 보내면 해당 요청의 API 스팬이 그 SDK 스팬 아래에 중첩됩니다. 워커가 Claude Platform on AWS로 보내는 요청의 경우, API 스팬은 대신 별도의 트레이스에 있습니다.

트레이스 컨텍스트와 baggage

SDK는 각 요청에서 애플리케이션의 전파기를 사용해 traceparent 같은 헤더로 트레이스 컨텍스트를 API에 보냅니다. 이 전파기가 baggage도 작성하면 SDK는 baggage도 보냅니다. baggage 없이 트레이스 컨텍스트를 보내려면 W3C 트레이스 컨텍스트 전파기만 등록하세요.

SDK가 이 헤더를 보내지 않게 하려면(예: HTTP 클라이언트 계측이 이미 이 헤더를 보내는 경우) SDK의 전파를 끄세요:

client = Anthropic(open_telemetry={"propagation": False})

SDK가 MCP 도구를 호출하는 동안에는 SDK의 도구 스팬이 현재 스팬입니다. 일부 MCP 클라이언트 라이브러리는 트레이스 컨텍스트를 _meta에 담아 MCP 서버로 보내므로, 이를 읽는 서버는 해당 도구 스팬 아래에 자신의 스팬을 트레이스에 추가할 수 있습니다. 버전 2.0 이상의 Python mcp 패키지와 C# ModelContextProtocol 패키지가 이렇게 합니다. TypeScript, Go, Java, Ruby, PHP용 MCP SDK는 자체적으로 이렇게 하지 않습니다.

문제 해결

Compatibility