Трассировка Claude OpenTelemetry: объяснение настройки API и SDK

Anthropic представила экспорт трассировок OpenTelemetry для Claude Managed Agents, Messages API и SDK Claude. Функция, анонсированная 14 октября 2026 года, находится в публичной бета-версии и отправляет стандартные данные трассировки на платформы наблюдаемости, поддерживающие OTLP.

Цель практическая: отслеживать вызовы моделей и активность инструментов агента вместе с приложением, которое его вызвало. Вместо исследования задержек, сбоев и использования токенов в разных местах команда может изучать релевантные спаны в своей существующей системе наблюдаемости.

Два пути настройки и одна модель трассировки

Трассировка фиксирует путь запроса через систему. Спан фиксирует одну операцию внутри этого пути, например вызов модели или выполнение инструмента. Спаны Claude следуют семантическим соглашениям OpenTelemetry GenAI, что помогает совместимым инструментам интерпретировать данные у разных поставщиков моделей.

Источник: Anthropic. Схема иллюстрирует структуру трассировок и рабочие процессы анализа, а не измеренные показатели производительности.

Существуют два взаимодополняющих способа собирать эти данные:

Оба пути фиксируют спаны запросов и использование токенов. Вместе они обеспечивают видимость как клиентской работы, так и работы внутри Claude API. Отправка данных обоими путями в один и тот же бэкенд также позволяет бэкенду отображать их взаимосвязь.

Настройте трассировку API в Console

Трассировка API не требует изменения обычного кода запросов лишь для получения отдельных трассировок API. Администратор добавляет назначение, определяющее, куда Claude должна их отправлять.

1. Откройте настройки OpenTelemetry организации в Claude Console и выберите Add destination.
2. Выберите поставщика из списка или укажите пользовательскую конечную точку OTLP/HTTP и заголовки аутентификации.
3. Выберите рабочие пространства, охватываемые назначением, и режим содержимого.
4. Сохраните назначение, запустите Test и подтвердите получение спана anthropic.test.
5. Отправьте запрос из охваченного рабочего пространства и проверьте состояние назначения и полученную трассировку; спаны API используют service.name = claude-platform.

Для пользовательского назначения документированное требование — конечная точка OTLP/HTTP, принимающая protobuf, на публичном HTTPS-имени хоста через порт 443. Collector, который прослушивает только обычный порт 4318, требует подходящей HTTPS-публикации или обратного прокси. Учетные данные должны передаваться в значениях заголовков.

Базовая конечная точка обычно не включает /v1/traces, поскольку Claude добавляет этот путь самостоятельно. Расширенная конечная точка трассировок может переопределить путь, но должна использовать тот же хост. Конечные точки с частными адресами и перенаправления не поддерживаются в качестве обычных назначений доставки.

Настройте трассировку SDK в приложении

Трассировка SDK начинается с установки актуального поддерживаемого SDK Claude и регистрации поставщика трассировщика OpenTelemetry до первого вызова, который нужно отслеживать. Приложение предоставляет экспортёр, доставляющий спаны в бэкенд наблюдаемости. Поэтому «автоматический экспорт SDK» не означает, что новое приложение отправляет данные куда-либо без поставщика трассировщика и экспортёра назначения.

Консольный экспортёр может помочь проверить локальную инструментацию до подключения удаленной платформы. После настройки SDK создаёт спаны запросов и спаны инструментов, запускаемых через его средство запуска инструментов. Вызовы, выполняемые внутри спана приложения, могут быть вложены в этот спан.

Во время бета-периода параметры SDK, имена спанов и атрибуты могут меняться. Anthropic рекомендует фиксировать версию SDK, чтобы команды могли сами решать, когда принимать эти изменения.

Разберитесь в объединении трассировок и сессиях агентов

SDK передаёт контекст трассировки, поэтому серверные спаны API могут располагаться под клиентскими спанами SDK. Запросы к Claude Platform on AWS являются исключением: спаны API отображаются в отдельных трассировках, поскольку эта платформа пока не поддерживает такое же поведение объединения контекста трассировки.

