> ## 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 для Claude Code.
Отслеживайте использование Claude Code, затраты и активность инструментов в вашей организации, экспортируя данные телеметрии через OpenTelemetry (OTel). Claude Code экспортирует метрики как данные временных рядов через стандартный протокол метрик, события через протокол логов/событий и опционально распределенные трассировки через [протокол трассировки](#traces-beta). Настройте ваши бэкенды метрик, логов и трассировок в соответствии с требованиями мониторинга.
Быстрый старт
Настройте OpenTelemetry с помощью переменных окружения:
```bash theme={null}
# 1. Включить телеметрию
export CLAUDE_CODE_ENABLE_TELEMETRY=1
# 2. Выбрать экспортеры (оба опциональны - настройте только необходимое)
export OTEL_METRICS_EXPORTER=otlp # Опции: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp # Опции: otlp, console, none
# 3. Настроить OTLP endpoint (для OTLP экспортера)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# 4. Установить аутентификацию (если требуется)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"
# 5. Для отладки: сократить интервалы экспорта
export OTEL_METRIC_EXPORT_INTERVAL=10000 # 10 секунд (по умолчанию: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000 # 5 секунд (по умолчанию: 5000ms)
# 6. Запустить Claude Code
claude
```
Интервалы экспорта по умолчанию составляют 60 секунд для метрик и 5 секунд для логов. Во время настройки вы можете использовать более короткие интервалы для целей отладки. Не забудьте сбросить эти значения для использования в production.
Для полного списка параметров конфигурации см. [спецификацию OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options).
Конфигурация администратора
Администраторы могут настраивать параметры OpenTelemetry для всех пользователей через [файл управляемых параметров](/ru/settings#settings-files). Это позволяет централизованно управлять параметрами телеметрии в организации. Дополнительную информацию о том, как применяются параметры, см. в разделе [приоритет параметров](/ru/settings#settings-precedence).
Пример конфигурации управляемых параметров:
```json theme={null}
{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp",
"OTEL_LOGS_EXPORTER": "otlp",
"OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
"OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
"OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
}
}
```
Управляемые параметры можно распространять через MDM (Mobile Device Management) или другие решения для управления устройствами. Переменные окружения, определенные в файле управляемых параметров, имеют высокий приоритет и не могут быть переопределены пользователями.
Claude Code не передает переменные окружения `OTEL_*` подпроцессам, которые он порождает, включая инструмент Bash, hooks, MCP серверы и языковые серверы. Приложение, инструментированное OpenTelemetry, которое вы запускаете через инструмент Bash, не наследует endpoint экспортера Claude Code или заголовки, поэтому установите эти переменные непосредственно в команде, если это приложение должно экспортировать свою собственную телеметрию.
Детали конфигурации
Общие переменные конфигурации
| Переменная окружения | Описание | Примеры значений |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | Включает сбор телеметрии (обязательно) | `1` |
| `OTEL_METRICS_EXPORTER` | Типы экспортера метрик, разделенные запятыми. Используйте `none` для отключения | `console`, `otlp`, `prometheus`, `none` |
| `OTEL_LOGS_EXPORTER` | Типы экспортера логов/событий, разделенные запятыми. Используйте `none` для отключения | `console`, `otlp`, `none` |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Протокол для OTLP экспортера, применяется ко всем сигналам | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint коллектора для всех сигналов | `http://localhost:4317` |
| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | Протокол для метрик, переопределяет общий параметр | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | OTLP endpoint метрик, переопределяет общий параметр | `http://localhost:4318/v1/metrics` |
| `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | Протокол для логов, переопределяет общий параметр | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP endpoint логов, переопределяет общий параметр | `http://localhost:4318/v1/logs` |
| `OTEL_EXPORTER_OTLP_HEADERS` | Заголовки аутентификации для OTLP | `Authorization=Bearer token` |
| `OTEL_METRIC_EXPORT_INTERVAL` | Интервал экспорта в миллисекундах (по умолчанию: 60000) | `5000`, `60000` |
| `OTEL_LOGS_EXPORT_INTERVAL` | Интервал экспорта логов в миллисекундах (по умолчанию: 5000) | `1000`, `10000` |
| `OTEL_LOG_USER_PROMPTS` | Включить логирование содержимого пользовательских подсказок (по умолчанию: отключено) | `1` для включения |
| `OTEL_LOG_ASSISTANT_RESPONSES` | Включить логирование текста ответа ассистента на событиях `assistant_response` (по умолчанию: отключено). Если не установлено, возвращается к значению `OTEL_LOG_USER_PROMPTS`. {/* min-version: 2.1.193 */}Требует Claude Code v2.1.193 или позже | `1` для включения, `0` для сохранения скрытым |
| `OTEL_LOG_TOOL_DETAILS` | Включить логирование параметров инструмента и аргументов входных данных в событиях инструментов и атрибутах span трассировки: команды Bash, имена MCP сервера и инструмента, имена навыков и входные данные инструмента. Также включает пользовательские, плагин и MCP имена команд на событиях `user_prompt` (по умолчанию: отключено) | `1` для включения |
| `OTEL_LOG_TOOL_CONTENT` | Включить логирование входных и выходных данных инструмента в событиях span (по умолчанию: отключено). Требует [трассировку](#traces-beta). Содержимое усекается на 60 КБ | `1` для включения |
| `OTEL_LOG_RAW_API_BODIES` | Выдавать полный JSON запроса и ответа Anthropic Messages API как события логов `api_request_body` / `api_response_body` (по умолчанию: отключено). Тела включают всю историю разговора. Включение этого подразумевает согласие со всем, что раскрыли бы `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS` и `OTEL_LOG_TOOL_CONTENT` | `1` для встроенных тел, усеченных на 60 КБ, или `file:` для неусеченных тел на диске с указателем `body_ref` в событии |
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Предпочтение временности метрик (по умолчанию: `delta`). Установите на `cumulative`, если ваш бэкенд ожидает кумулятивную временность | `delta`, `cumulative` |
| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Интервал для обновления динамических заголовков (по умолчанию: 1740000ms / 29 минут) | `900000` |
Аутентификация mTLS
Способ настройки сертификатов клиента для экспортера OTLP зависит от протокола OTLP, используемого для этого сигнала, установленного через `OTEL_EXPORTER_OTLP_PROTOCOL` или переопределение для каждого сигнала. Одна и та же конфигурация применяется к метрикам, логам и трассировкам.
| Протокол | Переменные сертификата клиента | Доверять CA коллектора с помощью |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------- |
| `http/protobuf`, `http/json` | `CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY` и опционально `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`. См. [Конфигурация сети](/ru/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |
| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` и `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, или переопределения для каждого сигнала, такие как `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` для использования другого сертификата для каждого сигнала | `OTEL_EXPORTER_OTLP_CERTIFICATE` |
Для `grpc` SDK OpenTelemetry читает стандартные переменные OTLP напрямую, поэтому существующие конфигурации, которые устанавливают переменные метрик для каждого сигнала, продолжают работать.
Управление кардинальностью метрик
Следующие переменные окружения управляют тем, какие атрибуты включены в метрики для управления кардинальностью:
| Переменная окружения | Описание | Значение по умолчанию | Пример для отключения |
| ------------------------------------------ | --------------------------------------------------------------------------------- | --------------------- | --------------------- |
| `OTEL_METRICS_INCLUDE_SESSION_ID` | Включить атрибут session.id в метрики | `true` | `false` |
| `OTEL_METRICS_INCLUDE_VERSION` | Включить атрибут app.version в метрики | `false` | `true` |
| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Включить атрибуты user.account\_uuid и user.account\_id в метрики | `true` | `false` |
| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | Включить атрибут app.entrypoint в метрики | `false` | `true` |
| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | Включить ключи из `OTEL_RESOURCE_ATTRIBUTES` как атрибуты на точках данных метрик | `true` | `false` |
Эти переменные помогают управлять кардинальностью метрик, что влияет на требования к хранилищу и производительность запросов в вашем бэкенде метрик. Более низкая кардинальность обычно означает лучшую производительность и более низкие затраты на хранилище, но менее детальные данные для анализа.
Traces (beta)
Распределенная трассировка экспортирует spans, которые связывают каждую пользовательскую подсказку с запросами API и выполнением инструментов, которые она вызывает, так что вы можете просмотреть полный запрос как одну трассировку в вашем бэкенде трассировки.
Трассировка отключена по умолчанию. Чтобы включить её, установите оба `CLAUDE_CODE_ENABLE_TELEMETRY=1` и `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, затем установите `OTEL_TRACES_EXPORTER` для выбора места отправки spans. Трассировки повторно используют [общую конфигурацию OTLP](#common-configuration-variables) для endpoint, протокола, заголовков и [mTLS](#mtls-authentication).
| Переменная окружения | Описание | Примеры значений |
| ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | Включить трассировку span (обязательно). `ENABLE_ENHANCED_TELEMETRY_BETA` также принимается | `1` |
| `OTEL_TRACES_EXPORTER` | Типы экспортера трассировок, разделенные запятыми. Используйте `none` для отключения | `console`, `otlp`, `none` |
| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | Протокол для трассировок, переопределяет `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | OTLP endpoint трассировок, переопределяет `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318/v1/traces` |
| `OTEL_TRACES_EXPORT_INTERVAL` | Интервал экспорта пакета span в миллисекундах (по умолчанию: 5000) | `1000`, `10000` |
Spans скрывают текст пользовательской подсказки, детали входных данных инструмента и содержимое инструмента по умолчанию. Установите `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1` и `OTEL_LOG_TOOL_CONTENT=1` для их включения.
Когда трассировка активна, подпроцессы Bash и PowerShell автоматически наследуют переменную окружения `TRACEPARENT`, содержащую контекст трассировки W3C активного span выполнения инструмента. Это позволяет любому подпроцессу, который читает `TRACEPARENT`, родить свои собственные spans под той же трассировкой, обеспечивая сквозную распределенную трассировку через скрипты и команды, которые запускает Claude.
Когда трассировка активна и Claude Code подключен непосредственно к API Anthropic, каждый запрос модели несет заголовок W3C `traceparent`, установленный на контекст span `claude_code.llm_request`, и заголовок `traceresponse` API записывается как ссылка span. Вместе они соединяют spans Claude Code на стороне клиента с трассировкой на стороне сервера через любого совместимого посредника. Исходящие HTTP MCP запросы несут `traceparent` таким же образом. Заголовок не отправляется поставщикам третьих сторон.
По умолчанию заголовок `traceparent` на запросах модели и HTTP MCP отправляется только когда `ANTHROPIC_BASE_URL` не установлен или указывает на API Anthropic, так как некоторые прокси отклоняют неузнанные заголовки. Переменная `TRACEPARENT` подпроцесса управляется тем же переключателем для согласованности. Если вы запускаете Claude Code через пользовательский прокси `ANTHROPIC_BASE_URL` и хотите распространять контекст трассировки, установите `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`.
В Agent SDK и неинтерактивных сеансах, запущенных с `-p`, Claude Code также читает `TRACEPARENT` и `TRACESTATE` из своего собственного окружения при запуске каждого span взаимодействия. Это позволяет процессу встраивания передать свой активный контекст трассировки W3C в подпроцесс, так что spans Claude Code появляются как дочерние элементы трассировки вызывающей стороны. Интерактивные сеансы игнорируют входящий `TRACEPARENT`, чтобы избежать случайного наследования значений окружения из CI или контейнерных сред.
Иерархия span
Каждая пользовательская подсказка запускает корневой span `claude_code.interaction`. Вызовы API, вызовы инструментов и выполнения hooks записываются как его дочерние элементы. Spans инструментов имеют два собственных дочерних span: один для времени, потраченного на ожидание решения о разрешении, и один для самого выполнения. Когда инструмент Agent или устаревший инструмент Task порождает подагента, spans API и инструментов подагента вложены под span `claude_code.tool` родителя.
```text theme={null}
claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook (требует детальную бета-трассировку)
└── claude_code.tool
├── claude_code.tool.blocked_on_user
├── claude_code.tool.execution
└── (инструмент Agent) spans claude_code.llm_request / claude_code.tool подагента
```
В сеансах Agent SDK и `claude -p`, `claude_code.interaction` сам становится дочерним элементом span вызывающей стороны, когда `TRACEPARENT` установлен в окружении.
Атрибуты span
Каждый span несет [стандартные атрибуты](#standard-attributes) плюс атрибут `span.type`, соответствующий его имени. Таблицы ниже перечисляют дополнительные атрибуты, установленные на каждом span. Spans `llm_request`, `tool.execution` и `hook` устанавливают статус OpenTelemetry `ERROR` при записи сбоя; другие spans всегда заканчиваются со статусом `UNSET`.
**`claude_code.interaction`**
| Атрибут | Описание | Управляется |
| ------------------------- | -------------------------------------------------------------- | ----------------------- |
| `user_prompt` | Текст подсказки. Значение `` если gate не установлен | `OTEL_LOG_USER_PROMPTS` |
| `user_prompt_length` | Длина подсказки в символах | |
| `interaction.sequence` | Счетчик на основе 1 взаимодействий в этом сеансе | |
| `interaction.duration_ms` | Длительность хода в реальном времени | |
**`claude_code.llm_request`**
| Атрибут | Описание | Управляется |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `model` | Идентификатор модели | |
| `gen_ai.system` | Всегда `anthropic`. Семантическое соглашение OpenTelemetry GenAI | |
| `gen_ai.request.model` | То же значение, что и `model`. Семантическое соглашение OpenTelemetry GenAI | |
| `query_source` | Подсистема, которая выдала запрос, такая как `repl_main_thread` или имя подагента | |
| `agent_id` | Идентификатор подагента или товарища, который выдал запрос. Отсутствует в основном сеансе | |
| `parent_agent_id` | Идентификатор агента, который породил этот. Отсутствует для основного сеанса и для агентов, порожденных непосредственно из него | |
| `speed` | `fast` или `normal` | |
| `llm_request.context` | `interaction`, `tool` или `standalone` в зависимости от родительского span | |
| `duration_ms` | Длительность в реальном времени, включая повторные попытки | |
| `ttft_ms` | Время до первого токена в миллисекундах | |
| `input_tokens` | Количество входных токенов из блока использования API | |
| `output_tokens` | Количество выходных токенов | |
| `cache_read_tokens` | Токены, прочитанные из кэша подсказок | |
| `cache_creation_tokens` | Токены, записанные в кэш подсказок | |
| `request_id` | ID запроса Anthropic API из заголовка ответа `request-id` | |
| `gen_ai.response.id` | То же значение, что и `request_id`. Семантическое соглашение OpenTelemetry GenAI | |
| `client_request_id` | Сгенерированный клиентом `x-client-request-id` последней попытки | |
| `attempt` | Всего попыток для этого запроса | |
| `success` | `true` или `false` | |
| `status_code` | HTTP код состояния при сбое запроса | |
| `error` | Сообщение об ошибке при сбое запроса | |
| `response.has_tool_call` | `true` когда ответ содержал блоки tool-use | |
| `stop_reason` | API ответ `stop_reason`, такой как `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `pause_turn` или `refusal` | |
| `gen_ai.response.finish_reasons` | То же значение, что и `stop_reason`, обернутое в массив строк. Семантическое соглашение OpenTelemetry GenAI | |
Каждая повторная попытка также записывается как событие span `gen_ai.request.attempt` с атрибутами `attempt` и `client_request_id`.
**`claude_code.tool`**
| Атрибут | Описание | Управляется |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `tool_name` | Имя инструмента | |
| `duration_ms` | Длительность в реальном времени, включая ожидание разрешения и выполнение | |
| `result_tokens` | Приблизительный размер токена результата инструмента | |
| `agent_id` | Идентификатор подагента или товарища, который запустил инструмент. Отсутствует в основном сеансе | |
| `parent_agent_id` | Идентификатор агента, который породил этот. Отсутствует для основного сеанса и для агентов, порожденных непосредственно из него | |
| `tool_use_id` | ID блока `tool_use` модели для этого вызова. Совпадает с `tool_use_id` на событиях [tool\_result](#tool-result-event) и [tool\_decision](#tool-decision-event) и в полезных нагрузках hook, поэтому вы можете присоединить span к этим записям | |
| `gen_ai.tool.call.id` | То же значение, что и `tool_use_id`. Семантическое соглашение OpenTelemetry GenAI | |
| `file_path` | Целевой путь файла для инструментов Read, Edit и Write | `OTEL_LOG_TOOL_DETAILS` |
| `full_command` | Строка команды для инструмента Bash | `OTEL_LOG_TOOL_DETAILS` |
| `skill_name` | Имя навыка для инструмента Skill | `OTEL_LOG_TOOL_DETAILS` |
| `subagent_type` | Тип подагента для инструмента Agent или устаревшего инструмента Task | `OTEL_LOG_TOOL_DETAILS` |
Когда `OTEL_LOG_TOOL_CONTENT=1`, этот span также записывает событие span `tool.output`, чьи атрибуты содержат входные и выходные тела инструмента, усеченные на 60 КБ на атрибут.
**`claude_code.tool.blocked_on_user`**
| Атрибут | Описание | Управляется |
| ------------- | ------------------------------------------------------------------------------------- | ----------- |
| `duration_ms` | Время, потраченное на ожидание решения о разрешении | |
| `decision` | `accept` или `reject` | |
| `source` | Источник решения, соответствующий событию [Tool decision event](#tool-decision-event) | |
**`claude_code.tool.execution`**
| Атрибут | Описание | Управляется |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `duration_ms` | Время, потраченное на запуск тела инструмента | |
| `tool_use_id` | То же значение, что и на родительском span `claude_code.tool` | |
| `gen_ai.tool.call.id` | То же значение, что и `tool_use_id`. Семантическое соглашение OpenTelemetry GenAI | |
| `success` | `true` или `false` | |
| `error` | Строка категории ошибки при сбое выполнения, такая как `Error:ENOENT` или `ShellError`. Содержит полное сообщение об ошибке вместо этого, когда gate установлен | `OTEL_LOG_TOOL_DETAILS` |
**`claude_code.hook`**
Этот span выдается только при активной детальной бета-трассировке, которая требует `ENABLE_BETA_TRACING_DETAILED=1` и `BETA_TRACING_ENDPOINT` в дополнение к конфигурации экспортера трассировки выше. В интерактивных сеансах CLI это также требует, чтобы ваша организация была в списке разрешений для функции. Сеансы Agent SDK и неинтерактивные сеансы `-p` не имеют ограничений. Он не выдается, когда установлен только `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`.
| Атрибут | Описание | Управляется |
| ------------------------ | ------------------------------------------------------------ | ----------------------- |
| `hook_event` | Тип события hook, такой как `PreToolUse` | |
| `hook_name` | Полное имя hook, такой как `PreToolUse:Write` | |
| `num_hooks` | Количество выполненных команд hook, соответствующих условиям | |
| `hook_definitions` | JSON-сериализованная конфигурация hook | `OTEL_LOG_TOOL_DETAILS` |
| `duration_ms` | Длительность в реальном времени всех соответствующих hooks | |
| `num_success` | Количество hooks, которые завершились успешно | |
| `num_blocking` | Количество hooks, которые вернули решение блокировки | |
| `num_non_blocking_error` | Количество hooks, которые не удались без блокировки | |
| `num_cancelled` | Количество hooks, отмененных до завершения | |
Дополнительные атрибуты, содержащие содержимое, такие как `new_context`, `system_prompt_preview`, `user_system_prompt`, `tool_input` и `response.model_output`, выдаются только при активной детальной бета-трассировке. Они не являются частью стабильной схемы span. `user_system_prompt` дополнительно требует `OTEL_LOG_USER_PROMPTS=1`. Он содержит только текст системной подсказки, который вы предоставляете через опцию SDK `systemPrompt` или флаги `--system-prompt` и `--append-system-prompt`, усеченный на 60 КБ, и выдается один раз за сеанс, а не за запрос.
Для корпоративных сред, требующих динамической аутентификации, вы можете настроить скрипт для динамического создания заголовков. Динамические заголовки применяются только к протоколам `http/protobuf` и `http/json`. Экспортер `grpc` использует только статическое значение `OTEL_EXPORTER_OTLP_HEADERS`.
Конфигурация параметров
Добавьте в ваш `.claude/settings.json`:
```json theme={null}
{
"otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}
```
Значение может быть путем к исполняемому файлу, включая путь, содержащий пробелы, или командной строкой shell с аргументами. На Windows значение всегда запускается через shell, поэтому заключите путь, содержащий пробелы, в кавычки внутри значения JSON.
Требования к скрипту
Скрипт должен выводить корректный JSON с парами строк ключ-значение, представляющими HTTP заголовки:
```bash theme={null}
#!/bin/bash
# Пример: несколько заголовков
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"
```
Если помощник не удается или выводит содержимое, которое не соответствует этим требованиям, Claude Code сообщает об ошибке в:
* выводе `/doctor`
* журнале отладки при запуске с [`--debug`](/ru/cli-reference#cli-flags) или после запуска `/debug` в сеансе
* stderr в неинтерактивных сеансах, запущенных с `-p`
Поведение обновления
Скрипт помощника заголовков запускается при запуске и периодически после этого для поддержки обновления токена. По умолчанию скрипт запускается каждые 29 минут. Настройте интервал с помощью переменной окружения `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`.
Поддержка многокомандной организации
Организации с несколькими командами или отделами могут добавлять пользовательские атрибуты для различия между разными группами, используя переменную окружения `OTEL_RESOURCE_ATTRIBUTES`:
```bash theme={null}
# Добавить пользовательские атрибуты для идентификации команды
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
```
Эти пользовательские атрибуты будут включены во все метрики и события, позволяя вам:
* Фильтровать метрики по команде или отделу
* Отслеживать затраты по центру затрат
* Создавать панели мониторинга для конкретных команд
* Настраивать оповещения для конкретных команд
Claude Code прикрепляет эти значения как атрибуты на каждой точке данных метрик и записи событий, в дополнение к отправке их в блоке ресурсов OTLP. Поскольку большинство бэкендов метрик предоставляют атрибуты точек данных как запрашиваемые метки, вы можете группировать и фильтровать метрики по вашим пользовательским ключам напрямую. Пользовательские ключи никогда не переопределяют [стандартные атрибуты](#standard-attributes), такие как `user.id` или `session.id`: когда ключ конфликтует, Claude Code сохраняет встроенное значение.
Каждый пользовательский ключ становится меткой на каждой серии метрик, поэтому высококардинальные значения увеличивают затраты на хранилище в вашем бэкенде метрик. Чтобы отправлять пользовательские атрибуты только в блоке ресурсов и опускать их из меток точек данных, установите `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`. См. [Управление кардинальностью метрик](#metrics-cardinality-control).
Переменная окружения `OTEL_RESOURCE_ATTRIBUTES` использует пары ключ=значение, разделенные запятыми, со строгими требованиями к форматированию:
* **Пробелы не допускаются**: значения не могут содержать пробелы. Например, `user.organizationName=My Company` недопустимо
* **Формат**: должны быть пары ключ=значение, разделенные запятыми: `key1=value1,key2=value2`
* **Допустимые символы**: только символы US-ASCII, исключая управляющие символы, пробелы, двойные кавычки, запятые, точки с запятой и обратные слэши
* **Специальные символы**: символы вне допустимого диапазона должны быть закодированы в процентах
Для значения, которому нужен пробел, используйте подчеркивания или camelCase вместо этого. Следующие примеры устанавливают `org.name` с каждой формой:
```bash theme={null}
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"
```
Вы можете закодировать в процентах любой символ, не только исключенные. Этот пример кодирует как пробел, так и апостроф:
```bash theme={null}
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
```
Заключение значений в кавычки не экранирует пробелы. Например, `org.name="My Company"` приводит к буквальному значению `"My Company"` с кавычками включены, а не `My Company`.
Примеры конфигураций
Установите эти переменные окружения перед запуском `claude`. Каждый блок показывает полную конфигурацию для другого экспортера или сценария развертывания:
```bash theme={null}
# Отладка консоли (интервалы 1 секунда)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000
# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus
# Несколько экспортеров
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
# Разные endpoints/бэкенды для метрик и логов
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317
# Только метрики (без событий/логов)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# Только события/логи (без метрик)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
```
Доступные метрики и события
Стандартные атрибуты
Все метрики и события имеют эти стандартные атрибуты:
| Атрибут | Описание | Управляется |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `session.id` | Уникальный идентификатор сеанса | `OTEL_METRICS_INCLUDE_SESSION_ID` (по умолчанию: true) |
| `app.version` | Текущая версия Claude Code | `OTEL_METRICS_INCLUDE_VERSION` (по умолчанию: false) |
| `app.entrypoint` | Как был запущен сеанс, такой как `cli`, `sdk-cli`, `sdk-ts`, `sdk-py` или `claude-vscode` | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (по умолчанию: false) |
| `organization.id` | UUID организации (при аутентификации) | Всегда включается, когда доступно |
| `user.account_uuid` | UUID учетной записи (при аутентификации) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (по умолчанию: true) |
| `user.account_id` | ID учетной записи в формате с тегами, соответствующий API администратора Anthropic (при аутентификации), такой как `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (по умолчанию: true) |
| `user.id` | Случайный анонимный идентификатор, генерируемый при первом запуске и сохраняемый в `~/.claude.json`. Он не содержит личной информации и не является производным от вашей учетной записи Claude. Удаление файла создает новое несвязанное значение при следующем запуске. | Всегда включается |
| `user.email` | Адрес электронной почты пользователя (при аутентификации через OAuth) | Всегда включается, когда доступно |
| `terminal.type` | Тип терминала, такой как `iTerm.app`, `vscode`, `cursor` или `tmux` | Всегда включается при обнаружении |
| Ключи из `OTEL_RESOURCE_ATTRIBUTES` | Пользовательские атрибуты, которые вы установили, такие как `department` или `team.id`. См. [Поддержка многокомандной организации](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (по умолчанию: true) |
Когда Claude Code подписан на [Claude apps gateway](/ru/claude-apps-gateway), CLI помечает экспорты аутентифицированной идентичностью из сеанса gateway: `user.id` является субъектом IdP, а не анонимным идентификатором установки, `user.email` является адресом электронной почты, на который выполнен вход, и `user.groups` содержит членство в группе IdP в виде строки, разделенной запятыми. Каждый экспорт также содержит `identity.source: gateway-oidc`. Идентичность gateway применяется последней, поэтому ключи `user.*` и `identity.*`, установленные через `OTEL_RESOURCE_ATTRIBUTES`, игнорируются в сеансах gateway.
События дополнительно включают следующие атрибуты. Они никогда не прикрепляются к метрикам, потому что они вызовут неограниченную кардинальность:
* `prompt.id`: UUID, коррелирующий пользовательскую подсказку со всеми последующими событиями до следующей подсказки. См. [Атрибуты корреляции событий](#event-correlation-attributes).
* `workspace.host_paths`: каталоги рабочей области хоста, выбранные в приложении для рабочего стола, как массив строк
Метрики
Claude Code экспортирует следующие метрики:
| Имя метрики | Описание | Единица |
| ------------------------------------- | --------------------------------------------------------------- | ------- |
| `claude_code.session.count` | Количество запущенных сеансов CLI | count |
| `claude_code.lines_of_code.count` | Количество строк кода, которые были изменены | count |
| `claude_code.pull_request.count` | Количество созданных pull request | count |
| `claude_code.commit.count` | Количество созданных git коммитов | count |
| `claude_code.cost.usage` | Стоимость сеанса Claude Code | USD |
| `claude_code.token.usage` | Количество использованных токенов | tokens |
| `claude_code.code_edit_tool.decision` | Количество решений о разрешении инструмента редактирования кода | count |
| `claude_code.active_time.total` | Общее активное время в секундах | s |
Детали метрик
Каждая метрика включает стандартные атрибуты, перечисленные выше. Метрики с дополнительными контекстно-специфичными атрибутами отмечены ниже.
Счетчик сеансов
Увеличивается в начале каждого сеанса.
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `start_type`: Как был запущен сеанс. Один из `"fresh"`, `"resume"`, `"continue"` или `"agents_view"`. Значение `"agents_view"` идентифицирует процесс панели управления `claude agents`, локальный пользовательский интерфейс, запущенный пользователем, а не разговорный сеанс. Отфильтруйте по этому значению, чтобы отделить запуски процесса UI от разговорных сеансов в ваших панелях управления.
Счетчик строк кода
Увеличивается при добавлении или удалении кода.
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `type`: (`"added"`, `"removed"`)
* `model`: Идентификатор модели для модели, которая внесла изменение (например, "claude-sonnet-5")
Счетчик pull request
Увеличивается при создании pull request или merge request через команду shell или инструмент MCP.
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
Счетчик коммитов
Увеличивается при создании git коммитов через Claude Code.
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
Счетчик затрат
Увеличивается после каждого запроса API.
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `model`: Идентификатор модели (например, "claude-sonnet-5")
* `query_source`: Категория подсистемы, которая выдала запрос. Один из `"main"`, `"subagent"` или `"auxiliary"`
* `speed`: `"fast"` когда запрос использовал быстрый режим. Отсутствует в противном случае
* `effort`: [Уровень усилий](/ru/model-config#adjust-effort-level), применяемый к запросу: `"low"`, `"medium"`, `"high"`, `"xhigh"` или `"max"`. Отсутствует, когда модель не поддерживает усилия.
* `agent.name`: Тип подагента, который выдал запрос. Встроенные имена агентов и агенты из официальных плагинов маркетплейса появляются как есть. Другие определяемые пользователем имена агентов заменяются на `"custom"`. Отсутствует, когда запрос не был выдан именованным типом подагента.
* `skill.name`: Навык, активный для запроса, установленный инструментом Skill, командой `/` или унаследованный порожденным подагентом. Встроенные, поставляемые, определяемые пользователем и навыки плагинов официального маркетплейса появляются как есть. Навыки плагинов третьих сторон заменяются на `"third-party"`. Отсутствует, когда нет активного навыка.
* `plugin.name`: Владельцы плагина, когда активный навык или подагент предоставляются плагином. Имена плагинов официального маркетплейса появляются как есть. Имена плагинов третьих сторон заменяются на `"third-party"`. Отсутствует, когда ни навык, ни подагент не имеют владельца плагина.
* `marketplace.name`: Маркетплейс, из которого был установлен владельцы плагин. Выдается только для плагинов официального маркетплейса. Отсутствует в противном случае.
* `mcp_server.name`: MCP сервер, чей инструмент запустился в ходе, который произвел этот запрос. Встроенные, claude.ai-проксированные и официальные имена серверов реестра появляются как есть. Пользовательские имена серверов заменяются на `"custom"`. Отсутствует, когда инструмент MCP не запустился.
* `mcp_tool.name`: Инструмент MCP, который запустился в ходе, который произвел этот запрос, с тем же редактированием, что и `mcp_server.name`. Отсутствует, когда инструмент MCP не запустился.
Счетчик токенов
Увеличивается после каждого запроса API.
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)
* `model`: Идентификатор модели (например, "claude-sonnet-5")
* `query_source`: Категория подсистемы, которая выдала запрос. Один из `"main"`, `"subagent"` или `"auxiliary"`
* `speed`: `"fast"` когда запрос использовал быстрый режим. Отсутствует в противном случае
* `effort`: [Уровень усилий](/ru/model-config#adjust-effort-level), применяемый к запросу. Подробности см. в разделе [Счетчик затрат](#cost-counter).
* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Атрибуция навыка, плагина и агента для запроса. Определения и поведение редактирования см. в разделе [Счетчик затрат](#cost-counter).
Увеличивается, когда пользователь принимает или отклоняет использование инструмента Edit, Write или NotebookEdit.
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `tool_name`: Имя инструмента (`"Edit"`, `"Write"`, `"NotebookEdit"`)
* `decision`: Решение пользователя (`"accept"`, `"reject"`)
* `source`: Источник решения. Один из `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"` или `"user_reject"`. См. [Событие решения инструмента](#tool-decision-event) для получения информации о том, что означает каждое значение.
* `language`: Язык программирования отредактированного файла, такой как `"TypeScript"`, `"Python"`, `"JavaScript"` или `"Markdown"`. Возвращает `"unknown"` для неузнанных расширений файлов.
Счетчик активного времени
Отслеживает фактическое время, потраченное на активное использование Claude Code, исключая время простоя. Эта метрика увеличивается во время взаимодействия пользователя, такого как ввод текста и чтение ответов, и во время обработки CLI, такой как выполнение инструментов и генерация ответов AI.
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `type`: `"user"` для взаимодействия с клавиатурой, `"cli"` для выполнения инструментов и ответов AI
События
Claude Code экспортирует следующие события через логи/события OpenTelemetry (когда настроен `OTEL_LOGS_EXPORTER`):
Атрибуты корреляции событий
Когда пользователь отправляет подсказку, Claude Code может сделать несколько вызовов API и запустить несколько инструментов. Атрибут `prompt.id` позволяет связать все эти события с одной подсказкой, которая их вызвала.
| Атрибут | Описание |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| `prompt.id` | Идентификатор UUID v4, связывающий все события, созданные при обработке одной пользовательской подсказки |
Чтобы отследить всю активность, вызванную одной подсказкой, отфильтруйте события по определенному значению `prompt.id`. Это возвращает событие user\_prompt, любые события api\_request и любые события tool\_result, которые произошли при обработке этой подсказки.
`prompt.id` намеренно исключен из метрик, потому что каждая подсказка генерирует уникальный ID, что создало бы постоянно растущее количество временных рядов. Используйте его только для анализа на уровне событий и аудита.
Событие пользовательской подсказки
Логируется, когда пользователь отправляет подсказку.
**Имя события**: `claude_code.user_prompt`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"user_prompt"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `prompt_length`: Длина подсказки
* `prompt`: Содержимое подсказки. Скрыто по умолчанию. Установите `OTEL_LOG_USER_PROMPTS=1` для включения
* `command_name`: Имя команды, когда подсказка вызывает одну. Встроенные и поставляемые имена команд, такие как `compact` или `debug`, выдаются как есть; псевдонимы, такие как `reset`, выдаются как введено, а не как каноническое имя. Пользовательские, плагин и MCP имена команд сворачиваются в `custom` или `mcp`, если не установлен `OTEL_LOG_TOOL_DETAILS=1`
* `command_source`: Происхождение команды, когда присутствует: `builtin`, `custom` или `mcp`. Команды, предоставляемые плагинами, сообщают как `custom`
Событие результата помощника
Логируется после каждого запроса API, который возвращает текстовое содержимое от модели. Включены только текстовые блоки ответа; блоки мышления и блоки использования инструментов исключены. Требует Claude Code v2.1.193 или позже.
**Имя события**: `claude_code.assistant_response`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"assistant_response"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `response_length`: Длина текста ответа в символах
* `response`: Текст ответа, усеченный на 60 КБ. Скрыт как `` по умолчанию. Установите `OTEL_LOG_ASSISTANT_RESPONSES=1` для включения. Когда `OTEL_LOG_ASSISTANT_RESPONSES` не установлен, `OTEL_LOG_USER_PROMPTS` контролирует его вместо этого, поэтому установите `OTEL_LOG_ASSISTANT_RESPONSES=0`, чтобы сохранить ответы скрытыми, пока логирование подсказок включено
* `model`: Идентификатор модели (например, "claude-sonnet-4-6")
* `request_id`: ID запроса Anthropic API из заголовка ответа `request-id`. Присутствует только, когда API возвращает его
* `query_source`: Подсистема, которая выдала запрос, такая как `"repl_main_thread"`, `"compact"` или имя подагента
Логируется, когда инструмент завершает выполнение. Не выдается, если вызов инструмента был отклонен; см. [Событие решения инструмента](#tool-decision-event) для отклонений.
**Имя события**: `claude_code.tool_result`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"tool_result"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `tool_name`: Имя инструмента
* `tool_use_id`: Уникальный идентификатор для этого вызова инструмента. Совпадает с `tool_use_id`, переданным в hooks, позволяя корреляцию между событиями OTel и данными, захваченными hooks.
* `success`: `"true"` или `"false"`
* `duration_ms`: Время выполнения в миллисекундах
* `error_type`: Строка категории ошибки при сбое инструмента, такая как `"Error:ENOENT"` или `"ShellError"`
* `error` (когда `OTEL_LOG_TOOL_DETAILS=1`): Полное сообщение об ошибке при сбое инструмента
* `decision_type`: Всегда `"accept"`, так как это событие выдается только после запуска инструмента. Отклоненные вызовы не производят результат инструмента
* `decision_source`: Источник решения о разрешении. Один из `"config"`, `"hook"`, `"user_permanent"` или `"user_temporary"`. См. [Событие решения инструмента](#tool-decision-event) для получения информации о том, что означает каждое значение. Источники, только для отклонения, `"user_abort"` и `"user_reject"`, никогда не появляются на этом событии.
* `tool_input_size_bytes`: Размер JSON-сериализованного входа инструмента в байтах
* `tool_result_size_bytes`: Размер результата инструмента в байтах
* `mcp_server_scope`: Идентификатор области MCP сервера (для инструментов MCP)
* `tool_parameters` (когда `OTEL_LOG_TOOL_DETAILS=1`): JSON строка, содержащая параметры, специфичные для инструмента:
* Для инструмента Bash: включает `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox` и `git_commit_id` (SHA коммита, когда команда `git commit` успешна)
* Для инструмента WorkspaceBash: включает `bash_command`, `full_command`, `timeout`
* Для инструментов MCP: включает `mcp_server_name`, `mcp_tool_name`
* Для инструмента Skill: включает `skill_name`
* Для инструмента Agent или устаревшего инструмента Task: включает `subagent_type`
* `tool_input` (когда `OTEL_LOG_TOOL_DETAILS=1`): JSON-сериализованные аргументы инструмента. Отдельные значения более 512 символов усекаются, и полная нагрузка ограничена примерно 4 K символами. Применяется ко всем инструментам, включая инструменты MCP.
Событие запроса API
Логируется для каждого запроса API к Claude.
**Имя события**: `claude_code.api_request`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"api_request"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `model`: Используемая модель (например, "claude-sonnet-5")
* `cost_usd`: Приблизительная стоимость в USD
* `duration_ms`: Длительность запроса в миллисекундах
* `input_tokens`: Количество входных токенов
* `output_tokens`: Количество выходных токенов
* `cache_read_tokens`: Количество токенов, прочитанных из кэша
* `cache_creation_tokens`: Количество токенов, использованных для создания кэша
* `request_id`: ID запроса Anthropic API из заголовка ответа `request-id`, такой как `"req_011..."`. Присутствует только, когда API возвращает его.
* `speed`: `"fast"` или `"normal"`, указывающий, был ли активен быстрый режим
* `query_source`: Подсистема, которая выдала запрос, такая как `"repl_main_thread"`, `"compact"` или имя подагента
* `effort`: [Уровень усилий](/ru/model-config#adjust-effort-level), применяемый к запросу: `"low"`, `"medium"`, `"high"`, `"xhigh"` или `"max"`. Отсутствует, когда модель не поддерживает усилия.
* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Атрибуция навыка, плагина, агента и MCP для запроса. Определения и поведение редактирования см. в разделе [Счетчик затрат](#cost-counter).
Событие ошибки API
Логируется, когда запрос API к Claude не удается.
**Имя события**: `claude_code.api_error`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"api_error"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `model`: Используемая модель (например, "claude-sonnet-5")
* `error`: Сообщение об ошибке
* `status_code`: HTTP код состояния в виде числа. Отсутствует для ошибок, не связанных с HTTP, таких как сбои соединения.
* `duration_ms`: Длительность запроса в миллисекундах
* `attempt`: Общее количество попыток, включая исходный запрос (`1` означает, что повторных попыток не было)
* `request_id`: ID запроса Anthropic API из заголовка ответа `request-id`, такой как `"req_011..."`. Присутствует только, когда API возвращает его.
* `speed`: `"fast"` или `"normal"`, указывающий, был ли активен быстрый режим
* `query_source`: Подсистема, которая выдала запрос, такая как `"repl_main_thread"`, `"compact"` или имя подагента
* `effort`: [Уровень усилий](/ru/model-config#adjust-effort-level), применяемый к запросу. Отсутствует, когда модель не поддерживает усилия.
* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Атрибуция навыка, плагина, агента и MCP для запроса. Определения и поведение редактирования см. в разделе [Счетчик затрат](#cost-counter).
Событие отказа API
Логируется, когда запрос API возвращает `stop_reason: "refusal"`. Отказы поступают в успешном потоке ответов, а не как ошибка HTTP, поэтому событие `api_error` не срабатывает для них. Это событие позволяет отслеживать частоту отказов и группировать отказы по тем же атрибутам, что и `api_request` и `api_error`.
**Имя события**: `claude_code.api_refusal`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"api_refusal"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `model`: Идентификатор модели из запроса
* `request_id`: ID запроса Anthropic API из заголовка ответа `request-id`, такой как `"req_011..."`. Присутствует только, когда API возвращает его.
* `query_source`: Подсистема, которая выдала запрос, такая как `"repl_main_thread"`, `"compact"` или имя подагента. Определения см. в разделе [`api_request`](#api-request-event).
* `speed`: Либо `"fast"` когда активен [Fast mode](/ru/fast-mode), либо `"normal"`
* `attempt`: Номер попытки повтора. Первая попытка это `1`.
* `effort`: [Уровень усилий](/ru/model-config#adjust-effort-level), применяемый к запросу. Отсутствует, когда модель не поддерживает усилия.
* `server_fallback_hop`: `true` когда резервный вариант модели на стороне сервера API уже повторил этот отказ на другой модели, поэтому пользователь не видел этот конкретный отказ. `false` когда запрос закончился отказом. Один ход может выдать как событие `true` hop, так и позже событие `false` final, когда модель резервного варианта также отказывает.
* `has_category`: `true` когда ответ API содержал `stop_details.category` из `"cyber"`, `"bio"`, `"frontier_llm"` или `"reasoning_extraction"`. `false` когда ответ не содержал категорию или значение вне этого набора. Отсутствует, когда `server_fallback_hop` это `true`, потому что hop блоки не содержат `stop_details`.
* `has_explanation`: `true` когда ответ API содержал `stop_details.explanation`, иначе `false`. Отсутствует, когда `server_fallback_hop` это `true`.
* `category`: Значение `stop_details.category` из ответа API. Один из `"cyber"`, `"bio"`, `"frontier_llm"` или `"reasoning_extraction"`. Присутствует только, когда установлен `OTEL_LOG_TOOL_DETAILS=1` и `has_category` это `true`.
* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Атрибуция навыка, плагина, агента и MCP для запроса. Определения и поведение редактирования см. в разделе [Счетчик затрат](#cost-counter).
Событие тела запроса API
Логируется для каждой попытки запроса API, когда установлен `OTEL_LOG_RAW_API_BODIES`. Одно событие выдается за попытку, поэтому повторные попытки с скорректированными параметрами каждая производят свое собственное событие.
**Имя события**: `claude_code.api_request_body`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"api_request_body"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `body`: JSON-сериализованные параметры запроса Messages API (системная подсказка, сообщения, инструменты и т.д.), усеченные на 60 КБ. Содержимое расширенного мышления в предыдущих ходах помощника скрыто. Выдается только в встроенном режиме (`OTEL_LOG_RAW_API_BODIES=1`).
* `body_ref`: Абсолютный путь к файлу `/.request.json`, содержащему неусеченное тело. Выдается только в режиме файла (`OTEL_LOG_RAW_API_BODIES=file:`).
* `body_length`: Длина неусеченного тела. UTF-8 байты, когда `OTEL_LOG_RAW_API_BODIES=file:`, или единицы кода UTF-16, когда `=1`
* `body_truncated`: `"true"` когда произошло встроенное усечение. Отсутствует в режиме файла и когда усечение не произошло.
* `model`: Идентификатор модели из параметров запроса
* `query_source`: Подсистема, которая выдала запрос (например, `"compact"`)
Событие тела ответа API
Логируется для каждого успешного ответа API, когда установлен `OTEL_LOG_RAW_API_BODIES`.
**Имя события**: `claude_code.api_response_body`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"api_response_body"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `body`: JSON-сериализованный ответ Messages API (id, блоки содержимого, использование, причина остановки), усеченный на 60 КБ. Содержимое расширенного мышления скрыто. Выдается только в встроенном режиме (`OTEL_LOG_RAW_API_BODIES=1`).
* `body_ref`: Абсолютный путь к файлу `/.response.json`, содержащему неусеченное тело. Выдается только в режиме файла (`OTEL_LOG_RAW_API_BODIES=file:`).
* `body_length`: Длина неусеченного тела. UTF-8 байты, когда `OTEL_LOG_RAW_API_BODIES=file:`, или единицы кода UTF-16, когда `=1`
* `body_truncated`: `"true"` когда произошло встроенное усечение. Отсутствует в режиме файла и когда усечение не произошло.
* `model`: Идентификатор модели
* `query_source`: Подсистема, которая выдала запрос
* `request_id`: ID запроса Anthropic API из заголовка ответа `request-id`, такой как `"req_011..."`. Присутствует только, когда API возвращает его.
Логируется, когда принимается решение о разрешении инструмента (принять/отклонить).
**Имя события**: `claude_code.tool_decision`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"tool_decision"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `tool_name`: Имя инструмента (например, "Read", "Edit", "Write", "NotebookEdit")
* `tool_use_id`: Уникальный идентификатор для этого вызова инструмента. Совпадает с `tool_use_id`, переданным в hooks, позволяя корреляцию между событиями OTel и данными, захваченными hooks.
* `decision`: Либо `"accept"`, либо `"reject"`
* `source`: Источник решения:
* `"config"`: Решено автоматически без запроса, на основе параметров проекта, правил разрешения или запрета в личных параметрах пользователя, корпоративной управляемой политики, флагов `--allowedTools` или `--disallowedTools`, активного режима разрешений, разрешения в области сеанса из более ранней подсказки в том же интерактивном сеансе CLI, или потому что инструмент по своей природе безопасен. Событие не указывает, какой из этих источников совпал.
* `"hook"`: Hook `PreToolUse` или `PermissionRequest` вернул решение.
* `"user_permanent"`: Выдается, когда пользователь выбрал "Да, и больше не спрашивать для ..." при запросе разрешения, что сохраняет правило разрешения в его личных параметрах. В интерактивном CLI это выдается только для самого этого выбора; более поздние вызовы, которые соответствуют сохраненному правилу, выдают `"config"` вместо этого. В Agent SDK или неинтерактивных сеансах `-p` как начальный выбор, так и более поздние совпадения правил выдают `"user_permanent"`. Рассматривается как принятие.
* `"user_temporary"`: Выдается, когда пользователь выбрал "Да" при запросе разрешения для одноразового одобрения, или выбрал один из вариантов "... во время этого сеанса" на запросе редактирования или чтения файла. В интерактивном CLI это выдается только для самого выбора; более поздние вызовы, разрешенные этим разрешением в области сеанса, выдают `"config"` вместо этого. В Agent SDK или неинтерактивных сеансах `-p` как выбор, так и более поздние совпадения выдают `"user_temporary"`. Рассматривается как принятие.
* `"user_abort"`: Выдается, когда пользователь отклонил запрос разрешения без ответа. Рассматривается как отклонение.
* `"user_reject"`: Выдается, когда пользователь выбрал "Нет" при запросе. В интерактивном CLI это выдается только для самого этого выбора; вызовы, которые соответствуют правилу отказа в личных параметрах пользователя, выдают `"config"` вместо этого. В Agent SDK или неинтерактивных сеансах `-p` вызовы, которые соответствуют правилу отказа в личных параметрах, выдают `"user_reject"`. Рассматривается как отклонение.
* `tool_parameters` (когда `OTEL_LOG_TOOL_DETAILS=1`): JSON строка, содержащая параметры, специфичные для инструмента. Та же форма, что и [Событие результата инструмента](#tool-result-event), минус поля после выполнения, такие как `git_commit_id`. Значения могут отличаться от `tool_result` для принятого вызова, если решение о разрешении переписывает входные данные инструмента через `updatedInput`. Используйте этот атрибут, чтобы увидеть, какая команда была отклонена, когда `decision` это `"reject"`.
* Для инструмента Bash: включает `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`
* Для инструмента WorkspaceBash: включает `bash_command`, `full_command`, `timeout`
* Для инструментов MCP: включает `mcp_server_name`, `mcp_tool_name`
* Для инструмента Skill: включает `skill_name`
* Для инструмента Agent или устаревшего инструмента Task: включает `subagent_type`
Событие изменения режима разрешений
Логируется, когда режим разрешений изменяется, например при циклировании Shift+Tab, выходе из Plan Mode или проверке gate автоматического режима.
**Имя события**: `claude_code.permission_mode_changed`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"permission_mode_changed"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `from_mode`: Предыдущий режим разрешений, например `"default"`, `"plan"`, `"acceptEdits"`, `"auto"` или `"bypassPermissions"`
* `to_mode`: Новый режим разрешений
* `trigger`: Что вызвало изменение. Один из `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"` или `"auto_opt_in"`. Отсутствует, когда переход исходит из SDK или моста
Событие аутентификации
Логируется, когда `/login` или `/logout` завершается.
**Имя события**: `claude_code.auth`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"auth"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `action`: `"login"` или `"logout"`
* `success`: `"true"` или `"false"`
* `auth_method`: Метод аутентификации, такой как `"oauth"`
* `error_category`: Категориальный вид ошибки при сбое действия. Исходное сообщение об ошибке никогда не включается
* `status_code`: HTTP код состояния в виде строки при сбое действия с ошибкой HTTP
Событие подключения MCP сервера
Логируется, когда MCP сервер подключается, отключается или не удается подключиться.
**Имя события**: `claude_code.mcp_server_connection`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"mcp_server_connection"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `status`: `"connected"`, `"failed"` или `"disconnected"`
* `transport_type`: Транспорт сервера, такой как `"stdio"`, `"sse"` или `"http"`
* `server_scope`: Область, в которой настроен сервер, такая как `"user"`, `"project"` или `"local"`
* `duration_ms`: Длительность попытки подключения в миллисекундах
* `error_code`: Код ошибки при сбое подключения
* `is_plugin`: `true` когда сервер предоставляется плагином, `false` в противном случае
* `plugin_id_hash` (когда `is_plugin` это `true`): Стабильный хеш имени плагина и маркетплейса для группировки событий по плагину без раскрытия имени
* `plugin.name` (когда `is_plugin` это `true`): Имя плагина, который предоставляет сервер. Для плагинов третьих сторон это буквальная строка `"third-party"`, если не установлен `OTEL_LOG_TOOL_DETAILS=1`; это защищает имена плагинов третьих сторон от появления в логах по умолчанию. Плагины из официальных источников Anthropic всегда идентифицируются по имени. Атрибуты `plugin_id_hash` и `plugin.name` поступают на ваш собственный бэкенд мониторинга и не отправляются в Anthropic
* `server_name` (когда `OTEL_LOG_TOOL_DETAILS=1`): Настроенное имя сервера
* `error` (когда `OTEL_LOG_TOOL_DETAILS=1`): Полное сообщение об ошибке при сбое подключения
Событие внутренней ошибки
Логируется, когда Claude Code перехватывает неожиданную внутреннюю ошибку. Записываются только имя класса ошибки и код в стиле errno. Сообщение об ошибке и трассировка стека никогда не включаются. Это событие не выдается при запуске против Bedrock, Vertex или Foundry, или когда установлен `DISABLE_ERROR_REPORTING`.
**Имя события**: `claude_code.internal_error`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"internal_error"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `error_name`: Имя класса ошибки, такой как `"TypeError"` или `"SyntaxError"`
* `error_code`: Код errno Node.js, такой как `"ENOENT"`, когда присутствует в ошибке
Событие установки плагина
Логируется, когда плагин завершает установку, как из команды CLI `claude plugin install`, так и из интерактивного UI `/plugin`.
**Имя события**: `claude_code.plugin_installed`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"plugin_installed"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `marketplace.is_official`: `"true"` если маркетплейс является официальным маркетплейсом Anthropic, `"false"` в противном случае
* `install.trigger`: `"cli"` или `"ui"`
* `plugin.name`: Имя установленного плагина. Для сторонних маркетплейсов это включается только, когда `OTEL_LOG_TOOL_DETAILS=1`
* `plugin.version`: Версия плагина, когда объявлена в записи маркетплейса. Для сторонних маркетплейсов это включается только, когда `OTEL_LOG_TOOL_DETAILS=1`
* `marketplace.name`: Маркетплейс, из которого был установлен плагин. Для сторонних маркетплейсов это включается только, когда `OTEL_LOG_TOOL_DETAILS=1`
Событие загрузки плагина
Логируется один раз для каждого включенного плагина при запуске сеанса. Используйте это событие для инвентаризации активных плагинов в вашем парке, как дополнение к `plugin_installed`, которое записывает само действие установки.
**Имя события**: `claude_code.plugin_loaded`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"plugin_loaded"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `plugin.name`: имя плагина. Для плагинов вне официального маркетплейса и встроенного пакета значение `"third-party"`, если не установлен `OTEL_LOG_TOOL_DETAILS=1`
* `marketplace.name`: маркетплейс, из которого был установлен плагин, когда известен. Скрыто как `"third-party"` при том же условии, что и `plugin.name`
* `plugin.version`: версия из манифеста плагина. Включается только, когда имя не скрыто и манифест объявляет версию
* `plugin.scope`: категория происхождения для плагина: `"official"`, `"org"`, `"user-local"` или `"default-bundle"`
* `enabled_via`: как плагин был включен: `"default-enable"`, `"org-policy"`, `"seed-mount"` или `"user-install"`
* `plugin_id_hash`: детерминированный хеш имени плагина и маркетплейса, отправляемый только на ваш настроенный экспортер. Позволяет вам подсчитать, сколько различных плагинов третьих сторон загружено в вашем парке, без записи их имен
* `has_hooks`: предоставляет ли плагин hooks
* `has_mcp`: предоставляет ли плагин MCP серверы
* `host_owned_mcp`: `true` когда хост SDK управляет подключениями MCP этого плагина и Claude Code пропустил чтение конфигурации MCP сервера плагина, `false` в противном случае. Требует Claude Code v2.1.172 или позже
* `skill_path_count`: количество каталогов навыков, которые объявляет плагин
* `command_path_count`: количество каталогов команд, которые объявляет плагин
* `agent_path_count`: количество каталогов агентов, которые объявляет плагин
* `safe_mode`: `"true"` когда сеанс был запущен с [`--safe-mode`](/ru/cli-reference), `"false"` в противном случае. В безопасном режиме это событие сообщает только настроенный инвентарь; команды, навыки, hooks и MCP серверы плагина не загружаются. Требует Claude Code v2.1.169 или позже
Событие активации навыка
Логируется, когда навык вызывается, будь то Claude вызывает его через инструмент Skill или вы запускаете его как команду `/`.
**Имя события**: `claude_code.skill_activated`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"skill_activated"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `skill.name`: Имя навыка. Для определяемых пользователем и сторонних плагин навыков значение является заполнителем `"custom_skill"`, если не установлен `OTEL_LOG_TOOL_DETAILS=1`
* `invocation_trigger`: Как был вызван навык (`"user-slash"`, `"claude-proactive"` или `"nested-skill"`)
* `skill.source`: Откуда был загружен навык (например, `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)
* `skill.kind`: `"workflow"` когда навык является навыком workflow. Отсутствует в противном случае
* `plugin.name` (когда `OTEL_LOG_TOOL_DETAILS=1` или плагин из официального маркетплейса): Имя владельца плагина, когда навык предоставляется плагином
* `marketplace.name` (когда `OTEL_LOG_TOOL_DETAILS=1` или плагин из официального маркетплейса): Маркетплейс владельца плагина, когда навык предоставляется плагином
Событие упоминания @
Логируется, когда Claude Code разрешает упоминание `@` в подсказке. Не каждое упоминание выдает событие: пути раннего выхода, такие как отказ в разрешении, файлы большого размера, вложения ссылок PDF и сбои при перечислении каталогов, возвращаются без логирования.
**Имя события**: `claude_code.at_mention`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"at_mention"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `mention_type`: Тип упоминания (`"file"`, `"directory"`, `"agent"`, `"mcp_resource"`)
* `success`: Было ли упоминание успешно разрешено (`"true"` или `"false"`)
Событие исчерпания повторных попыток API
Логируется один раз, когда запрос API не удается после более чем одной попытки. Выдается вместе с финальным событием `api_error`.
**Имя события**: `claude_code.api_retries_exhausted`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"api_retries_exhausted"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `model`: Используемая модель
* `error`: Финальное сообщение об ошибке
* `status_code`: HTTP код состояния в виде числа. Отсутствует для ошибок, не связанных с HTTP.
* `total_attempts`: Общее количество попыток
* `total_retry_duration_ms`: Общее время в реальном времени по всем попыткам
* `speed`: `"fast"` или `"normal"`
Событие регистрации hook
Логируется один раз для каждого настроенного hook при запуске сеанса. Используйте это событие для инвентаризации активных hooks в вашем парке, как дополнение к событиям `hook_execution_start` и `hook_execution_complete` для каждого выполнения.
**Имя события**: `claude_code.hook_registered`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"hook_registered"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `hook_event`: тип события hook, такой как `"PreToolUse"` или `"PostToolUse"`
* `hook_type`: тип реализации hook: `"command"`, `"prompt"`, `"mcp_tool"`, `"http"` или `"agent"`
* `hook_source`: где определен hook: `"userSettings"`, `"projectSettings"`, `"localSettings"`, `"flagSettings"`, `"policySettings"` или `"pluginHook"`
* `safe_mode`: `"true"` когда сеанс был запущен с [`--safe-mode`](/ru/cli-reference), `"false"` в противном случае. Требует Claude Code v2.1.169 или позже
* `hook_matcher` (когда `OTEL_LOG_TOOL_DETAILS=1`): строка matcher из конфигурации hook, когда она установлена
* `plugin.name` (когда `hook_source` это `"pluginHook"`): имя участвующего плагина. Для плагинов вне официального маркетплейса и встроенного пакета значение `"third-party"`, если не установлен `OTEL_LOG_TOOL_DETAILS=1`
* `plugin_id_hash` (когда `hook_source` это `"pluginHook"`): детерминированный хеш имени плагина и маркетплейса, отправляемый только на ваш настроенный экспортер. Позволяет вам подсчитать различные участвующие плагины без записи их имен
Событие начала выполнения hook
Логируется, когда один или несколько hooks начинают выполняться для события hook.
**Имя события**: `claude_code.hook_execution_start`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"hook_execution_start"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `hook_event`: Тип события hook, такой как `"PreToolUse"` или `"PostToolUse"`
* `hook_name`: Полное имя hook, включая matcher, такой как `"PreToolUse:Write"`
* `num_hooks`: Количество соответствующих команд hook
* `managed_only`: `"true"` когда разрешены только управляемые политики hooks
* `hook_source`: `"policySettings"` или `"merged"`
* `safe_mode`: `"true"` когда сеанс был запущен с [`--safe-mode`](/ru/cli-reference), `"false"` в противном случае. Требует Claude Code v2.1.169 или позже
* `hook_definitions`: JSON-сериализованная конфигурация hook. Включается только, когда включены как детальная бета-трассировка, так и `OTEL_LOG_TOOL_DETAILS=1`
Событие завершения выполнения hook
Логируется, когда все hooks для события hook завершены.
**Имя события**: `claude_code.hook_execution_complete`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"hook_execution_complete"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `hook_event`: Тип события hook
* `hook_name`: Полное имя hook, включая matcher
* `num_hooks`: Количество соответствующих команд hook
* `num_success`: Количество, которые завершились успешно
* `num_blocking`: Количество, которые вернули решение блокировки
* `num_non_blocking_error`: Количество, которые не удались без блокировки
* `num_cancelled`: Количество, отмененные до завершения
* `total_duration_ms`: Длительность в реальном времени всех соответствующих hooks
* `managed_only`: `"true"` когда разрешены только управляемые политики hooks
* `hook_source`: `"policySettings"` или `"merged"`
* `safe_mode`: `"true"` когда сеанс был запущен с [`--safe-mode`](/ru/cli-reference), `"false"` в противном случае. Требует Claude Code v2.1.169 или позже
* `hook_definitions`: JSON-сериализованная конфигурация hook. Включается только, когда включены как детальная бета-трассировка, так и `OTEL_LOG_TOOL_DETAILS=1`
Событие метрик плагина hook
Логируется, когда hook плагина из официального маркетплейса выдает метрики для каждого вызова. Только плагины, установленные из официального маркетплейса Anthropic, могут выдавать эти метрики. Плагины сторонних маркетплейсов и пользовательские hooks не выдают в это событие. Используйте это событие для мониторинга поведения плагина, такого как показатели поиска, затраты и длительность из вашего собственного стека наблюдаемости.
**Имя события**: `claude_code.hook_plugin_metrics`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"hook_plugin_metrics"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `plugin_id`: идентификатор плагина в форме `@`
* `hook_event`: тип события hook, который выдал метрики
* До 20 ключей метрик, выданных плагином. Имена соответствуют `^[a-z][a-z0-9_]{0,39}$`. Значения являются логическими или числовыми.
Событие компактирования
Логируется, когда компактирование разговора завершается.
**Имя события**: `claude_code.compaction`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"compaction"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `trigger`: `"auto"` или `"manual"`
* `success`: `"true"` или `"false"`
* `duration_ms`: Длительность компактирования
* `pre_tokens`: Приблизительное количество токенов до компактирования
* `post_tokens`: Приблизительное количество токенов после компактирования
* `error`: Сообщение об ошибке при сбое компактирования
* `precompute_reuse`: Установлено только, когда `trigger` это `"manual"`. Автоматическое компактирование может подготовить сводку в фоновом режиме перед заполнением окна контекста, и этот атрибут записывает, была ли эта подготовленная сводка повторно использована `/compact`. `"hit"` означает, что она была повторно использована; `"miss_custom_instructions"`, `"miss_hook"` и `"miss_not_ready"` дают причину, по которой вместо этого была вычислена свежая сводка. Требует Claude Code v2.1.153 или позже
Событие опроса обратной связи
Логируется, когда опрос качества сеанса показывается или на него отвечают. Дополнительную информацию о том, что собирают опросы и как их контролировать, см. в разделе [Опросы качества сеанса](/ru/data-usage#session-quality-surveys).
**Имя события**: `claude_code.feedback_survey`
**Атрибуты**:
* Все [стандартные атрибуты](#standard-attributes)
* `event.name`: `"feedback_survey"`
* `event.timestamp`: Временная метка ISO 8601
* `event.sequence`: монотонно возрастающий счетчик для упорядочивания событий в сеансе
* `event_type`: Событие жизненного цикла опроса, например `"appeared"`, `"responded"` или `"transcript_prompt_appeared"`
* `appearance_id`: Уникальный ID, связывающий события, выданные для одного экземпляра опроса
* `survey_type`: Какой опрос произвел событие. `"session"` это подсказка рейтинга "Как работает Claude?"
* `response`: Выбор пользователя на событиях `responded`
* `enabled_via_override`: `true` когда установлен [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/ru/env-vars). Выдается как логическое значение, а не строка. Присутствует на событиях опроса `session`. Отфильтруйте по этому атрибуту, чтобы подтвердить, что переопределение применяется в вашем парке
Интерпретация данных метрик и событий
Экспортируемые метрики и события поддерживают ряд анализов:
Мониторинг использования
| Метрика | Возможность анализа |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `claude_code.token.usage` | Разбить по `type` (input/output), пользователю, команде, модели, `skill.name`, `plugin.name` или `agent.name` |
| `claude_code.session.count` | Отслеживать принятие и вовлеченность с течением времени |
| `claude_code.lines_of_code.count` | Измерить производительность, отслеживая добавления и удаления кода, разбитые по моделям |
| `claude_code.commit.count` & `claude_code.pull_request.count` | Понять влияние на рабочие процессы разработки |
Мониторинг затрат
Метрика `claude_code.cost.usage` помогает с:
* Отслеживанием тенденций использования по командам или отдельным лицам
* Выявлением сеансов с высоким использованием для оптимизации
* Атрибуцией расходов конкретным навыкам, плагинам или типам подагентов через атрибуты `skill.name`, `plugin.name` и `agent.name`
Метрики затрат являются приблизительными. Для официальных данных о выставлении счетов обратитесь к вашему поставщику API (Claude Console, Amazon Bedrock или Google Cloud Vertex).
Оповещения и сегментация
Распространенные оповещения, которые следует рассмотреть:
* Скачки затрат
* Необычное потребление токенов
* Высокий объем сеансов от конкретных пользователей
Все метрики можно сегментировать по [стандартным атрибутам](#standard-attributes). Атрибут `model` доступен на `claude_code.token.usage`, `claude_code.cost.usage` и {/* min-version: 2.1.172 */}начиная с версии 2.1.172, `claude_code.lines_of_code.count`.
Разбивки по моделям для коммитов можно только приблизительно оценить, объединив данные с метриками токенов или затрат по `session.id`, поскольку один сеанс может охватывать несколько моделей. Отфильтруйте сторону токенов или затрат до строк, где `query_source` равен `"main"`, чтобы вспомогательные запросы и запросы подагентов не приписывали коммиты сеанса модели, которая их не создавала.
Обнаружение исчерпания повторных попыток
Claude Code повторяет неудачные запросы API внутри и выдает одно событие `claude_code.api_error` только после того, как сдается, поэтому само событие является терминальным сигналом для этого запроса. Промежуточные повторные попытки не логируются как отдельные события.
Атрибут `attempt` на событии записывает, сколько попыток было сделано в общей сложности. `CLAUDE_CODE_MAX_RETRIES` по умолчанию равен `10` и ограничен `15`. Когда запрос исчерпывает все повторные попытки при переходной ошибке, `attempt` равен на один больше, чем это эффективное ограничение: 11 по умолчанию и никогда не более 16. Более низкое значение указывает на неповторяемую ошибку, такую как ответ `400`.
Чтобы различить сеанс, который восстановился, от того, который застопорился, сгруппируйте события по `session.id` и проверьте, существует ли более позднее событие `api_request` после ошибки.
Анализ событий
Данные событий предоставляют подробные сведения о взаимодействиях Claude Code:
**Паттерны использования инструментов**: анализируйте события результатов инструментов для выявления:
* Наиболее часто используемых инструментов
* Показателей успеха инструментов
* Среднего времени выполнения инструментов
* Паттернов ошибок по типам инструментов
**Мониторинг производительности**: отслеживайте длительность запросов API и время выполнения инструментов для выявления узких мест производительности.
Аудит событий безопасности
События OpenTelemetry являются источником данных аудита для активности Claude Code. Каждое событие содержит атрибуты идентификации, которые связывают вызовы инструментов, активность MCP и решения о разрешениях с пользователем, который их инициировал. Экспортер логов OTLP может доставлять эти события на любую платформу Security Information and Event Management (SIEM) с приемником OTLP или на OpenTelemetry Collector, который перенаправляет на ваш SIEM.
Атрибуция действий пользователям
[Стандартные атрибуты](#standard-attributes) на каждом событии включают идентификацию аутентифицированного пользователя: `user.email`, `user.account_uuid`, `user.account_id` и `organization.id` при входе с учетной записью Claude, плюс `user.id` и область сеанса `session.id`. `user.id` является идентификатором, ограниченным установкой, за исключением сеансов [Claude apps gateway](/ru/claude-apps-gateway), где это субъект IdP из выданного шлюзом токена.
Вызовы инструментов MCP, команды Bash и редактирование файлов поэтому приписываются разработчику, который запустил сеанс. Claude Code не действует под отдельной учетной записью сервиса; идентификация, записанная на каждом событии, это собственная учетная запись Claude разработчика или идентификация IdP разработчика в сеансе [Claude apps gateway](/ru/claude-apps-gateway).
Когда Claude Code аутентифицируется с прямым ключом API или против Bedrock, Vertex AI или Microsoft Foundry, в сеансе нет учетной записи Claude и только `user.id` и `session.id` заполняются. В этих развертываниях прикрепите идентификацию пользователя самостоятельно с помощью `OTEL_RESOURCE_ATTRIBUTES`, установленного для каждого пользователя через файл [управляемых параметров](#administrator-configuration) или оболочку запуска. Сеансы Claude apps gateway не требуют ничего из этого: CLI автоматически проставляет идентификацию IdP, как описано в [Стандартные атрибуты](#standard-attributes).
```bash theme={null}
export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."
```
Аудит активности MCP
Чтобы захватить активность MCP сервера с полной деталью вызова, включите экспортер логов и установите `OTEL_LOG_TOOL_DETAILS=1`. Каждая операция MCP затем производит структурированные события, которые несут имя сервера, имя инструмента и аргументы вызова вместе со стандартными атрибутами идентификации:
| Событие | Что оно записывает для MCP |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp_server_connection` | Подключение сервера, отключение и сбой подключения с `server_name`, `transport_type`, `server_scope` и деталью ошибки |
| `tool_result` | Каждый вызов инструмента MCP с `tool_name` и `mcp_server_scope`, полезной нагрузкой `tool_parameters`, содержащей `mcp_server_name` и `mcp_tool_name`, и полезной нагрузкой `tool_input`, содержащей аргументы вызова |
| `tool_decision` | Был ли вызов разрешен или отклонен, исходило ли решение из конфигурации, hook или пользователя, и полезная нагрузка `tool_parameters`, содержащая `mcp_server_name` и `mcp_tool_name` |
Без `OTEL_LOG_TOOL_DETAILS` эти события опускают идентифицирующую деталь:
* `tool_result`: сохраняет `tool_name` и `mcp_server_scope`, опускает `mcp_server_name`, `mcp_tool_name` и аргументы
* `tool_decision`: сохраняет `tool_name`, опускает `tool_parameters`
* `mcp_server_connection`: опускает `server_name` и сообщение об ошибке, но сохраняет `is_plugin`, `plugin_id_hash` и `plugin.name`, с именами плагинов, не относящихся к Anthropic, отредактированными на буквальное значение `"third-party"`, поэтому серверы, предоставляемые плагинами, остаются различимыми без подробного логирования
Сопоставление вопросов безопасности с событиями
При построении правил обнаружения найдите сигнал, который вы хотите отслеживать, и запросите ваш бэкенд для соответствующего события и атрибутов:
| Сигнал | Событие | Ключевые атрибуты |
| ------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Вызов инструмента разрешен или отклонен, и почему | `tool_decision` | `decision`, `source`, `tool_name`, `tool_parameters` |
| Эскалация режима разрешений | `permission_mode_changed` | `from_mode`, `to_mode`, `trigger` |
| Hook политики заблокировал действие | `hook_execution_complete` | `hook_event`, `num_blocking` |
| Вход, выход и сбой аутентификации | `auth` | `action`, `success`, `error_category` |
| Подключение MCP сервера или сбой | `mcp_server_connection` | `status`, `server_name`, `is_plugin`, `error_code` |
| Установленный плагин и его источник | `plugin_installed` | `plugin.name`, `marketplace.name`, `marketplace.is_official` |
| Запущенные команды и затронутые файлы | `tool_result` (выполнено) или `tool_decision` (отклонено) с `OTEL_LOG_TOOL_DETAILS=1` | `tool_parameters`; `tool_input` (только `tool_result`) |
Claude Code выдает только поток исходных событий. Обнаружение аномалий, базирование, корреляция между сеансами и оповещение являются ответственностью вашего SIEM или бэкенда наблюдаемости.
Отправка событий в SIEM
Укажите `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` на приемник OTLP вашего SIEM или на OpenTelemetry Collector, который перенаправляет на собственный API приема вашего SIEM. Следующий пример управляемых параметров экспортирует только события с полной деталью инструмента, включенной для аудита MCP и Bash:
```json theme={null}
{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_LOGS_EXPORTER": "otlp",
"OTEL_LOG_TOOL_DETAILS": "1",
"OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
"OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
"OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
}
}
```
Рассмотрения бэкенда
Выбор вашего бэкенда метрик, логов и трассировок определяет типы анализов, которые вы можете выполнять:
Для метрик
* **Базы данных временных рядов (например, Prometheus)**: Расчеты скорости, агрегированные метрики
* **Колончатые хранилища (например, ClickHouse)**: Сложные запросы, анализ уникальных пользователей
* **Полнофункциональные платформы наблюдаемости (например, Honeycomb, Datadog, Grafana Cloud)**: Продвинутые запросы, визуализация, оповещения
Для событий/логов
* **Системы агрегации логов (например, Elasticsearch, Loki)**: Полнотекстовый поиск, анализ логов
* **Колончатые хранилища (например, ClickHouse)**: Анализ структурированных событий
* **Полнофункциональные платформы наблюдаемости (например, Honeycomb, Datadog, Grafana Cloud)**: Корреляция между метриками и событиями
Для трассировок
Выберите бэкенд, поддерживающий хранилище распределенных трассировок и корреляцию span:
* **Системы распределенной трассировки (например, Jaeger, Zipkin, Grafana Tempo)**: Визуализация span, водопады запросов, анализ задержки
* **Полнофункциональные платформы наблюдаемости (например, Honeycomb, Datadog, Grafana Cloud)**: Поиск трассировок и корреляция с метриками и логами
Для организаций, требующих метрик Daily/Weekly/Monthly Active User (DAU/WAU/MAU), рассмотрите бэкенды, поддерживающие эффективные запросы уникальных значений.
Все метрики и события экспортируются со следующими атрибутами ресурса:
* `service.name`: `claude-code`
* `service.version`: Текущая версия Claude Code
* `os.type`: Тип операционной системы (например, `linux`, `darwin`, `windows`)
* `os.version`: Строка версии операционной системы
* `host.arch`: Архитектура хоста (например, `amd64`, `arm64`)
* `wsl.version`: Номер версии WSL (присутствует только при запуске на Windows Subsystem for Linux)
* Имя счетчика: `com.anthropic.claude_code`
Ресурсы для измерения ROI
Для полного руководства по измерению возврата инвестиций для Claude Code, включая настройку телеметрии, анализ затрат, метрики производительности и автоматизированные отчеты, см. [Руководство по измерению ROI Claude Code](https://github.com/anthropics/claude-code-monitoring-guide). Этот репозиторий предоставляет готовые конфигурации Docker Compose, настройки Prometheus и OpenTelemetry, а также шаблоны для создания отчетов о производительности, интегрированные с такими инструментами, как Linear.
Безопасность и конфиденциальность
* Экспорт OpenTelemetry на ваш бэкенд является добровольным и требует явной конфигурации. Информацию об отдельной операционной телеметрии Anthropic и о том, как её отключить, см. в разделе [Data usage](/ru/data-usage#telemetry-services)
* Содержимое файлов в исходном виде и фрагменты кода не включаются в метрики или события. Span трассировок — это отдельный путь данных: см. пункт `OTEL_LOG_TOOL_CONTENT` ниже
* При аутентификации через OAuth `user.email` включается в атрибуты телеметрии. Если это вызывает беспокойство для вашей организации, работайте с вашим бэкендом телеметрии для фильтрации или редактирования этого поля
* Содержимое пользовательской подсказки не собирается по умолчанию. Записывается только длина подсказки. Чтобы включить содержимое подсказки, установите `OTEL_LOG_USER_PROMPTS=1`
* Текст ответа помощника не собирается по умолчанию. Записывается только длина ответа. Чтобы включить текст ответа, установите `OTEL_LOG_ASSISTANT_RESPONSES=1`. Как и все данные OpenTelemetry из Claude Code, текст ответа отправляется только на endpoint OTel, который вы настраиваете, никогда на Anthropic. Когда эта переменная не установлена, `OTEL_LOG_USER_PROMPTS` используется как резервный вариант, поэтому установите `OTEL_LOG_ASSISTANT_RESPONSES=0`, если вы хотите содержимое подсказки без содержимого ответа
* Аргументы входных данных инструмента и параметры не логируются по умолчанию. Чтобы включить их, установите `OTEL_LOG_TOOL_DETAILS=1`. Эти данные отправляются только на endpoint OTEL, который вы настраиваете, никогда на Anthropic. Аргументы могут по-прежнему содержать конфиденциальные значения, поэтому настройте ваш бэкенд телеметрии для фильтрации или редактирования этих атрибутов по мере необходимости. Когда включено:
* События `tool_result` и `tool_decision` включают атрибут `tool_parameters` с командами Bash, именами MCP сервера и инструмента и именами навыков. Поля, такие как `full_command`, выдаются неусеченными
* События `tool_result` дополнительно включают атрибут `tool_input` с путями к файлам, URL-адресами, шаблонами поиска и другими аргументами. Отдельные значения более 512 символов усекаются, и общее количество ограничено примерно 4 K символами
* События `user_prompt` включают буквальное `command_name` для пользовательских, плагин и MCP команд
* Span трассировки включают тот же атрибут `tool_input` и атрибуты, полученные из входных данных, такие как `file_path`, с тем же усечением, что и `tool_input`
* Входные и выходные данные инструмента не логируются в span событиях по умолчанию. Чтобы включить их, установите `OTEL_LOG_TOOL_CONTENT=1`. Когда включено, события span включают полное содержимое входных и выходных данных инструмента, усеченное на 60 КБ на span. Это может включать содержимое исходного файла из результатов инструмента Read и выходные данные команды Bash. Настройте ваш бэкенд телеметрии для фильтрации или редактирования этих атрибутов по мере необходимости
* Тела запроса и ответа Anthropic Messages API в исходном виде не логируются по умолчанию. Чтобы включить их, установите `OTEL_LOG_RAW_API_BODIES`. С `=1` каждый вызов API выдает события логов `api_request_body` и `api_response_body`, чей атрибут `body` является JSON-сериализованной нагрузкой, усеченной на 60 КБ. С `=file:`, неусеченные тела записываются в файлы `.request.json` и `.response.json` в этом каталоге, и события несут путь `body_ref` вместо встроенного тела. Отправьте каталог с коллектором логов или sidecar, а не через поток телеметрии. В обоих режимах тела содержат полную историю разговора (системная подсказка, каждый предыдущий ход пользователя и помощника, результаты инструментов), поэтому включение этого подразумевает согласие со всем, что раскрыли бы другие флаги содержимого `OTEL_LOG_*`. Содержимое расширенного мышления Claude всегда скрыто из этих тел независимо от других параметров
Мониторинг Claude Code на Amazon Bedrock
Для подробного руководства по мониторингу использования Claude Code для Amazon Bedrock см. [Реализация мониторинга Claude Code (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).