Настройка OpenTelemetry с Claude SDK

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

SDK создаёт спаны в вашем приложении. «Exporter» (экспортер) 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» (рабочий процесс среды) в SDK для Python, TypeScript и Go создаёт спан для каждого запускаемого инструмента и каждого отправляемого запроса. Он группирует их под одним спаном anthropic.environment.work для каждого рабочего элемента.

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

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

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

Контекст трассировки и 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