Сессии Managed Agents раскрывают спаны запросов Sessions API, спаны ходов агентов, запросы к моделям, инструменты, выполняемые API, и оценки результатов. Одна сессия может охватывать несколько трассировок и, при многоагентной работе, несколько потоков. Документация рекомендует группировать по anthropic.session.id для сессии или по gen_ai.conversation.id для потока.

Claude Code, Agent SDK и Cowork имеют собственную документацию по мониторингу. Новую функцию платформы не следует считать заменой существующих инструкций по инструментации для каждого продукта.

Режимы содержимого, ограничения и обработка данных

Каждое назначение Console и клиент SDK имеют режим содержимого. Режим по умолчанию, Metadata only, включает идентификаторы, время, статус, количество токенов и отдельный описательный текст, например названия инструментов, их описания и имена серверов MCP. Он исключает промпты и ответы модели, но не гарантирует, что каждое экспортируемое поле не содержит текста, предоставленного приложением.

Full content также включает промпты и ответы. Это делает его полезным для отладки неудачных взаимодействий и построения оценок на основе реального трафика, но переносит содержимое диалогов в отдельную систему с собственными настройками доступа и хранения.

Размер содержимого и усечение

Ограничение содержимого по умолчанию составляет 0,75 МБ на спан. По словам Anthropic, этого достаточно примерно для англоязычного контекста на 200 000 токенов и значение остаётся ниже ограничения запроса в 1 МБ, используемого многими сервисами наблюдаемости и прокси. Полный контекст на один миллион токенов может требовать около 4 МБ, поэтому стандартного ограничения недостаточно для полного сохранения каждого крупного промпта.

Когда спан превышает ограничение содержимого, SDK или API сокращает его и устанавливает anthropic.content.truncated в true. В спанах запросов сначала отбрасываются системный промпт и самые ранние сообщения; в спанах инструментов отбрасываются блоки из конца результата работы инструмента. Изображения и документы отображаются по типу, а не как полные медиаданные.

SDK использует traces.max_content_bytes для управления ограничением. Назначения Console предоставляют максимальный размер содержимого в расширенных настройках, а поставщики из списка могут иметь собственное значение по умолчанию.

Ограниченные данные и Zero Data Retention

Организации с ограничениями Anthropic на обработку данных HIPAA, FERPA или K–12 экспортируют через назначения API только метаданные независимо от выбранного режима содержимого. В документации указано, что это ограничение не применяется к спанам SDK, поэтому конфигурация SDK всё равно требует отдельной проверки.

Экспорт полного содержимого можно использовать с подходящими запросами Messages API с нулевым хранением данных, поскольку API удерживает экспортируемое содержимое в памяти до доставки. Managed Agents не подходит для нулевого хранения данных, а включение OpenTelemetry не изменяет условия хранения.

Избегайте двойного подсчёта токенов

Один запрос может размещать сведения об использовании токенов в нескольких спанах. Поэтому суммирование всех спанов в трассировке может завысить использование.

Когда для запроса Messages API существуют и спаны SDK, и API, используйте источник API. Внутри этого источника суммируйте спаны запросов или их спаны запросов к модели, но не оба вида; учитывайте компактацию согласно специальным правилам документации. Для Managed Agents релевантными спанами API являются запросы к моделям и оценки результатов.

Повторные попытки доставки также могут создавать дублирующиеся спаны. Выполняйте дедупликацию по идентификатору трассировки и идентификатору спана, если бэкенд не делает этого самостоятельно.

Экспортируемые трассировки — это запись для отладки, а не гарантированно полный журнал для расчётов. Доставка выполняется по принципу максимальных усилий, а выборка может исключать запросы. Anthropic направляет команды, которым нужен полный учёт использования API-ключей, к Usage API.

Интеграции наблюдаемости и примеры клиентов

Anthropic называет Grafana Cloud, Honeycomb, Sentry и Splunk для просмотра трассировок агентов вместе с журналами и метриками приложений. Также перечислены Arize AI, Braintrust, Datadog, Langfuse, LangSmith, New Relic и PostHog для рабочих процессов, связывающих трассировки с оценками и улучшением качества. Databricks Unity Gateway выделен как средство обеспечения видимости на уровне организации.

