Перейти к основному содержанию
Когда вы запускаете агентов в 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. Каждый имеет свой переключатель включения и свой экспортер, поэтому вы можете включить только те, которые вам нужны.
СигналЧто он содержитВключить с помощью
MetricsСчётчики для токенов, стоимости, сессий, строк кода и решений по инструментамOTEL_METRICS_EXPORTER
Log eventsСтруктурированные записи для каждой подсказки, запроса API, ошибки API и результата инструментаOTEL_LOGS_EXPORTER
TracesSpans для каждого взаимодействия, запроса к модели, вызова инструмента и hook (бета)OTEL_TRACES_EXPORTER плюс CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
Для полного списка имён метрик, имён событий и атрибутов см. справочник Claude Code Monitoring. Agent SDK излучает те же данные, потому что запускает тот же CLI. Имена spans перечислены в разделе Чтение трассировок агента ниже.

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

Телеметрия отключена до тех пор, пока вы не установите CLAUDE_CODE_ENABLE_TELEMETRY=1 и не выберете хотя бы один экспортер. Наиболее распространённая конфигурация отправляет все три сигнала через OTLP HTTP на сборщик. Следующий пример устанавливает переменные в словарь и передаёт их через options.env. Агент выполняет одну задачу, и CLI экспортирует spans, метрики и события на сборщик по адресу collector.example.com пока цикл потребляет поток ответов: 
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

OTEL_ENV = {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    # Требуется для traces, которые находятся в бета-версии. Metrics и log events этого не требуют.
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    # Выберите экспортер для каждого сигнала. Используйте otlp для SDK; см. примечание ниже.
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    # Стандартная конфигурация транспорта OTLP.
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token",
}


async def main():
    options = ClaudeAgentOptions(env=OTEL_ENV)
    async for message in query(
        prompt="List the files in this directory", options=options
    ):
        print(message)


asyncio.run(main())
Поскольку дочерний процесс по умолчанию наследует окружение вашего приложения, вы можете достичь того же результата, экспортировав эти переменные в Dockerfile, манифесте Kubernetes или профиле оболочки и полностью опустив options.env.
Экспортер console записывает телеметрию в стандартный вывод, который SDK использует как свой канал сообщений. Не устанавливайте console как значение экспортера при запуске через SDK. Чтобы проверить телеметрию локально, направьте OTEL_EXPORTER_OTLP_ENDPOINT на локальный сборщик или контейнер all-in-one Jaeger вместо этого.

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

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

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

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, метрике и событии, которое излучает агент: 
options = ClaudeAgentOptions(
    env={
        # ... конфигурация экспортера ...
        "OTEL_SERVICE_NAME": "support-triage-agent",
        "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production",
    },
)

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

CLI прикрепляет атрибуты идентичности к каждому событию на основе учётных данных, которые он использует для вызова Anthropic. Когда вы создаёте приложение, которое обслуживает многих конечных пользователей из одного развёртывания, эти атрибуты идентифицируют учётные данные вашего сервиса, а не конечного пользователя, от имени которого действовал агент. Чтобы сделать вызовы инструментов и активность MCP атрибутируемыми конечным пользователям вашего приложения, внедрите идентичность конечного пользователя как атрибуты ресурсов при каждом вызове query(). Процентно-кодируйте значения перед интерполяцией, так как OTEL_RESOURCE_ATTRIBUTES зарезервирует запятые, пробелы и знаки равенства. Следующий пример прикрепляет запрашивающего пользователя и тенанта к каждому span и событию из одного запроса: 
from urllib.parse import quote

options = ClaudeAgentOptions(
    env={
        # ... конфигурация экспортера ...
        "OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}",
    },
)
С прикреплённой идентичностью конечного пользователя события tool_decision, tool_result, mcp_server_connection и permission_mode_changed становятся журналом аудита для каждого пользователя, который вы можете переслать на платформу Security Information and Event Management (SIEM). См. Аудит событий безопасности в справочнике Monitoring для полного списка событий, связанных с безопасностью, и атрибутов, которые несёт каждое из них.

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

Телеметрия по умолчанию структурирована. Длительности, имена моделей и имена инструментов записываются на каждом span; подсчёты токенов записываются, когда базовый запрос API возвращает данные об использовании, поэтому spans для неудачных или прерванных запросов могут их опускать. Содержимое, которое читает и записывает ваш агент, по умолчанию не записывается. Эти переменные opt-in добавляют содержимое в экспортируемые данные:
ПеременнаяДобавляет
OTEL_LOG_USER_PROMPTS=1Текст подсказки на событиях claude_code.user_prompt и на span claude_code.interaction
OTEL_LOG_TOOL_DETAILS=1Аргументы входных данных инструмента (пути файлов, команды оболочки, шаблоны поиска) на событиях claude_code.tool_result
OTEL_LOG_TOOL_CONTENT=1Полные тела входных и выходных данных инструмента как события span на claude_code.tool, усечённые на 60 КБ. Требует, чтобы трассировка была включена
OTEL_LOG_RAW_API_BODIESПолный JSON запроса и ответа Anthropic Messages API как события логов claude_code.api_request_body и claude_code.api_response_body. Установите на 1 для встроенных тел, усечённых на 60 КБ, или file:<dir> для неусечённых тел на диске с путём body_ref в событии. Тела включают всю историю разговора и имеют содержимое расширенного мышления отредактировано. Включение этого подразумевает согласие на всё, что раскроют три переменные выше
Оставьте эти переменные неустановленными, если ваш конвейер наблюдаемости не одобрен для хранения данных, которые обрабатывает ваш агент. См. Безопасность и конфиденциальность в справочнике Monitoring для полного списка атрибутов и поведения редактирования.

​
Связанная документация

Эти руководства охватывают смежные темы для мониторинга и развёртывания агентов:
  • Отслеживание стоимости и использования: читайте данные о токенах и стоимости из потока сообщений без внешнего бэкенда.
  • Размещение Agent SDK: развёртывайте агентов в контейнерах, где вы можете установить переменные OpenTelemetry на уровне окружения.
  • Monitoring: полный справочник для каждой переменной окружения, метрики и события, которые излучает CLI.