> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Наблюдаемость с OpenTelemetry > Экспортируйте трассировки, метрики и события из Agent SDK в ваш бэкенд наблюдаемости с помощью OpenTelemetry. Когда вы запускаете агентов в production, вам нужна видимость того, что они делали: * какие инструменты они вызывали * сколько времени заняла каждый запрос к модели * сколько токенов было потрачено * где произошли сбои Agent SDK может экспортировать эти данные как трассировки OpenTelemetry, метрики и события логов в любой бэкенд, который принимает OpenTelemetry Protocol (OTLP), такой как Honeycomb, Datadog, Grafana, Langfuse или самостоятельно размещённый сборщик. Это руководство объясняет, как SDK излучает телеметрию, как настроить экспорт и как помечать и фильтровать данные после их поступления на ваш бэкенд. Чтобы прочитать использование токенов и стоимость непосредственно из потока ответов SDK вместо экспорта на бэкенд, см. [Отслеживание стоимости и использования](/ru/agent-sdk/cost-tracking).

Как телеметрия поступает из 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` | | Traces | Spans для каждого взаимодействия, запроса к модели, вызова инструмента и hook (бета) | `OTEL_TRACES_EXPORTER` плюс `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` | Для полного списка имён метрик, имён событий и атрибутов см. справочник Claude Code [Monitoring](/ru/monitoring-usage). Agent SDK излучает те же данные, потому что запускает тот же CLI. Имена spans перечислены в разделе [Чтение трассировок агента](#read-agent-traces) ниже.

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

Телеметрия отключена до тех пор, пока вы не установите `CLAUDE_CODE_ENABLE_TELEMETRY=1` и не выберете хотя бы один экспортер. Наиболее распространённая конфигурация отправляет все три сигнала через OTLP HTTP на сборщик. Следующий пример устанавливает переменные в словарь и передаёт их через `options.env`. Агент выполняет одну задачу, и CLI экспортирует spans, метрики и события на сборщик по адресу `collector.example.com` пока цикл потребляет поток ответов: ```python Python theme={null} 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()) ``` ```typescript TypeScript theme={null} import { query } from "@anthropic-ai/claude-agent-sdk"; const otelEnv = { 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", }; for await (const message of query({ prompt: "List the files in this directory", // env заменяет унаследованное окружение в TypeScript, поэтому сначала распределите // process.env, чтобы сохранить PATH, ANTHROPIC_API_KEY и другие переменные. options: { env: { ...process.env, ...otelEnv } }, })) { console.log(message); } ``` Поскольку дочерний процесс по умолчанию наследует окружение вашего приложения, вы можете достичь того же результата, экспортировав эти переменные в Dockerfile, манифесте Kubernetes или профиле оболочки и полностью опустив `options.env`. Экспортер `console` записывает телеметрию в стандартный вывод, который SDK использует как свой канал сообщений. Не устанавливайте `console` как значение экспортера при запуске через SDK. Чтобы проверить телеметрию локально, направьте `OTEL_EXPORTER_OTLP_ENDPOINT` на локальный сборщик или контейнер all-in-one Jaeger вместо этого.

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

CLI группирует телеметрию и экспортирует по интервалу. При чистом выходе процесса он пытается сбросить ожидающие данные, но сброс ограничен коротким таймаутом, поэтому spans всё ещё могут быть потеряны, если сборщик медленно реагирует. Если ваш процесс убит до того, как CLI завершит работу, всё, что остаётся в буфере пакета, теряется. Снижение интервалов экспорта сокращает оба окна. По умолчанию метрики экспортируются каждые 60 секунд, а traces и logs экспортируются каждые 5 секунд. Следующий пример сокращает все три интервала, чтобы данные достигли сборщика пока короткая задача всё ещё выполняется: ```python Python theme={null} OTEL_ENV = { # ... конфигурация экспортера из предыдущего примера ... "OTEL_METRIC_EXPORT_INTERVAL": "1000", "OTEL_LOGS_EXPORT_INTERVAL": "1000", "OTEL_TRACES_EXPORT_INTERVAL": "1000", } ``` ```typescript TypeScript theme={null} const otelEnv = { // ... конфигурация экспортера из предыдущего примера ... 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](/ru/agent-sdk/hooks). Требует детальную бета-трассировку (`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()` для одной и той же [сессии](/ru/agent-sdk/sessions), фильтруйте по `session.id` в вашем бэкенде, чтобы увидеть их как одну временную шкалу. Атрибут опускается, если `OTEL_METRICS_INCLUDE_SESSION_ID` установлен на ложное значение. Трассировка находится в бета-версии. Имена spans и атрибуты могут измениться между выпусками. См. [Traces (beta)](/ru/monitoring-usage#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)](/ru/monitoring-usage#traces-beta) в справочнике Monitoring для полного справочника span и атрибутов.

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

По умолчанию CLI сообщает `service.name` как `claude-code`. Если вы запускаете несколько агентов или запускаете SDK наряду с другими сервисами, которые экспортируют на один и тот же сборщик, переопределите имя сервиса и добавьте атрибуты ресурсов, чтобы вы могли фильтровать по агенту в вашем бэкенде. Следующий пример переименовывает сервис и прикрепляет метаданные развёртывания. Эти значения применяются как атрибуты ресурсов OpenTelemetry на каждом span, метрике и событии, которое излучает агент: ```python Python theme={null} options = ClaudeAgentOptions( env={ # ... конфигурация экспортера ... "OTEL_SERVICE_NAME": "support-triage-agent", "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production", }, ) ``` ```typescript TypeScript theme={null} const options = { env: { ...process.env, // ... конфигурация экспортера ... OTEL_SERVICE_NAME: "support-triage-agent", OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production", }, }; ```

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

CLI прикрепляет [атрибуты идентичности](/ru/monitoring-usage#standard-attributes) к каждому событию на основе учётных данных, которые он использует для вызова Anthropic. Когда вы создаёте приложение, которое обслуживает многих конечных пользователей из одного развёртывания, эти атрибуты идентифицируют учётные данные вашего сервиса, а не конечного пользователя, от имени которого действовал агент. Чтобы сделать вызовы инструментов и активность MCP атрибутируемыми конечным пользователям вашего приложения, внедрите идентичность конечного пользователя как атрибуты ресурсов при каждом вызове `query()`. Процентно-кодируйте значения перед интерполяцией, так как `OTEL_RESOURCE_ATTRIBUTES` [зарезервирует запятые, пробелы и знаки равенства](/ru/monitoring-usage#multi-team-organization-support). Следующий пример прикрепляет запрашивающего пользователя и тенанта к каждому span и событию из одного запроса. Он предполагает наличие объекта `request` из вашего веб-фреймворка, содержащего идентификаторы пользователя и тенанта: ```python Python theme={null} from urllib.parse import quote options = ClaudeAgentOptions( env={ # ... конфигурация экспортера ... "OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}", }, ) ``` ```typescript TypeScript theme={null} const options = { env: { ...process.env, // ... конфигурация экспортера ... OTEL_RESOURCE_ATTRIBUTES: `enduser.id=${encodeURIComponent(request.userId)},tenant.id=${encodeURIComponent(request.tenantId)}`, }, }; ``` С прикреплённой идентичностью конечного пользователя события `tool_decision`, `tool_result`, `mcp_server_connection` и `permission_mode_changed`, которые экспортируются как записи журнала с префиксом `claude_code.`, становятся журналом аудита для каждого пользователя, который вы можете переслать на платформу Security Information and Event Management (SIEM). См. [Аудит событий безопасности](/ru/monitoring-usage#audit-security-events) в справочнике 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 КБ. Требует, чтобы [трассировка](#read-agent-traces) была включена | | `OTEL_LOG_RAW_API_BODIES` | Полный JSON запроса и ответа Anthropic Messages API как события логов `claude_code.api_request_body` и `claude_code.api_response_body`. Установите на `1` для встроенных тел, усечённых на 60 КБ, или `file:` для неусечённых тел на диске с путём `body_ref` в событии. Тела включают всю историю разговора и имеют содержимое расширенного мышления отредактировано. Включение этого подразумевает согласие на всё, что раскроют три переменные выше | Оставьте эти переменные неустановленными, если ваш конвейер наблюдаемости не одобрен для хранения данных, которые обрабатывает ваш агент. См. [Безопасность и конфиденциальность](/ru/monitoring-usage#security-and-privacy) в справочнике Monitoring для полного списка атрибутов и поведения редактирования. Эти руководства охватывают смежные темы для мониторинга и развёртывания агентов: * [Отслеживание стоимости и использования](/ru/agent-sdk/cost-tracking): читайте данные о токенах и стоимости из потока сообщений без внешнего бэкенда. * [Размещение Agent SDK](/ru/agent-sdk/hosting): развёртывайте агентов в контейнерах, где вы можете установить переменные OpenTelemetry на уровне окружения. * [Monitoring](/ru/monitoring-usage): полный справочник для каждой переменной окружения, метрики и события, которые излучает CLI.