Это примеры, а не закрытый список совместимых решений. Другие инструменты могут получать данные, если принимают требуемый стандартный экспорт OTLP.

В анонсе приведены заявления клиентов Foxglove, Ramp, Sterling Labs и FloQast. Их сценарии использования включают отладку робототехники, анализ рыночных агентов и трассировку процессов бухгалтерского учёта.

Ramp описывает внутреннюю систему Reflect, которая оценивает трассировки Langfuse и предлагает исправления. По словам инженера компании, для некоторых агентов она обеспечила снижение использования токенов на 10–20% и ускорение сессий на 30%. Это результаты, о которых сообщил клиент в рамках данного процесса улучшений; они не означают, что одно лишь включение экспорта трассировок даст такие результаты.

FAQ

Что такое экспорт трассировок Claude OpenTelemetry?

Он отправляет стандартные спаны, описывающие запросы Claude API, ходы агентов, вызовы моделей и активность поддерживаемых инструментов, в бэкенд наблюдаемости. Функция находится в публичной бета-версии и поддерживает отдельные пути трассировки API и SDK.

Нужна ли роль администратора для включения трассировки?

Роль администратора нужна для добавления или изменения назначений трассировки API в Claude Console. Трассировка SDK настраивается в коде приложения и не требует специальных разрешений организации Claude.

Экспортируются ли промпты и ответы по умолчанию?

Нет, режим по умолчанию — Metadata only. Режим Full content добавляет промпты и ответы с учётом ограничений содержимого и документированных ограничений для отдельных организаций.

Можно ли использовать самостоятельно размещаемый OpenTelemetry Collector?

Да, если назначение API соответствует документированным требованиям к сети и протоколу. В частности, экспорт API требует приёмник protobuf OTLP/HTTP, доступный через публичное HTTPS-имя хоста на порту 443, а не только частный слушатель Collector.

Могут ли спаны SDK и API появиться в одной трассировке?

Да, если контекст трассировки передаётся и спаны поступают в один и тот же бэкенд наблюдаемости. Спаны API для запросов к Claude Platform on AWS в настоящее время вместо этого появляются в отдельных трассировках.

Могут ли трассировки заменить Usage API для расчёта общих показателей биллинга?

Нет, трассировки могут быть выбраны выборкой, потеряны или доставлены более одного раза. Используйте документированные правила подсчёта для анализа и Usage API, когда требуется полный учёт использования.

Связанные инструменты

• Claude SDK Tracing: Клиентская инструментация для спанов запросов и средства запуска инструментов.
• Claude API Tracing: Управляемый через Console экспорт спанов моделей и инструментов на стороне API.
• OpenTelemetry: Нейтральная к поставщикам среда трассировки и экосистема экспорта, используемые этой интеграцией.

Связанные ссылки

• Оригинальный отчет Unite.AI: Новостной материал от 14 октября, послуживший основой для этой статьи.
• Анонс Anthropic: Официальная информация о доступности функции, интеграциях и заявлениях клиентов.
• Обзор OpenTelemetry: Охват, ограничения содержимого, подсчёт токенов и правила обработки данных.
• Настройка трассировки API: Конфигурация назначений, требования к конечным точкам и устранение проблем с доставкой.
• Настройка трассировки SDK: Поставщики трассировщиков, экспортёры, конфигурация и обработка потоков.
• Семантические соглашения GenAI: Общие соглашения проекта OpenTelemetry для телеметрии генеративного ИИ.

Итоги

Бета-версия OpenTelemetry от Claude связывает вызовы моделей и инструменты агентов с системами трассировки, которые команды уже используют. Трассировка API раскрывает серверную активность, а трассировка SDK добавляет клиентские операции и инструменты; их объединение даёт наиболее ясную временную шкалу приложения там, где поддерживается объединение трассировок.

Осознанно выбирайте режимы содержимого, проверяйте усечение и состояние доставки, а токены считайте по одному подходящему источнику. Трассировка улучшает видимость, но полный учёт использования и контроль хранения остаются отдельными обязанностями.