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

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

API создаёт спаны для ваших запросов к Messages API и сеансов Managed Agents. Чтобы получать их, добавьте destination (назначение) в Claude Console. Назначение сообщает API конечную точку OTLP вашей платформы наблюдаемости и способ аутентификации в ней.

Что вам понадобится

• Роль администратора в организации Claude Console, чтобы добавлять и изменять назначения. С ролью разработчика вы можете их просматривать. Если ваша организация использует Claude Platform on AWS, войдите в Console через AWS Console, как описано в разделе Вход в систему.
• Конечная точка OTLP/HTTP, принимающая кодировку protobuf по URL-адресу HTTPS на порту 443. Если вы запускаете собственный OpenTelemetry Collector, его приёмник OTLP/HTTP по умолчанию прослушивает порт 4318. Настройте приёмник на приём HTTPS на порту 443 или разместите перед Collector балансировщик нагрузки или обратный прокси.
• Учетные данные для конечной точки, например ключ API.

1. Добавьте назначение

1. В Console откройте страницу настроек OpenTelemetry вашей организации и нажмите Add destination.

2. Настройте назначение:

   Поле	Что ввести
   Provider	Ваша платформа наблюдаемости или Custom, если её нет в списке. Если вы выберете платформу из списка, Console запросит её данные, например ключ API, вместо OTLP endpoint URL, Request headers и OTLP traces endpoint URL.
   Name	Необязательно. Например, «Платформа наблюдаемости компании Acme».
   OTLP endpoint URL	Базовый URL-адрес HTTPS конечной точки OTLP/HTTP вашей платформы наблюдаемости с именем хоста, а не IP-адресом. Он может содержать префикс пути, например https://gateway.example.com/otlp. Не добавляйте /v1/traces, так как API добавляет его сам. Если вы задали 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. Задайте его, если платформа принимает трассировки по URL-адресу, отличному от OTLP endpoint URL с добавлением /v1/traces. Он должен иметь тот же хост, что и OTLP endpoint URL.
   Maximum content size in MB	Необязательно, в разделе Advanced settings, если выбран режим содержимого Full content. Максимальный объем содержимого, который API отправляет в каждом спане. Console заполняет его в зависимости от значения, выбранного в поле Provider. Измените его в соответствии с тем, что принимает ваша платформа наблюдаемости. Оставьте поле пустым, чтобы отправлять максимальный объем, допустимый API. См. Ограничения содержимого.

3. Нажмите Add destination, чтобы сохранить.

4. Нажмите Test в меню More actions назначения. Появится сообщение о том, что тестовый спан доставлен в ваш коллектор, или о причине сбоя доставки (см. Ошибки доставки).

5. Убедитесь, что спан anthropic.test поступил в вашу платформу наблюдаемости.

Admin API и CLI

Вы также можете добавлять назначение через Admin API, а не через Console. Выполните вход в CLI от имени администратора или укажите ключ Admin API в ANTHROPIC_API_KEY. В 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)

Запрос на создание принимает те же настройки, что и Console, за исключением Provider, поэтому введите URL-адрес конечной точки и заголовки вашей платформы наблюдаемости самостоятельно. Задайте traces.max_content_bytes в байтах в соответствии с тем, что принимает ваша платформа наблюдаемости (см. Ограничения содержимого). Чтобы просмотреть список, изменить или удалить назначения, а также чтобы добавить или удалить одно рабочее пространство, используйте другие методы API назначений телеметрии.

2. Выберите рабочие пространства для назначения

Назначение получает спаны рабочих пространств, которые оно охватывает. Выберите их при добавлении назначения. Для Workspaces выберите один из следующих вариантов:

• All: все рабочие пространства в организации, включая Default Workspace и рабочие пространства, созданные позже.
• Selected: только выбранные вами рабочие пространства.
• All except: как All, но без выбранных вами рабочих пространств.

Для Selected или All except выберите рабочие пространства в поле поиска, которое появляется под вариантами. Чтобы позже изменить рабочие пространства назначения, откройте его меню More actions на странице настроек OpenTelemetry, когда фильтр Workspace показывает All. Нажмите Edit, затем выберите другой вариант Workspaces или измените рабочие пространства в поле поиска.

Если у вас есть роль разработчика в организации и роль Workspace Admin в рабочем пространстве, вы можете добавить это рабочее пространство в назначение Selected или удалить его оттуда. Выберите это рабочее пространство в фильтре Workspace, затем откройте меню More actions назначения. В Claude Platform on AWS в Console нет роли Workspace Admin. Там то, кто может добавить рабочее пространство в назначение или удалить его оттуда, определяет ваша политика IAM.

