Использование OpenTelemetry с Claude SDK

С помощью OpenTelemetry Claude SDK может создавать Span (спан) для каждого отправляемого им запроса и для каждого использования инструментов, которое выполняет tool runner. Вы можете просматривать эти спаны в своей платформе наблюдаемости, вложенными в ваши собственные трассировки.

SDK создаёт спаны в вашем приложении. Экспортер OpenTelemetry вашего приложения отправляет их в вашу платформу наблюдаемости.

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

# Регистрируем tracer provider (поставщик трассировщиков), выводящий каждый span в консоль.
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"}}
)

# Отключить spans (спаны) для одного клиента.
quiet_client = Anthropic(open_telemetry=False)

# Задать ID беседы через with_options(), который возвращает копию клиента.
# 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 инструменты выполняет ваша песочница, поэтому спаны инструментов создаёт SDK, а не API. Рабочий процесс окружения (environment worker) в Python, TypeScript и Go SDK создаёт спан для каждого инструмента, который он выполняет, и для каждого запроса, который он отправляет. Он группирует их под одним спаном anthropic.environment.work для каждого рабочего элемента.

Чтобы получить эти спаны:

1. В процессе, который запускает рабочий процесс, настройте трассировку SDK, как описано в шагах 1–4.
2. Разрешите сетевой трафик из песочницы в вашу платформу наблюдаемости или OpenTelemetry Collector.

Когда рабочий процесс отправляет результат инструмента, спан API этого запроса вложен в его спан SDK. Для запросов, которые рабочий процесс отправляет в Claude Platform on AWS, спаны API вместо этого находятся в собственных трассировках.

Контекст трассировки и baggage

С каждым запросом SDK с помощью распространителя вашего приложения отправляет в API контекст трассировки в таких заголовках, как traceparent. Если этот распространитель также записывает baggage, SDK отправляет и ваш baggage. Чтобы отправлять контекст трассировки без baggage, зарегистрируйте только распространитель контекста трассировки W3C.

Чтобы SDK не отправлял эти заголовки, например когда инструментирование вашего HTTP-клиента уже отправляет их, отключите распространение в SDK:

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

Пока SDK вызывает инструмент MCP, текущим спаном является спан инструмента SDK. Некоторые клиентские библиотеки MCP отправляют контекст трассировки на сервер MCP в _meta, поэтому сервер, который его читает, может добавить свои спаны в вашу трассировку под этим спаном инструмента. Так делают пакет Python mcp начиная с версии 2.0 и пакет C# ModelContextProtocol. SDK MCP для TypeScript, Go, Java, Ruby и PHP сами этого не делают.

Устранение неполадок

Compatibility