Перейти к основному содержанию
Когда вы запускаете агентов в production, вам нужна видимость того, что они делали:
  • какие инструменты они вызывали
  • сколько времени заняла каждый запрос к модели
  • сколько токенов было потрачено
  • где произошли сбои
Agent SDK может экспортировать эти данные как трассировки OpenTelemetry, метрики и события логов в любой бэкенд, который принимает OpenTelemetry Protocol (OTLP), такой как Honeycomb, Datadog, Grafana, Langfuse или самостоятельно размещённый сборщик. Это руководство объясняет, как SDK излучает телеметрию, как настроить экспорт и как помечать и фильтровать данные после их поступления на ваш бэкенд. Чтобы прочитать использование токенов и стоимость непосредственно из потока ответов SDK вместо экспорта на бэкенд, см. Отслеживание стоимости и использования.

Как телеметрия поступает из SDK

Agent SDK запускает Claude Code CLI как дочерний процесс и взаимодействует с ним через локальный канал. CLI имеет встроенную инструментацию OpenTelemetry: он записывает spans вокруг каждого запроса к модели и выполнения инструмента, излучает метрики для счётчиков токенов и стоимости и излучает структурированные события логов для подсказок и результатов инструментов. SDK не производит телеметрию самостоятельно. Вместо этого он передаёт конфигурацию в процесс CLI, и CLI экспортирует непосредственно в ваш сборщик. Конфигурация передаётся как переменные окружения. По умолчанию дочерний процесс наследует окружение вашего приложения, поэтому вы можете настроить телеметрию в одном из двух мест:
  • Окружение процесса: установите переменные в вашей оболочке, контейнере или оркестраторе перед запуском вашего приложения. Каждый вызов query() автоматически их подхватывает без изменения кода. Это рекомендуемый подход для production развёртываний.
  • Параметры для каждого вызова: установите переменные в ClaudeAgentOptions.env (Python) или options.env (TypeScript). Используйте это, когда разные агенты в одном процессе нуждаются в разных параметрах телеметрии. В Python env объединяется поверх унаследованного окружения. В TypeScript env полностью заменяет унаследованное окружение, поэтому включите ...process.env в объект, который вы передаёте.
CLI экспортирует три независимых сигнала OpenTelemetry. Каждый имеет свой переключатель включения и свой экспортер, поэтому вы можете включить только те, которые вам нужны. Для полного списка имён метрик, имён событий и атрибутов см. справочник Claude Code Monitoring. Agent SDK излучает те же данные, потому что запускает тот же CLI. Имена spans перечислены в разделе Чтение трассировок агента ниже.

Включение экспорта телеметрии

Телеметрия отключена до тех пор, пока вы не установите CLAUDE_CODE_ENABLE_TELEMETRY=1 и не выберете хотя бы один экспортер. Наиболее распространённая конфигурация отправляет все три сигнала через OTLP HTTP на сборщик. Следующий пример устанавливает переменные в словарь и передаёт их через options.env. Агент выполняет одну задачу, и CLI экспортирует spans, метрики и события на сборщик по адресу collector.example.com пока цикл потребляет поток ответов:
Поскольку дочерний процесс по умолчанию наследует окружение вашего приложения, вы можете достичь того же результата, экспортировав эти переменные в Dockerfile, манифесте Kubernetes или профиле оболочки и полностью опустив options.env.
Экспортер console записывает телеметрию в стандартный вывод, который SDK использует как свой канал сообщений. Не устанавливайте console как значение экспортера при запуске через SDK. Чтобы проверить телеметрию локально, направьте OTEL_EXPORTER_OTLP_ENDPOINT на локальный сборщик или контейнер all-in-one Jaeger вместо этого.

Сброс телеметрии из короткоживущих вызовов

CLI группирует телеметрию и экспортирует по интервалу. При чистом выходе процесса он пытается сбросить ожидающие данные, но сброс ограничен коротким таймаутом, поэтому spans всё ещё могут быть потеряны, если сборщик медленно реагирует. Если ваш процесс убит до того, как CLI завершит работу, всё, что остаётся в буфере пакета, теряется. Снижение интервалов экспорта сокращает оба окна. По умолчанию метрики экспортируются каждые 60 секунд, а traces и logs экспортируются каждые 5 секунд. Следующий пример сокращает все три интервала, чтобы данные достигли сборщика пока короткая задача всё ещё выполняется:

Чтение трассировок агента

Traces дают вам наиболее детальный вид запуска агента. С установленным CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, каждый шаг цикла агента становится span, который вы можете проверить в вашем бэкенде трассировки:
  • claude_code.interaction: оборачивает один оборот цикла агента, от получения подсказки до создания ответа.
  • claude_code.llm_request: оборачивает каждый вызов API Claude с именем модели, задержкой и подсчётом токенов как атрибутами.
  • claude_code.tool: оборачивает каждый вызов инструмента с дочерними spans для ожидания разрешения (claude_code.tool.blocked_on_user) и самого выполнения (claude_code.tool.execution).
  • claude_code.hook: оборачивает каждое выполнение hook. Требует детальную бета-трассировку (ENABLE_BETA_TRACING_DETAILED=1 и BETA_TRACING_ENDPOINT) в дополнение к переменным выше.