API отправляет спаны в каждое включённое назначение, которое охватывает рабочее пространство, в котором выполняется запрос или сеанс.

3. Убедитесь, что спаны поступают

1. В Console выберите рабочее пространство, на которое распространяется назначение, и отправьте запрос к Messages API в playground. Вы также можете отправить запрос к Messages API из вашего приложения или запустить сеанс Managed Agents в этом рабочем пространстве. Чтобы запустить сеанс, вы можете выполнить шаги из руководства Начало работы с Claude Managed Agents.
2. В Console на странице настроек OpenTelemetry убедитесь, что в столбце Delivery для назначения отображается Healthy. Это может занять около минуты.
3. В вашей платформе наблюдаемости отфильтруйте по service.name = claude-platform, чтобы найти спаны запроса.

Если в столбце отображается Failing, наведите на него указатель, чтобы увидеть последнюю ошибку. Чтобы найти вероятную причину, см. Ошибки доставки.

4. Свяжите спаны API с вашими собственными трассировками

По умолчанию спаны API для запроса к Messages API или сеанса Managed Agents находятся в собственных трассировках. Свяжите их с трассировками вашего приложения, чтобы они вкладывались в ваши собственные спаны.

API считывает контекст трассировки каждого запроса из заголовка traceparent W3C. Если флаг выборки в заголовке выключен, API не создаёт спан запроса и спаны под ним. Claude Platform on AWS пока не поддерживает этот заголовок. Спаны для запросов, которые вы туда отправляете, всегда начинают собственные трассировки, даже если флаг выборки выключен.

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 в заголовки запроса.
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, когда вы подключаете его с помощью коннектора MCP, чтобы он мог размещать собственные спаны под спанами API. Каждый запрос и уведомление, которые API отправляет вашему серверу MCP, содержат W3C traceparent в params._meta. В запросе tools/call он указывает на спан anthropic.mcp_tool_use этого использования инструмента. В остальных сообщениях он указывает на спан anthropic.messages.create. Для запроса, который API не трассирует, например запроса, у которого в заголовке traceparent выключен флаг выборки, API не отправляет traceparent.

Следующие шаги

Доставка и состояние

Следующие правила применяются к спанам, которые API отправляет в ваши назначения.

• Как минимум один раз: назначение может получить один и тот же спан более одного раза. Чтобы удалить дубликаты, используйте идентификатор трассировки и идентификатор спана.
• Без гарантий: спан может быть потерян до доставки. API не может повторно отправить потерянный спан.
• Сжатие: API сжимает первый запрос каждой доставки с помощью gzip и устанавливает заголовок Content-Encoding: gzip. Если ваша конечная точка отвечает на этот запрос ответом 400 или 415, API сразу же повторно отправляет те же спаны без сжатия.
• Повторные попытки: API повторяет доставку позже ограниченное число раз после тайм-аута, сбоя соединения, TLS или DNS либо ответа 408, 429 или 5xx. При других сбоях повторные попытки не выполняются.
• Тайм-ауты: для каждого запроса ваша конечная точка должна завершить TLS-рукопожатие в течение 5 секунд и отправить заголовки ответа в течение 5 секунд. Каждая доставка завершается по тайм-ауту через 10 секунд в общей сложности, включая повторную отправку без сжатия.
• User agent: каждый запрос содержит заголовок User-Agent: Claude-Platform.

Столбец Delivery показывает состояние каждого назначения. Состояние может отставать до одной минуты.

API отключает назначение, когда:

• Конечная точка отправляет перенаправление 3xx.
• Имя хоста конечной точки разрешается в IP-адрес, который не является публичным.
• Все доставки завершаются сбоем в течение 24 часов.

API не отправляет спаны в отключённое назначение. Чтобы возобновить экспорт, устраните причину. Затем, когда фильтр Workspace на странице настроек OpenTelemetry показывает All, нажмите Enable в меню More actions назначения. Экспорт возобновится примерно в течение минуты.

Чтобы изменить назначение, откройте его меню More actions, когда фильтр Workspace показывает All. Затем нажмите Edit, Disable, Enable или Delete. Если вы меняете хост в OTLP endpoint URL, введите значения заголовков заново. Если у назначения есть OTLP traces endpoint URL, укажите для него тот же новый хост или очистите его.

Ограничения

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

Ошибки доставки

Когда доставка завершается неудачей, в столбце Delivery отображается Failing. Наведите на него указатель, чтобы увидеть ошибку, а затем определите вероятную причину:

Compatibility