Spans llm_request, tool и hook являются дочерними элементами охватывающего span claude_code.interaction. Когда агент порождает подагента через инструмент Task, spans llm_request и tool подагента вложены под span claude_code.tool родительского агента, поэтому полная цепочка делегирования появляется как одна трассировка. Spans по умолчанию несут атрибут session.id. Когда вы делаете несколько вызовов query() для одной и той же сессии, фильтруйте по session.id в вашем бэкенде, чтобы увидеть их как одну временную шкалу. Атрибут опускается, если OTEL_METRICS_INCLUDE_SESSION_ID установлен на ложное значение.
Трассировка находится в бета-версии. Имена spans и атрибуты могут измениться между выпусками. См. Traces (beta) в справочнике Monitoring для переменных конфигурации экспортера трассировки.
SDK автоматически распространяет контекст трассировки W3C в подпроцесс CLI. Когда вы вызываете query() пока в вашем приложении активен span OpenTelemetry, SDK внедряет TRACEPARENT и TRACESTATE в окружение дочернего процесса, и CLI читает их, так что его span claude_code.interaction становится дочерним элементом вашего span. Запуск агента затем появляется внутри трассировки вашего приложения вместо отключённого корня. Когда распространение контекста трассировки включено, CLI также пересылает TRACEPARENT каждой команде Bash и PowerShell, которую он запускает. Если команда, запущенная через инструмент Bash, излучает свои собственные spans OpenTelemetry, эти spans вложены под span claude_code.tool.execution, который оборачивает команду. Автоматическое внедрение пропускается, когда вы явно устанавливаете TRACEPARENT в options.env, поэтому вы можете закрепить определённый контекст родителя, если необходимо. Интерактивные сессии CLI полностью игнорируют входящий TRACEPARENT; только запуски Agent SDK и claude -p его соблюдают. См. Traces (beta) в справочнике Monitoring для полного справочника span и атрибутов.

Пометка телеметрии от вашего агента

По умолчанию CLI сообщает service.name как claude-code. Если вы запускаете несколько агентов или запускаете SDK наряду с другими сервисами, которые экспортируют на один и тот же сборщик, переопределите имя сервиса и добавьте атрибуты ресурсов, чтобы вы могли фильтровать по агенту в вашем бэкенде. Следующий пример переименовывает сервис и прикрепляет метаданные развёртывания. Эти значения применяются как атрибуты ресурсов OpenTelemetry на каждом span, метрике и событии, которое излучает агент:

Атрибуция действий вашим конечным пользователям

CLI прикрепляет атрибуты идентичности к каждому событию на основе учётных данных, которые он использует для вызова Anthropic. Когда вы создаёте приложение, которое обслуживает многих конечных пользователей из одного развёртывания, эти атрибуты идентифицируют учётные данные вашего сервиса, а не конечного пользователя, от имени которого действовал агент. Чтобы сделать вызовы инструментов и активность MCP атрибутируемыми конечным пользователям вашего приложения, внедрите идентичность конечного пользователя как атрибуты ресурсов при каждом вызове query(). Процентно-кодируйте значения перед интерполяцией, так как OTEL_RESOURCE_ATTRIBUTES зарезервирует запятые, пробелы и знаки равенства. Следующий пример прикрепляет запрашивающего пользователя и тенанта к каждому span и событию из одного запроса. Он предполагает наличие объекта request из вашего веб-фреймворка, содержащего идентификаторы пользователя и тенанта:
С прикреплённой идентичностью конечного пользователя события tool_decision, tool_result, mcp_server_connection и permission_mode_changed, которые экспортируются как записи журнала с префиксом claude_code., становятся журналом аудита для каждого пользователя, который вы можете переслать на платформу Security Information and Event Management (SIEM). См. Аудит событий безопасности в справочнике Monitoring для полного списка событий, связанных с безопасностью, и атрибутов, которые несёт каждое из них.

Контроль конфиденциальных данных в экспортах

Телеметрия по умолчанию структурирована. Длительности, имена моделей и имена инструментов записываются на каждом span; подсчёты токенов записываются, когда базовый запрос API возвращает данные об использовании, поэтому spans для неудачных или прерванных запросов могут их опускать. Содержимое, которое читает и записывает ваш агент, по умолчанию не записывается. Эти переменные opt-in добавляют содержимое в экспортируемые данные: Оставьте эти переменные неустановленными, если ваш конвейер наблюдаемости не одобрен для хранения данных, которые обрабатывает ваш агент. См. Безопасность и конфиденциальность в справочнике Monitoring для полного списка атрибутов и поведения редактирования. Эти руководства охватывают смежные темы для мониторинга и развёртывания агентов:
  • Отслеживание стоимости и использования: читайте данные о токенах и стоимости из потока сообщений без внешнего бэкенда.
  • Размещение Agent SDK: развёртывайте агентов в контейнерах, где вы можете установить переменные OpenTelemetry на уровне окружения.
  • Monitoring: полный справочник для каждой переменной окружения, метрики и события, которые излучает CLI.