SpyBara
Go Premium

monitoring-usage.md 2026-09-28 22:59 UTC to 2026-09-29 21:59 UTC

This page contains 287 additions and 243 deletions.

2026
Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Wed 23 23:57 Fri 25 23:58 Mon 28 22:59 Tue 29 21:59

Мониторинг

Узнайте, как включить и настроить OpenTelemetry для Claude Code.

Отслеживайте использование Claude Code, затраты и активность инструментов в вашей организации, экспортируя данные телеметрии через OpenTelemetry (OTel). Claude Code экспортирует метрики как данные временных рядов через стандартный протокол метрик, события через протокол логов/событий и опционально распределенные трассировки через протокол трассировки.

Быстрый старт

Настройте OpenTelemetry с помощью переменных окружения:

# 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. Для отладки: сократить интервалы экспорта, и сбросить их для использования в production
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 секунд (по умолчанию: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 секунд (по умолчанию: 5000ms)

# 6. Запустить Claude Code
claude

Чтобы проверить настройку, которая экспортирует метрики, проверьте вашу систему на наличие метрики claude_code.session.count, которую Claude Code отправляет при запуске сеанса. Чтобы проверить настройку только логов, отправьте запрос и проверьте событие claude_code.user_prompt.

Если ничего не поступает, запустите Claude Code с помощью claude --debug-file <path> и проверьте журнал, который он записывает в этот путь. Claude Code сообщает об ошибках от настроенных вами экспортеров как об ошибках [3P telemetry], где 3P означает third-party. Строки с префиксом [Anthropic telemetry] описывают отдельную операционную телеметрию Anthropic и не указывают на проблему с вашей настройкой.

Для полного списка параметров конфигурации см. спецификацию OpenTelemetry.

Конфигурация администратора

Администраторы могут настраивать параметры OpenTelemetry для всех пользователей через файл управляемых параметров. Дополнительную информацию о том, как применяются параметры, см. в разделе приоритет параметров.

Пример конфигурации управляемых параметров:

{
  "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"
  }
}

Claude Code игнорирует переменные экспортера OpenTelemetry в файлах .claude/settings.json и .claude/settings.local.json репозитория, поэтому репозиторий не может использовать их для включения телеметрии, выбора места её отправки или захвата содержимого. Установите их в управляемых параметрах или попросите каждого разработчика установить их в своей оболочке или в ~/.claude/settings.json. Репозиторий все ещё может отключить сигнал, установив его селектор экспортера, например OTEL_LOGS_EXPORTER, на none, если только управляемые параметры, файл --settings или окружение, из которого вы запускаете Claude Code, не устанавливают эту переменную.

Claude Code не передает переменные окружения OTEL_* подпроцессам, которые он порождает, включая инструмент Bash, hooks, MCP серверы и языковые серверы. Приложение, инструментированное OpenTelemetry, которое вы запускаете через инструмент Bash, не наследует endpoint экспортера Claude Code или заголовки, поэтому установите эти переменные непосредственно в команде, если это приложение должно экспортировать свою собственную телеметрию.

Как управляемые параметры блокируют назначение OTLP

Когда вы устанавливаете переменную OTEL_EXPORTER_OTLP_* в управляемых параметрах, Claude Code удаляет конфликтующие переменные, установленные разработчиком при запуске, и регистрирует предупреждение в журнале отладки. То, что удаляется, зависит от того, какую переменную вы установили:

  • Endpoints: когда вы устанавливаете OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code удаляет каждый endpoint для конкретного сигнала, установленный разработчиком. Разработчики не могут направить один сигнал на другой сборщик, поэтому вам не нужно также устанавливать переменные endpoint для конкретного сигнала в управляемых параметрах.

  • Протоколы: когда вы устанавливаете OTEL_EXPORTER_OTLP_PROTOCOL, Claude Code удаляет каждый протокол для конкретного сигнала, установленный разработчиком.

  • Учетные данные: когда вы устанавливаете OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY или OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, Claude Code удаляет версии этой переменной для конкретного сигнала, установленные разработчиком, плюс каждую переменную endpoint, установленную разработчиком, общую или для конкретного сигнала, поскольку эти учетные данные в противном случае достигли бы сборщика, который не выбрали управляемые параметры.

  • Селекторы экспортера: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER и бета-версия OTEL_TRACES_EXPORTER следуют обычному приоритету для каждого ключа. Параметр разработчика все еще может отключить сигнал или переключить его на экспортер консоли, поэтому установите селекторы в управляемых параметрах также, если вам нужно их заблокировать. Во всех источниках администратора, OTEL_LOGS_EXPORTER следует единице телеметрии, в то время как два других селектора объединяются для каждого ключа. Требуется Claude Code v2.1.223 или позже.

  • Бета-версия endpoints трассировки: с активной детальной бета-версией трассировки, Claude Code экспортирует логи и трассировки в BETA_TRACING_ENDPOINT вместо использования экспортеров логов и трассировок. Claude Code поэтому удаляет установленный разработчиком BETA_TRACING_ENDPOINT всякий раз, когда любой из этих управляемых параметров определяет назначение любого из этих сигналов:

    • Общий endpoint или endpoint логов/трассировок или учетные данные
    • otelHeadersHelper
    • Селектор экспортера логов или трассировок, установленный на none, console или пустой, значения, которые держат сигнал вне сборщика
    • CLAUDE_CODE_ENABLE_TELEMETRY отключен

    Endpoint или учетные данные только для метрик его не удаляют. До v2.1.251, установленный разработчиком BETA_TRACING_ENDPOINT перенаправлял логи и трассировки, которые экспортирует детальная бета-версия трассировки, даже когда управляемые параметры закрепили сборщик.

Claude Code не удаляет переменные для конкретного сигнала, которые вы устанавливаете в самих управляемых параметрах, поэтому вы можете направить один сигнал на другой сборщик, установив его переменную там, как это делает пример SIEM. Если вы установите там учетные данные для конкретного сигнала, Claude Code удалит установленный разработчиком endpoint для этого сигнала.

Это поведение удаления изменяет то, где доставляется телеметрия, а не то, что собирает Claude Code.

До v2.1.217, каждая переменная независимо следовала приоритету параметров для каждого ключа, поэтому endpoint для конкретного сигнала, установленный в параметрах пользователя или оболочке, перенаправлял этот сигнал от управляемого сборщика.

Когда приложение для рабочего стола или запускатель самостоятельно размещаемой среды запускает Claude Code и называет endpoint OTLP в среде, которую он предоставляет, Claude Code закрепляет назначение таким же образом: переменные телеметрии запускателя удаляют переменные, установленные разработчиком, точно так же, как это делают управляемые параметры. Claude Code не удаляет переменные, которые сам установил запускатель. Требуется Claude Code v2.1.251 или позже.

Детали конфигурации

Общие переменные конфигурации

Эти переменные настраивают экспортеры, конечные точки и поведение экспорта для всех развертываний.

Если вы установите переменную конечной точки или протокола для конкретного сигнала, такую как OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, Claude Code использует её вместо универсальной переменной для этого сигнала. Если вы установите переменную заголовков для конкретного сигнала, такую как OTEL_EXPORTER_OTLP_METRICS_HEADERS, Claude Code объединяет её с универсальной переменной OTEL_EXPORTER_OTLP_HEADERS для этого сигнала.

На машинах с управляемыми параметрами см. Как управляемые параметры блокируют назначение OTLP, чтобы узнать, что 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, применяется ко всем сигналам. Claude Code не имеет протокола по умолчанию, поэтому установите эту переменную или переменную протокола для конкретного сигнала для каждого включённого экспортера otlp grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT Конечная точка сборщика OTLP для всех сигналов http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL Протокол для метрик, переопределяет общий параметр grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT Конечная точка метрик OTLP, переопределяет общий параметр http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL Протокол для логов, переопределяет общий параметр grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT Конечная точка логов OTLP, переопределяет общий параметр http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERS Заголовки аутентификации для OTLP Authorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_HEADERS Заголовки аутентификации для метрик, объединяются с общими заголовками Authorization=Bearer token
OTEL_EXPORTER_OTLP_LOGS_HEADERS Заголовки аутентификации для логов, объединяются с общими заголовками 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. Требует Claude Code v2.1.193 или позже 1 для включения, 0 для сохранения скрытым
OTEL_LOG_TOOL_DETAILS Включить логирование параметров инструмента и входных аргументов в событиях инструмента и атрибутах span трассировки: команды Bash, имена серверов MCP и инструментов, имена skills, имена пользовательских рабочих процессов и входные данные инструмента. Также включает имена пользовательских, plugin и MCP команд на событиях user_prompt и реальные имена агентов, skills, plugins и серверов MCP и инструментов на счётчиках стоимости и токенов (по умолчанию: отключено). Для встроенных серверов Claude Desktop в сеансах, которыми владеет Claude Desktop, mcp_server_name/mcp_tool_name выдаются на tool_decision/tool_result даже с отключённым флагом. Исключение требует Claude Code v2.1.214 или позже 1 для включения
OTEL_LOG_TOOL_CONTENT Включить логирование содержимого инструмента в событии span tool.output (по умолчанию: отключено). Атрибуты span переносят содержимое инструмента под их собственные шлюзы. Требует трассировку. Содержимое усекается на лимите содержимого (60 КБ по умолчанию) 1 для включения
OTEL_LOG_MANAGED_SETTINGS Добавить скрытые управляемые параметры и дайджест SHA-256 параметров перед скрытием на события managed settings resolved (по умолчанию: отключено). Значение в параметрах проекта или локальных параметрах не включает его. Требует Claude Code v2.1.274 или позже 1 для включения
OTEL_LOG_RAW_API_BODIES Выдать полный запрос и ответ JSON API Anthropic Messages как события логов api_request_body / api_response_body (по умолчанию: отключено). Тела включают всю историю разговора. Включение этого подразумевает согласие на всё, что раскрыли бы OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS и OTEL_LOG_TOOL_CONTENT 1 для встроенных тел, усечённых на лимите содержимого (60 КБ по умолчанию), или file:<dir> для неусечённых тел на диске с указателем body_ref в событии
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH Лимит содержимого: максимальная длина атрибутов, содержащих содержимое, таких как ответы модели, содержимое инструмента, системные подсказки и тела сырого API, включая маркер усечения, в единицах кода UTF-16 (по умолчанию: 61440, т.е. 60 КБ). По умолчанию размер рассчитан для бэкендов, которые ограничивают значения атрибутов на 64 КБ; увеличивайте его только если ваш бэкенд принимает большие значения, или уменьшайте, чтобы сократить объём телеметрии. Когда лимит атрибута OpenTelemetry SDK, OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT или один из его вариантов logrecord и span, установлен ниже, Claude Code усекает на этом меньшем значении, чтобы маркер [TRUNCATED ...] оставался в пределах лимита SDK. Требует Claude Code v2.1.214 или позже 262144
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE Предпочтение временности метрик (по умолчанию: delta). Установите на cumulative, если ваш бэкенд ожидает кумулятивную временность delta, cumulative
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS Интервал обновления динамических заголовков (по умолчанию: 1740000ms / 29 минут) 900000

Для протоколов http/protobuf и http/json Claude Code отправляет каждый запрос экспорта с заголовком Content-Length. До v2.1.212 версии Claude Code от v2.1.191 и позже отправляли эти запросы с кодированием передачи по частям; Azure Monitor и другие конечные точки, требующие объявленной длины, отклоняли их с ошибками 411 Length Required или 400.

Аутентификация 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. См. Конфигурация сети 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 OpenTelemetry SDK читает стандартные переменные OTLP напрямую, поэтому существующие конфигурации, которые устанавливают переменные метрик для конкретного сигнала, продолжают работать. На машинах с управляемыми параметрами Claude Code может удалить установленные разработчиком учётные данные и конечные точки для конкретного сигнала при запуске.

Контроль кардинальности метрик

Следующие переменные окружения контролируют, какие атрибуты включены в метрики для управления кардинальностью:

Переменная окружения Описание Значение по умолчанию Пример для отключения
OTEL_METRICS_INCLUDE_SESSION_ID Включить атрибуты session.id и, в облачных сеансах, ccr.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
OTEL_METRICS_INCLUDE_REPOSITORY Включить атрибуты идентификации репозитория vcs.* repository identity attributes на метрики и события. Требует Claude Code v2.1.269 или позже false true

Более низкая кардинальность обычно означает лучшую производительность и более низкие затраты на хранилище, но менее детальные данные для анализа.

Traces (beta)

Распределённая трассировка экспортирует spans, которые связывают каждую пользовательскую подсказку с запросами API и выполнениями инструментов, которые она запускает, поэтому вы можете просмотреть полный запрос как одну трассировку в вашем бэкенде трассировки.

Трассировка отключена по умолчанию. Чтобы включить её, установите оба CLAUDE_CODE_ENABLE_TELEMETRY=1 и CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, затем установите OTEL_TRACES_EXPORTER, чтобы выбрать, куда отправляются spans. Трассировки повторно используют общую конфигурацию OTLP для конечной точки, протокола, заголовков и mTLS. На машинах с управляемыми параметрами Claude Code может удалить установленные разработчиком учётные данные и конечные точки для конкретного сигнала при запуске.

Переменная окружения Описание Примеры значений
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, переопределяет OTEL_EXPORTER_OTLP_ENDPOINT http://localhost:4318/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS Заголовки аутентификации для трассировок, объединяются с OTEL_EXPORTER_OTLP_HEADERS Authorization=Bearer token
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 или контейнерных сред.

Входящий контекст трассировки также применяется к событиям. В сеансах Agent SDK и -p с установленным TRACEPARENT каждая запись логов OTLP события содержит значения trace_id и span_id, которые присоединяют её к трассировке вашего приложения, даже когда экспортер трассировок не настроен, поэтому ваш бэкенд логирования может коррелировать события с остальной частью трассировки.

Запись, выданная во время активного взаимодействия, содержит ID span взаимодействия, даже когда Claude Code выдаёт её вне асинхронного контекста span, такого как обратный вызов подсказки разрешения или для записи, буферизованной при запуске и экспортированной позже. Запись, выданная без активного span взаимодействия, содержит ID входящего TRACEPARENT напрямую. До v2.1.214 записи, выданные вне асинхронного контекста span, содержали ID входящего TRACEPARENT вместо ID span. До v2.1.212 записи событий, выданные вне активного span, не содержали trace_id или span_id.

Иерархия span

Каждая пользовательская подсказка запускает корневой span claude_code.interaction. Вызовы API, вызовы инструментов и выполнения hooks записываются как его дочерние элементы. Spans инструментов имеют два собственных дочерних span: один для времени, потраченного на ожидание решения разрешения, и один для самого выполнения. Когда инструмент Agent или устаревший инструмент Task порождает подагента, spans API и инструментов подагента вложены под span claude_code.tool родителя.

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 установлен в окружении.

Когда hook PreToolUse откладывает вызов инструмента, Claude Code сохраняет контекст трассировки хода, который отложил его. Когда вы возобновляете сеанс и инструмент повторно запускается, spans инструмента присоединяются к трассировке этого более раннего хода как дочерние элементы span claude_code.interaction хода.

Атрибуты span

Каждый span содержит стандартные атрибуты плюс атрибут span.type, соответствующий его имени. Таблицы ниже перечисляют дополнительные атрибуты, установленные на каждом span. Spans llm_request, tool.execution и hook устанавливают статус OpenTelemetry ERROR, когда они записывают сбой; другие spans всегда заканчиваются со статусом UNSET.

claude_code.interaction

Атрибут Описание Контролируется
user_prompt Текст подсказки. Значение <REDACTED> если шлюз не установлен OTEL_LOG_USER_PROMPTS
user_prompt_length Длина подсказки в символах
interaction.sequence Счётчик взаимодействий на основе 1, считаемый за процесс Claude Code, а не за сеанс, как описано для event.sequence
parent.source Как span получил своего родителя трассировки: env когда он был родителем под входящим TRACEPARENT, none когда он запустил свою собственную трассировку. Требует Claude Code v2.1.268 или позже
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 или имя подагента ENABLE_BETA_TRACING_DETAILED
query_source_safe Ограниченная форма query_source, выданная независимо от того, активна ли детальная бета-трассировка, со значениями такими как repl_main_thread или agent.builtin.general-purpose. : становится . и агенты с пользовательскими именами появляются как agent.custom. Требует Claude Code v2.1.268 или позже
agent_id Идентификатор подагента или товарища, который выдал запрос. Отсутствует в основном сеансе
parent_agent_id Идентификатор агента, который породил этот. Отсутствует для основного сеанса и для агентов, порождённых непосредственно из него
workflow.run_id Идентификатор запуска Workflow запуска инструмента, который породил этого агента, с префиксом wf_. Отсутствует для агентов, не порождённых рабочим процессом
workflow.name Имя рабочего процесса, который породил этого агента. Имена, созданные пользователем, заменяются на custom, если шлюз не установлен OTEL_LOG_TOOL_DETAILS
speed fast или normal
effort Уровень усилий, применённый к запросу: low, medium, high, xhigh или max. Отсутствует, когда Claude Code не отправляет уровень усилий, например на модели, которая не поддерживает усилия. Требует Claude Code v2.1.274 или позже
llm_request.context interaction, tool или standalone в зависимости от родительского span
duration_ms Длительность по настенным часам, включая повторные попытки
ttft_ms Время до первого токена в миллисекундах
first_content_ms Время от начала запроса до первого блока содержимого успешной попытки в миллисекундах. Отсутствует на запросах, которые вернулись к пути без потоковой передачи. Требует Claude Code v2.1.268 или позже
input_tokens Количество входных токенов из блока использования API
output_tokens Количество выходных токенов
cache_read_tokens Токены, прочитанные из кэша подсказок
cache_creation_tokens Токены, записанные в кэш подсказок
request_id ID запроса API. Одно и то же значение как атрибут корреляции события request_id event correlation attribute
gen_ai.response.id Одно и то же значение как request_id. Семантическое соглашение OpenTelemetry GenAI
client_request_id Сгенерированный клиентом x-client-request-id последней попытки
attempt Всего попыток для этого запроса
success true или false
status_code HTTP код состояния, когда запрос не удался
error Сообщение об ошибке, когда запрос не удался
error_class Короткий токен класса ошибки, когда запрос не удался, такой как api_timeout или server_overload. Требует Claude Code v2.1.268 или позже
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 Имя инструмента
tool_name_safe Форма tool_name, которая не содержит имён, выбранных пользователем. Встроенные имена инструментов проходят дословно. Имена инструментов MCP появляются как mcp_other, за исключением имён инструментов, соответствующих нескольким фиксированным формам, таких как инструменты playwright с именами browser_*, которые проходят дословно. Требует Claude Code v2.1.268 или позже
bash_command_class Для инструмента Bash: категория первой программы команды из фиксированного списка, такая как vcs или package_manager. other для программы вне списка, unparsed когда строка не может быть разобрана. Требует Claude Code v2.1.268 или позже
bash_argv0 Для инструмента Bash: первая программа команды, когда она находится в одном и том же фиксированном списке, такая как git или npm. other для любой программы вне списка. Требует Claude Code v2.1.268 или позже
duration_ms Длительность по настенным часам, включая ожидание разрешения и выполнение
result_tokens Приблизительный размер токена результата инструмента
agent_id Идентификатор подагента или товарища, который запустил инструмент. Отсутствует в основном сеансе
parent_agent_id Идентификатор агента, который породил этот. Отсутствует для основного сеанса и для агентов, порождённых непосредственно из него
workflow.run_id Идентификатор запуска инструмента Workflow, который породил этого агента, с префиксом wf_. Отсутствует для агентов, не порождённых рабочим процессом
workflow.name Имя рабочего процесса, который породил этого агента. Имена, созданные пользователем, заменяются на custom, если шлюз не установлен OTEL_LOG_TOOL_DETAILS
tool_use_id ID блока tool_use модели для этого вызова. Совпадает с tool_use_id на событиях tool_result и tool_decision и в полезных нагрузках hooks, поэтому вы можете присоединить 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 для инструмента Skill OTEL_LOG_TOOL_DETAILS
subagent_type Тип подагента для инструмента Agent или устаревшего инструмента Task OTEL_LOG_TOOL_DETAILS

Событие span tool.output на claude_code.tool

Если вы установите OTEL_LOG_TOOL_CONTENT=1, вызовы Read и Bash могут записать событие span tool.output на span claude_code.tool. Вызовы Edit и Write записывают его только когда вы также установите OTEL_LOG_TOOL_DETAILS=1. Эта переменная не ограничена этими двумя инструментами, поэтому проверьте её строку в таблице конфигурации для аргументов, которые она добавляет в другом месте.

Инструменты MCP, WebFetch и WebSearch также записывают это событие на Claude Code v2.1.283 или позже.

Claude Code записывает это событие из успешного возврата вызова инструмента, поэтому вызов, который вызывает ошибку, ничего не записывает, независимо от инструмента. Среди вызовов, которые действительно возвращаются, он не записывает событие tool.output для:

  • Вызова любого инструмента, отличного от Read, Edit, Write, Bash, WebFetch, WebSearch и инструментов MCP
  • Read, который возвращает что-либо, отличное от текста файла, такое как изображение, PDF или повторное чтение файла, содержимое которого не изменилось
  • Вызова Edit или Write, если вы также не установите OTEL_LOG_TOOL_DETAILS=1
  • Вызова WebFetch или WebSearch, который Claude Code переместил в фоновый режим, потому что вы прервали ход, чтобы отправить ваши поставленные в очередь сообщения прямо сейчас, пока вызов выполнялся. Claude получает этот результат позже, после того как span инструмента закончился

Событие содержит эти атрибуты, каждый усечённый на лимите содержимого (60 КБ по умолчанию). Контролируется называет переменную, которая нужна атрибуту в дополнение к OTEL_LOG_TOOL_CONTENT=1, и для Edit и Write эта переменная контролирует само событие, а не атрибут.

Атрибут Описание Контролируется
content Текст, который вернул инструмент Read, или текст, который вызов Write был попрошен написать OTEL_LOG_TOOL_DETAILS для инструмента Write
output Для инструмента Bash, объединённый вывод команды, с stderr чередующимся в stdout. Для инструмента MCP, WebFetch или WebSearch, результат, который вернул инструмент: текстовые блоки, объединённые новыми строками, с изображением или документом, заменённым на заполнитель, такой как [image]
diff Структурированный патч, который применил инструмент Edit OTEL_LOG_TOOL_DETAILS
file_path Целевой путь файла для инструментов Read, Edit и Write, повторяющий атрибут span с тем же именем OTEL_LOG_TOOL_DETAILS
bash_command Строка команды для инструмента Bash OTEL_LOG_TOOL_DETAILS

Атрибут tool_name родительского span говорит вам, из какого инструмента пришло событие. Атрибут, усечённый на лимите содержимого, сопровождается <attribute>_truncated и <attribute>_original_length.

claude_code.tool.blocked_on_user

Атрибут Описание Контролируется
duration_ms Время, потраченное на ожидание решения разрешения
decision accept или reject
source Источник решения, соответствующий событию Tool decision

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. Содержит полное сообщение об ошибке вместо этого, когда шлюз установлен OTEL_LOG_TOOL_DETAILS
error_class Категория ошибки в форме идентификатора, с символами вне букв, цифр и подчёркиваний, заменённых на _, такой как Error_ENOENT или ShellError. Содержит категорию даже когда error содержит полное сообщение. Требует Claude Code v2.1.268 или позже

claude_code.hook

Этот span появляется только когда активна детальная бета-трассировка, которая требует ENABLE_BETA_TRACING_DETAILED=1 и BETA_TRACING_ENDPOINT, пару, которая также изменяет, куда идут ваши логи и трассировки. Установите пару в вашей оболочке, пользовательских параметрах или управляемых параметрах; обе переменные игнорируются в параметрах проекта и локальных параметрах. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA один не производит его.

В интерактивных сеансах CLI детальная бета-трассировка также требует, чтобы ваша организация была в списке разрешений для функции. Сеансы Agent SDK и неинтерактивные сеансы -p не требуют списка разрешений.

Атрибут Описание Контролируется
hook_event Тип события hook, такой как PreToolUse
hook_name Полное имя hook, такое как PreToolUse:Write
num_hooks Количество выполненных команд hook, соответствующих условиям
hook_definitions Конфигурация hook, сериализованная в JSON OTEL_LOG_TOOL_DETAILS
duration_ms Длительность по настенным часам всех соответствующих hooks
num_success Количество hooks, которые завершились успешно
num_blocking Количество hooks, которые вернули решение блокировки
num_non_blocking_error Количество hooks, которые не удались без блокировки
num_cancelled Количество hooks, отменённых перед завершением

Динамические заголовки

Для корпоративных сред, требующих динамической аутентификации, вы можете настроить скрипт для динамического создания заголовков. Динамические заголовки применяются только к протоколам http/protobuf и http/json. С протоколом grpc Claude Code использует только переменные статических заголовков, OTEL_EXPORTER_OTLP_HEADERS и его варианты для конкретного сигнала.

Конфигурация параметров

Добавьте в ваш .claude/settings.json, заменив путь на ваш собственный скрипт:

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

Значение может быть путём к исполняемому файлу, включая путь, содержащий пробелы, или строкой команды оболочки с аргументами. На Windows значение всегда запускается через оболочку, поэтому заключите путь, содержащий пробелы, в кавычки внутри значения JSON.

Требования к скрипту

Скрипт должен выводить действительный JSON с парами ключ-значение строк, представляющими заголовки HTTP:

#!/bin/bash
# Пример: несколько заголовков
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Если помощник не удаётся или выводит вывод, который не соответствует этим требованиям, экспорты не удаются и ваш бэкенд телеметрии не получает ничего из сеанса, пока помощник снова не заработает. Claude Code сообщает об ошибке в:

  • Уведомление предупреждения в интерактивных сеансах, otelHeadersHelper failed; telemetry is not being exported, показано один раз за сеанс, когда помощник впервые не удаётся
  • Вывод /status
  • Журнал отладки, при запуске с --debug или после запуска /debug в сеансе
  • stderr, в неинтерактивных сеансах, запущенных с -p

Поведение обновления

Скрипт помощника заголовков запускается при запуске и периодически после этого для поддержки обновления токена. По умолчанию скрипт запускается каждые 29 минут. Настройте интервал с переменной окружения CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS.

Поддержка организаций с несколькими командами

Организации с несколькими командами или отделами могут добавлять пользовательские атрибуты для различия между разными группами, используя переменную окружения OTEL_RESOURCE_ATTRIBUTES:

# Добавить пользовательские атрибуты для идентификации команды
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Эти пользовательские атрибуты включены во все метрики и события, позволяя вам:

  • Фильтровать метрики по команде или отделу
  • Отслеживать затраты по центру затрат
  • Создавать панели мониторинга для конкретных команд
  • Настраивать оповещения для конкретных команд

Claude Code присоединяет эти значения как атрибуты на каждой точке данных метрики и записи события, в дополнение к отправке их в блоке ресурсов OTLP. Поскольку большинство бэкендов метрик предоставляют атрибуты точек данных как запрашиваемые метки, вы можете группировать и фильтровать метрики по вашим пользовательским ключам напрямую. За исключением атрибутов репозитория vcs.* repository attributes, пользовательские ключи никогда не переопределяют стандартные атрибуты, такие как user.id или session.id: когда ключ конфликтует, Claude Code сохраняет встроенное значение.

Каждый пользовательский ключ становится меткой на каждой серии метрик, поэтому значения высокой кардинальности увеличивают затраты на хранилище в вашем бэкенде метрик. Чтобы отправлять пользовательские атрибуты только в блоке ресурсов и опускать их из меток точек данных, установите OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false. См. Контроль кардинальности метрик.

Примеры конфигураций

Установите эти переменные окружения перед запуском claude. Каждый сценарий ниже показывает полную конфигурацию, и каждая переменная описана в разделе Общие переменные конфигурации. Чтобы подтвердить, что конфигурация вступила в силу, проверьте ваш бэкенд на наличие метрики claude_code.session.count после запуска сеанса; Быстрый старт охватывает проверку только логов и что проверить, когда ничего не приходит.

Для отладки консоли с интервалом экспорта 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, скрепленного с http://localhost:9464/metrics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

В самостоятельно размещённой среде сеанс привязывает порт 9464 только при мощности по умолчанию в один. При более высокой мощности бегун повторно выставляет счётчики и датчики сеанса на своей собственной конечной точке /metrics вместо этого.

Для отправки метрик нескольким экспортерам:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

Для отправки метрик и логов на разные конечные точки или бэкенды:

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

Телеметрия из облачных сеансов и Claude Tag

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

Чтобы экспортировать телеметрию из этих сеансов, установите CLAUDE_CODE_ENABLE_TELEMETRY и переменные OTEL_*, используя те же ключи, что и в примере конфигурации администратора, в одном из двух мест:

  • Параметры, управляемые сервером: добавьте их в блок env параметров, управляемых сервером вашей организации. Claude Code получает эти параметры при запуске везде, где применяются параметры, управляемые сервером, что включает машины ваших пользователей и облачные сеансы, кроме сеансов канала Claude Tag. Сеансы Claude Tag не получают ваши параметры, управляемые сервером, поэтому этот способ их не настраивает.
  • Переменные окружения: добавьте их в переменные окружения облачного окружения, чтобы настроить только сеансы, работающие в этом окружении. Это способ, который достигает сеансов Claude Tag.

Любой, кто использует окружение, может читать его переменные, поэтому не помещайте туда учётные данные, такие как токен сборщика в OTEL_EXPORTER_OTLP_HEADERS. Учётные данные API в окружении тоже не помогут, потому что собственный экспорт телеметрии Claude Code — это один из запросов, которые никогда не получают учётные данные. Если ваш сборщик требует учётные данные, настройте весь экспорт через параметры, управляемые сервером, вместо этого, потому что когда вы устанавливаете учётные данные там, Claude Code удаляет переменные конечной точки, установленные вне управляемых параметров.

Помните об этих ограничениях при настройке телеметрии для облачных сеансов:

  • Позвольте сеансам достичь сборщика: Claude Code отправляет экспорт через сеть сеанса, поэтому достигнет ли он хоста в вашем OTEL_EXPORTER_OTLP_ENDPOINT, зависит от уровня сетевого доступа окружения. Если сеансы не могут достичь домена сборщика на выбранном вами уровне, добавьте домен в список разрешений окружения, потому что ни один параметр, управляемый сервером, не добавляет домены в список разрешений сети окружения.
  • Каналы Claude Tag используют окружения уровня организации: сеансы канала работают в окружениях уровня организации, а не в личных окружениях членов, поэтому внесите изменения в список разрешений и любые переменные окружения в общем окружении, установленном как стандартное для вашей организации или закреплённом на канале.
  • Cowork настраивается отдельно: сеансы Cowork не получают параметры, управляемые сервером, как показывает таблица охвата поверхности, поэтому блок env, управляемый сервером, не настраивает их телеметрию.

Атрибутирование телеметрии облачным сеансам

По умолчанию метрики и события из облачного сеанса содержат стандартные атрибуты, включая session.id, ccr.session.id и organization.id, поэтому вы можете фильтровать по сеансу или организации без дополнительной настройки. Значение ccr.session.id — это CLAUDE_CODE_REMOTE_SESSION_ID сеанса. Чтобы преобразовать его в URL транскрипта сеанса, см. Связать вывод обратно с сеансом.

Чтобы атрибутировать телеметрию более подробно, используйте эти параметры:

  • Определить сеансы Claude Tag: установите OTEL_METRICS_INCLUDE_ENTRYPOINT=true, как описано в разделе Контроль кардинальности метрик. Метрики затем содержат app.entrypoint, значение которого — claude-in-slack для сеансов Claude Tag.
  • Добавить пользовательские атрибуты: установите OTEL_RESOURCE_ATTRIBUTES в том же месте, где вы устанавливаете другие переменные OTEL_* для этих сеансов. Если вы export его в скрипте настройки окружения вместо этого, значение не достигает Claude Code: скрипт настройки — это отдельный скрипт Bash, который запускается перед запуском Claude Code, и переменные, которые он экспортирует, заканчиваются с ним.

В сеансах канала Claude Tag Claude работает как общая идентичность вашей организации, а не как какой-либо член, поэтому не полагайтесь на атрибуты user.* для определения того, кто отметил Claude.

Доступные метрики и события

Стандартные атрибуты

Все метрики и события имеют эти стандартные атрибуты:

Атрибут Описание Управляется
session.id Уникальный идентификатор сеанса OTEL_METRICS_INCLUDE_SESSION_ID (по умолчанию: true)
ccr.session.id Идентификатор облачного сеанса, значение CLAUDE_CODE_REMOTE_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 или claude-in-slack для сеансов Claude Tag 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 Адрес электронной почты пользователя, из вашего входа или, в облачном сеансе, из учётных данных самого сеанса Всегда включается, если доступно
terminal.type Тип терминала, например iTerm.app, vscode, cursor или tmux Всегда включается при обнаружении
Ключи из OTEL_RESOURCE_ATTRIBUTES Пользовательские атрибуты, которые вы устанавливаете, например department или team.id. См. Поддержка многокомандной организации OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES (по умолчанию: true)
vcs.repository.url.full, vcs.owner.name, vcs.repository.name, vcs.provider.name Идентификатор репозитория сеанса, полученный из его удалённого хранилища origin. См. Атрибуты репозитория OTEL_METRICS_INCLUDE_REPOSITORY (по умолчанию: false). Требуется Claude Code v2.1.269 или позже

Когда Claude Code подписан на шлюз приложений Claude, CLI помечает экспорты аутентифицированной идентификацией из сеанса шлюза: user.id — это субъект IdP, а не анонимный идентификатор установки, user.email — это адрес электронной почты входа, и user.groups содержит членство в группе IdP в виде строки, разделённой запятыми. Каждый экспорт также содержит identity.source: gateway-oidc. Идентификация шлюза применяется последней, поэтому ключи user.* и identity.*, установленные через OTEL_RESOURCE_ATTRIBUTES, игнорируются в сеансах шлюза.

События дополнительно включают следующие атрибуты. Они никогда не прикрепляются к метрикам, так как это вызовет неограниченную кардинальность:

  • prompt.id: UUID, коррелирующий пользовательский запрос со всеми последующими событиями до следующего запроса. См. Атрибуты корреляции событий.
  • workspace.host_paths: каталоги рабочей области хоста, выбранные в приложении для рабочего стола, как массив строк
  • workflow.run_id: идентификатор запуска, с префиксом wf_, в API и событиях инструментов, выпущенных агентами, которые принадлежат запуску инструмента Workflow. Фильтрация событий по одному workflow.run_id восстанавливает запросы API и результаты инструментов этого запуска. Идентификатор охватывает агентов, которых порождает скрипт рабочего процесса, и любых агентов, которых они порождают в свою очередь, например вызовы навыков. Он совпадает с идентификатором запуска, указанным в результате инструмента Workflow. Отсутствует во всех остальных событиях. Требуется Claude Code v2.1.202 или позже
  • workflow.name: имя рабочего процесса, meta.name его скрипта, выпущенное вместе с workflow.run_id. Встроенные имена рабочих процессов отображаются как есть при выполнении немодифицированного встроенного скрипта. Имена, созданные пользователем, включая отредактированные копии встроенных скриптов, заменяются на custom, если не установлен OTEL_LOG_TOOL_DETAILS=1. Требуется Claude Code v2.1.202 или позже

Атрибуты репозитория

Установите OTEL_METRICS_INCLUDE_REPOSITORY=true, чтобы помечать метрики и события идентификацией репозитория сеанса, чтобы общий сборщик мог атрибутировать использование по репозиторию. Требуется Claude Code v2.1.269 или позже.

Claude Code получает эти атрибуты один раз за сеанс из удалённого хранилища origin репозитория. Когда удалённые хранилища HTTPS и SSH репозитория называют один и тот же хост и один и тот же путь, как это происходит на GitHub, GitLab и Bitbucket Cloud, оба производят идентичные значения:

Атрибут Значение
vcs.repository.url.full URL браузера репозитория без .git, например https://github.com/example-org/example-repo
vcs.owner.name Путь владельца или группы, например example-org; опускается, когда путь удалённого хранилища имеет один сегмент
vcs.repository.name Простое имя репозитория, например example-repo
vcs.provider.name github, gitlab, bitbucket или gitea, когда Claude Code распознаёт хост удалённого хранилища или форму URL как один из этих поставщиков; опускается в противном случае

Значения приводятся в нижний регистр, и учётные данные, строки запроса и фрагменты из URL удалённого хранилища никогда не отображаются в них. Атрибуты опускаются, когда сеанс не имеет удалённого хранилища origin, когда удалённое хранилище не имеет формы URL или когда единственный охватывающий репозиторий — это ваш домашний каталог.

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

Ключ vcs.*, который вы объявляете в OTEL_RESOURCE_ATTRIBUTES, заменяет полученное значение для этого ключа. Если вы объявляете vcs.repository.url.full, Claude Code никогда не читает удалённое хранилище и сообщает только объявленные вами ключи.

Если клоны HTTPS и SSH одного репозитория сообщают разные значения, например на самостоятельно размещённой установке, где URL клона HTTPS содержит префикс пути, которого не хватает URL SSH, объявите vcs.repository.url.full в OTEL_RESOURCE_ATTRIBUTES вместе со всеми остальными ключами vcs.*, которые вы хотите сообщить. Каждый клон затем сообщает идентификацию, которую вы объявляете.

Атрибуты передаются только вашим собственным экспортёрам; телеметрия Anthropic отбрасывает каждый ключ vcs.*.

Метрики

Claude Code экспортирует следующие метрики. Столбец Unit показывает строку единицы OpenTelemetry, прикреплённую к каждой метрике; метрики подсчёта не имеют никаких.

Имя метрики Описание Единица
claude_code.session.count Количество запущенных сеансов CLI нет
claude_code.lines_of_code.count Количество изменённых строк кода нет
claude_code.pull_request.count Количество созданных запросов на слияние нет
claude_code.commit.count Количество созданных коммитов git нет
claude_code.cost.usage Стоимость сеанса Claude Code USD
claude_code.token.usage Количество использованных токенов tokens
claude_code.code_edit_tool.decision Количество решений о разрешении инструмента редактирования кода нет
claude_code.active_time.total Общее активное время s

Когда prometheus — единственный экспортёр, указанный в OTEL_METRICS_EXPORTER, Claude Code опускает единицы USD, tokens и s из экспортированных метрик, чтобы скрейп оставался в действительном формате текста Prometheus. Имена метрик не меняются, и конфигурации, которые объединяют экспортёры, такие как otlp,prometheus, сохраняют единицы. До v2.1.216 скрейп Prometheus включал строки # UNIT, специфичные для OpenMetrics, которые некоторые скрейперы отклоняли.

Детали метрик

Каждая метрика включает стандартные атрибуты, перечисленные выше. Метрики с дополнительными контекстно-специфичными атрибутами отмечены ниже.

Счётчик сеансов

Увеличивается в начале каждого сеанса.

Атрибуты:

  • Все стандартные атрибуты
  • start_type: Как был запущен сеанс. Один из "fresh", "resume", "continue" или "agents_view". Значение "agents_view" идентифицирует процесс панели управления claude agents, локальный пользовательский интерфейс, а не разговорный сеанс. Фильтруйте по этому значению, чтобы отделить запуски процесса пользовательского интерфейса от разговорных сеансов в ваших панелях управления.

Счётчик строк кода

Увеличивается при добавлении или удалении кода.

Атрибуты:

  • Все стандартные атрибуты
  • type: ("added", "removed")
  • model: Идентификатор модели для модели, которая внесла изменение (например, "claude-sonnet-5")

Счётчик запросов на слияние

Увеличивается, когда Claude Code создаёт запрос на слияние или запрос на объединение через команду оболочки или инструмент MCP.

Атрибуты:

Счётчик коммитов

Увеличивается при создании коммитов git через Claude Code.

Атрибуты:

Счётчик стоимости

Увеличивается после каждого запроса API.

Атрибуты agent.name, skill.name, plugin.name, mcp_server.name и mcp_tool.name по умолчанию скрывают некоторые имена в заполнитель "custom" или "third-party". Если вы установите OTEL_LOG_TOOL_DETAILS=1, они вместо этого содержат реальные имена. До v2.1.273 счётчики стоимости и токенов и события api_request, api_error и api_refusal содержали скрытые значения даже с установленным OTEL_LOG_TOOL_DETAILS=1.

Атрибуты:

  • Все стандартные атрибуты
  • model: Идентификатор модели (например, "claude-sonnet-5")
  • query_source: Категория подсистемы, которая выдала запрос. Один из "main", "subagent" или "auxiliary"
  • speed: "fast", когда запрос использовал быстрый режим. Отсутствует в противном случае
  • effort: Уровень усилий, применённый к запросу: "low", "medium", "high", "xhigh" или "max". Отсутствует, когда Claude Code не отправляет уровень усилий, например на модели, которая не поддерживает усилия.
  • agent.name: Тип подагента, который выдал запрос. Встроенные имена агентов и агенты из официальных плагинов маркетплейса отображаются как есть. Другие определённые пользователем имена агентов заменяются на "custom". Отсутствует, когда запрос не был выдан именованным типом подагента.
  • skill.name: Навык, активный для запроса, установленный инструментом Skill или командой /, или унаследованный порождённым подагентом. Встроенные, связанные, определённые пользователем и официальные имена навыков маркетплейса отображаются как есть. Имена навыков плагинов третьих сторон заменяются на "third-party". Отсутствует, когда нет активного навыка.
  • plugin.name: Владеющий плагин, когда активный навык или подагент предоставляется плагином. Имена официальных плагинов маркетплейса отображаются как есть. Имена плагинов третьих сторон заменяются на "third-party". Отсутствует, когда ни навык, ни подагент не имеют владеющего плагина.
  • marketplace.name: Маркетплейс, из которого был установлен владеющий плагин. Выпускается только для официальных плагинов маркетплейса, даже с установленным OTEL_LOG_TOOL_DETAILS=1. Отсутствует в противном случае.
  • mcp_server.name: Сервер MCP, результат инструмента которого использовал этот запрос. Встроенные, проксированные claude.ai и официальные имена серверов реестра отображаются как есть. Имена серверов, настроенные пользователем, заменяются на "custom". Отсутствует, когда запрос не использовал результат инструмента MCP. До v2.1.222 Claude Code устанавливал этот атрибут на каждый запрос после вызова инструмента MCP, а не только на запросы, которые использовали результат инструмента, поэтому панели управления, которые его агрегируют, показывают снижение после обновления.
  • mcp_tool.name: Инструмент MCP, результат которого использовал этот запрос, с тем же скрытием и поведением версии, что и mcp_server.name. Отсутствует, когда запрос не использовал результат инструмента MCP.

Счётчик токенов

Увеличивается после каждого запроса API.

Атрибуты:

  • Все стандартные атрибуты
  • type: ("input", "output", "cacheRead", "cacheCreation")
  • model: Идентификатор модели (например, "claude-sonnet-5")
  • query_source: Категория подсистемы, которая выдала запрос. Один из "main", "subagent" или "auxiliary"
  • speed: "fast", когда запрос использовал быстрый режим. Отсутствует в противном случае
  • effort: Уровень усилий, применённый к запросу. См. Счётчик стоимости для деталей.
  • agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Атрибуция навыка, плагина, агента и MCP для запроса. См. Счётчик стоимости для определений и поведения скрытия.

Счётчик решений инструмента редактирования кода

Увеличивается, когда пользователь принимает или отклоняет использование инструмента Edit, Write или NotebookEdit.

Атрибуты:

  • Все стандартные атрибуты
  • tool_name: Имя инструмента ("Edit", "Write", "NotebookEdit")
  • decision: Решение пользователя ("accept", "reject")
  • source: Откуда пришло решение. Один из "config", "hook", "user_permanent", "user_temporary", "user_abort" или "user_reject". См. Событие решения инструмента для того, что означает каждое значение.
  • language: Язык программирования отредактированного файла, например "TypeScript", "Python", "JavaScript" или "Markdown". Возвращает "unknown" для неизвестных расширений файлов.

Счётчик активного времени

Отслеживает фактическое время, потраченное на активное использование Claude Code, исключая время простоя. Эта метрика увеличивается во время взаимодействия пользователя, такого как ввод текста и чтение ответов, и во время обработки CLI, такой как выполнение инструментов и генерация ответов AI.

Атрибуты:

  • Все стандартные атрибуты
  • type: "user" для взаимодействия с клавиатурой, "cli" для выполнения инструментов и ответов AI

События

Claude Code экспортирует следующие события через логи/события OpenTelemetry (когда настроен OTEL_LOGS_EXPORTER):

Атрибуты корреляции событий

Когда пользователь отправляет запрос, Claude Code может сделать несколько вызовов API и запустить несколько инструментов. Атрибут prompt.id позволяет вам связать все эти события с одним запросом, который их вызвал.

Атрибут Описание
prompt.id Идентификатор UUID v4, связывающий все события, созданные при обработке одного пользовательского запроса
event.sequence Счётчик на основе 0 для упорядочивания событий, подсчитанный на процесс Claude Code, а не на сеанс
message.uuid UUID сообщения, как сохранено в транскрипте сеанса, файлы ~/.claude/projects/*/*.jsonl. Присутствует на assistant_response, на api_response_body и на user_prompt, кроме отправок команд, которые могут создавать ноль или много сообщений. На assistant_response и api_response_body это финальная запись транскрипта ответа, от которой цепочка parentUuid следующего хода. Требуется Claude Code v2.1.214 или позже, или v2.1.274 или позже на api_response_body
request_id Назначенный сервером ID запроса API, прочитанный из заголовка ответа request-id, например req_011.... На ответе без заголовка request-id, как на Amazon Bedrock, значение поступает из заголовка x-amzn-requestid вместо этого. Присутствует на api_request, api_error, api_refusal, assistant_response и api_response_body, когда ответ содержит любой из этих заголовков. Совпадает с тем же атрибутом на диапазоне трассировки llm_request. Источник x-amzn-requestid требует Claude Code v2.1.282 или позже
client_request_id Созданный клиентом UUID, отправленный как заголовок запроса x-client-request-id. Присутствует на api_request и api_error на подключениях API первой стороны; отсутствует на бэкендах поставщиков третьих сторон и когда запрос был повторён через резервный вариант без потоковой передачи. Связывает запрос с его ответом и остаётся доступным для сбоев, таких как тайм-ауты, которые никогда не создали серверный request_id. Совпадает с тем же атрибутом на диапазоне трассировки llm_request. Требуется Claude Code v2.1.214 или позже

Чтобы отследить всю деятельность, вызванную одним запросом, отфильтруйте события по определённому значению prompt.id. Это возвращает событие user_prompt, любые события api_request и любые события tool_result, которые произошли при обработке этого запроса.

event.sequence начинается с 0 каждый раз, когда процесс Claude Code запускается, и считает вверх в течение жизни этого процесса. Он продолжает считать через /clear, который назначает новый session.id. Если вы возобновляете сеанс без ветвления, сеанс сохраняет свой session.id, но берёт свои значения event.sequence из процесса, который его возобновил, поэтому в одном сеансе более позднее событие может содержать более низкое значение, чем более раннее, или повторить одно. Чтобы упорядочить события сеанса, отсортируйте по event.timestamp и используйте event.sequence для упорядочивания событий, которые имеют одну и ту же временную метку.

Для восстановления на уровне сообщений каждый класс событий содержит ключ, который совпадает с полем в транскрипте сеанса. Формат записи транскрипта внутренний для Claude Code и меняется между версиями, поэтому конвейер, который объединяет эти поля, может сломаться при любом выпуске; рассматривайте объединения как специфичные для версии, а не как стабильный контракт:

  • message.uuid на user_prompt, assistant_response и api_response_body
  • request_id на событиях API, сохранённых как requestId на записях помощника транскрипта
  • tool_use_id на событиях tool_result и tool_decision

Событие пользовательского запроса

Регистрируется, когда пользователь отправляет запрос.

Имя события: claude_code.user_prompt

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "user_prompt"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • prompt_length: Длина запроса
  • prompt: Содержание запроса. Скрыто по умолчанию. Установите OTEL_LOG_USER_PROMPTS=1, чтобы включить его
  • message.uuid: UUID результирующего пользовательского сообщения, совпадающий с сохранённой записью транскрипта. Отсутствует при отправке команд, которые могут создавать ноль или много сообщений. Требуется Claude Code v2.1.214 или позже
  • 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

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "assistant_response"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • response_length: Длина текста ответа в символах
  • response: Текст ответа, усечённый на пределе содержания (60 КБ по умолчанию). Скрыт в <REDACTED> по умолчанию. Установите OTEL_LOG_ASSISTANT_RESPONSES=1, чтобы включить его. Когда OTEL_LOG_ASSISTANT_RESPONSES не установлен, OTEL_LOG_USER_PROMPTS управляет им вместо этого, поэтому установите OTEL_LOG_ASSISTANT_RESPONSES=0, чтобы сохранить ответы скрытыми, пока логирование запросов включено
  • model: Идентификатор модели (например, "claude-sonnet-5")
  • request_id: ID запроса API, описанный в Атрибуты корреляции событий
  • message.uuid: UUID финальной записи транскрипта ответа. Ответ API сохраняется как одна запись транскрипта на блок содержания; это последняя, от которой цепочка parentUuid следующего хода. Требуется Claude Code v2.1.214 или позже
  • query_source: Подсистема, которая выдала запрос, например "repl_main_thread", "compact" или имя подагента

Событие результата инструмента

Регистрируется, когда инструмент завершает выполнение. Не выпускается, если вызов инструмента был отклонён; см. Событие решения инструмента для отклонений.

Имя события: claude_code.tool_result

Атрибуты:

  • Все стандартные атрибуты
  • 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". См. Событие решения инструмента для того, что означает каждое значение. Источники, только для отклонения, "user_abort" и "user_reject" никогда не появляются на этом событии.
  • tool_input_size_bytes: Размер сериализованного в JSON входа инструмента в байтах
  • tool_result_size_bytes: Размер результата инструмента в байтах
  • mcp_server_scope: Идентификатор области сервера MCP (для инструментов MCP)
  • vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type (когда OTEL_LOG_TOOL_DETAILS=1): идентификация коммита успешного запуска git commit инструментом Bash или PowerShell. vcs.ref.head.revision — это SHA коммита, vcs.ref.head.name — это ветка, на которую он был закоммичен, и vcs.ref.head.type — это branch. Имя и тип опускаются, когда коммит был сделан на отсоединённой HEAD. Требуется Claude Code v2.1.269 или позже
  • tool_parameters (когда OTEL_LOG_TOOL_DETAILS=1): Строка JSON, содержащая параметры, специфичные для инструмента. Для встроенных серверов Claude Desktop в сеансах, которыми владеет Claude Desktop, пара mcp_server_name/mcp_tool_name включается даже с отключённым флагом, то же исключение, созданное хостом, как Событие решения инструмента, требующее Claude Code v2.1.214 или позже. Параметры варьируются по инструменту:
    • Для инструмента Bash: включает bash_command, full_command, timeout, description и dangerouslyDisableSandbox, плюс git_commit_id и git_branch, когда команда git commit успешна. git_commit_id — это полный SHA коммита, когда коммит является HEAD рабочего каталога сеанса, и сокращённый SHA git в противном случае. git_branch — это ветка, на которую он был закоммичен, опускается на отсоединённой HEAD
    • Для инструмента рабочей области приложения для рабочего стола, который также сообщает tool_name как Bash: включает только 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 К символами. Применяется ко всем инструментам, включая инструменты MCP.

Событие запроса API

Регистрируется для каждого запроса API к Claude.

Имя события: claude_code.api_request

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "api_request"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • model: Используемая модель (например, "claude-sonnet-5")
  • cost_usd: Предполагаемая стоимость в USD
  • cost_usd_micros: Предполагаемая стоимость в миллионных долях доллара США, выпущенная как целое число
  • duration_ms: Длительность запроса в миллисекундах
  • input_tokens: Количество входных токенов
  • output_tokens: Количество выходных токенов
  • cache_read_tokens: Количество токенов, прочитанных из кэша
  • cache_creation_tokens: Количество токенов, использованных для создания кэша
  • request_id: ID запроса API, например "req_011...", описанный в Атрибуты корреляции событий.
  • client_request_id: Созданный клиентом UUID, отправленный как заголовок запроса x-client-request-id; см. таблицу атрибутов корреляции событий для того, когда он присутствует. Требуется Claude Code v2.1.214 или позже
  • speed: "fast" или "normal", указывающий, был ли активен быстрый режим
  • query_source: Подсистема, которая выдала запрос, например "repl_main_thread", "compact" или имя подагента
  • effort: Уровень усилий, применённый к запросу: "low", "medium", "high", "xhigh" или "max". Отсутствует, когда Claude Code не отправляет уровень усилий, например на модели, которая не поддерживает усилия.
  • agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Атрибуция навыка, плагина, агента и MCP для запроса. См. Счётчик стоимости для определений и поведения скрытия.

Событие ошибки API

Регистрируется, когда запрос API к Claude не удаётся.

Имя события: claude_code.api_error

Атрибуты:

  • Все стандартные атрибуты
  • 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 запроса API, например "req_011...", описанный в Атрибуты корреляции событий.
  • client_request_id: Созданный клиентом UUID, отправленный как заголовок запроса x-client-request-id. Доступен даже при сбое, таком как тайм-аут или ошибка соединения, которые никогда не создали серверный request_id; см. таблицу атрибутов корреляции событий для того, когда он присутствует. Требуется Claude Code v2.1.214 или позже
  • speed: "fast" или "normal", указывающий, был ли активен быстрый режим
  • query_source: Подсистема, которая выдала запрос, например "repl_main_thread", "compact" или имя подагента
  • effort: Уровень усилий, применённый к запросу. Отсутствует, когда Claude Code не отправляет уровень усилий, например на модели, которая не поддерживает усилия.
  • agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Атрибуция навыка, плагина, агента и MCP для запроса. См. Счётчик стоимости для определений и поведения скрытия.

Событие отказа API

Регистрируется, когда запрос API возвращает stop_reason: "refusal". Отказы поступают на успешный поток ответов, а не как ошибка HTTP, поэтому событие api_error не срабатывает для них. Это событие позволяет вам отслеживать частоту отказов и группировать отказы по тем же атрибутам, что и api_request и api_error.

Имя события: claude_code.api_refusal

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "api_refusal"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • model: Идентификатор модели из запроса
  • request_id: ID запроса API, например "req_011...", описанный в Атрибуты корреляции событий.
  • query_source: Подсистема, которая выдала запрос, например "repl_main_thread", "compact" или имя подагента. См. api_request для определений.
  • speed: Либо "fast", когда активен Быстрый режим, либо "normal"
  • attempt: Номер попытки повтора. Первая попытка — это 1.
  • effort: Уровень усилий, применённый к запросу. Отсутствует, когда Claude Code не отправляет уровень усилий, например на модели, которая не поддерживает усилия.
  • 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 для запроса. См. Счётчик стоимости для определений и поведения скрытия.

Событие тела запроса API

Регистрируется для каждой попытки запроса API, когда установлен OTEL_LOG_RAW_API_BODIES. Одно событие выпускается на попытку, поэтому повторные попытки с отрегулированными параметрами каждая создают своё собственное событие.

Имя события: claude_code.api_request_body

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "api_request_body"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • body: Сериализованные в JSON параметры запроса Messages API, такие как системный запрос, сообщения и инструменты, усечённые на пределе содержания (60 КБ по умолчанию). Содержание расширенного мышления в предыдущих ходах помощника скрыто. Выпускается только в встроенном режиме (OTEL_LOG_RAW_API_BODIES=1).
  • body_ref: Абсолютный путь к файлу <dir>/<uuid>.request.json, содержащему неусечённое тело. Выпускается только в режиме файла (OTEL_LOG_RAW_API_BODIES=file:<dir>).
  • body_length: Неусечённая длина тела. Байты UTF-8, когда OTEL_LOG_RAW_API_BODIES=file:<dir>, или единицы кода UTF-16, когда =1
  • body_truncated: "true", когда произошло встроенное усечение. Отсутствует в режиме файла и когда усечение не произошло.
  • model: Идентификатор модели из параметров запроса
  • query_source: Подсистема, которая выдала запрос (например, "compact")
  • request_body_id: UUID, который идентифицирует тело запроса этой попытки. Событие api_response_body для попытки, которая успешна, содержит то же значение, поэтому вы можете связать ответ с точным запросом, который его создал. Требуется Claude Code v2.1.274 или позже

Событие тела ответа API

Регистрируется для каждого успешного ответа API, когда установлен OTEL_LOG_RAW_API_BODIES.

В режиме файла (OTEL_LOG_RAW_API_BODIES=file:<dir>), Claude Code также добавляет одну строку JSON в <dir>/index.jsonl для каждого успешного ответа с полями timestamp, session_id, query_source, model, request_id, message_id, message_uuid, request_file и response_file. Прочитайте его, чтобы найти файлы запроса и ответа за данным сообщением транскрипта без запроса к вашему бэкенду телеметрии. Файл индекса требует Claude Code v2.1.274 или позже.

Имя события: claude_code.api_response_body

Атрибуты:

  • Все стандартные атрибуты
  • 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: Абсолютный путь к файлу <dir>/<request_id>.response.json, содержащему неусечённое тело. Выпускается только в режиме файла (OTEL_LOG_RAW_API_BODIES=file:<dir>).
  • body_length: Неусечённая длина тела. Байты UTF-8, когда OTEL_LOG_RAW_API_BODIES=file:<dir>, или единицы кода UTF-16, когда =1
  • body_truncated: "true", когда произошло встроенное усечение. Отсутствует в режиме файла и когда усечение не произошло.
  • model: Идентификатор модели
  • query_source: Подсистема, которая выдала запрос
  • request_id: ID запроса API, например "req_011...", описанный в Атрибуты корреляции событий.
  • request_body_id: request_body_id события api_request_body, на которое отвечает этот ответ. Требуется Claude Code v2.1.274 или позже
  • message.id: ID сообщения, который API назначил ответу, поле id тела ответа. Требуется Claude Code v2.1.274 или позже
  • message.uuid: UUID финальной записи транскрипта ответа. Вместе с request_body_id он связывает сообщение транскрипта с телами запроса и ответа позади него. Требуется Claude Code v2.1.274 или позже

Событие решения инструмента

Регистрируется, когда принимается решение о разрешении инструмента (принять/отклонить).

Имя события: claude_code.tool_decision

Атрибуты:

  • Все стандартные атрибуты
  • 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"
  • tool_source: Всегда присутствует. Происхождение инструмента как закрытый набор значений, созданных CLI. Требуется Claude Code v2.1.214 или позже
    • "builtin": собственные инструменты CLI
    • "mcp": серверы MCP в целом
    • "sdk_host_builtin_mcp": встроенный в процесс сервер, встроенный в сам Claude Desktop, в сеансе, которым владеет Claude Desktop. Claude Desktop владеет сеансом, который он запустил из одной из своих собственных точек входа, claude-desktop, claude-desktop-3p или local-agent, когда этот сеанс не является вложенным дочерним; вложенные сеансы, включая сеансы, которые сам Claude Code порождает, сообщают эти серверы как "mcp"
  • source: Откуда пришло решение:
    • "config": Решено автоматически без запроса, на основе параметров проекта, правил разрешения или запрета в личных параметрах пользователя, политики, управляемой предприятием, флагов --allowedTools или --disallowedTools, активного режима разрешения, предоставления области действия сеанса из более раннего запроса в том же интерактивном сеансе CLI или потому что инструмент по своей природе безопасен. Событие не указывает, какой из этих источников совпал. Claude Code также сообщает "config", когда сам запрос подсказки разрешения не удаётся, например когда обратный вызов canUseTool Agent SDK или инструмент --permission-prompt-tool возвращает недействительный результат, или когда входной поток закрывается во время ожидания запроса. До v2.1.216 Claude Code сообщал эти сбои как "user_reject".
    • "hook": Hook PreToolUse или PermissionRequest вернул решение.
    • "user_permanent": Выпускается, когда пользователь выбрал "Да, и больше не спрашивать для ..." в подсказке разрешения, которая сохраняет правило разрешения в его личные параметры. В интерактивном CLI это выпускается только для самого этого выбора; более поздние вызовы, которые совпадают с сохранённым правилом, выпускают "config" вместо этого. В сеансах Agent SDK или неинтерактивных -p, как исходный выбор, так и более поздние совпадения правил выпускают "user_permanent". Рассматривается как принятие.
    • "user_temporary": Выпускается, когда пользователь выбрал "Да" в подсказке разрешения для одобрения в один раз, или выбрал опцию, которая предоставляет доступ на оставшуюся часть сеанса в подсказке редактирования или чтения файла. В интерактивном CLI это выпускается только для самого выбора; более поздние вызовы, разрешённые этим предоставлением области действия сеанса, выпускают "config" вместо этого. В сеансах Agent SDK или неинтерактивных -p, как выбор, так и более поздние совпадения выпускают "user_temporary". Рассматривается как принятие.
    • "user_abort": Выпускается, когда пользователь отклонил подсказку разрешения без ответа. В сеансах Agent SDK и неинтерактивных -p это включает прерывание хода, пока запрос разрешения canUseTool или --permission-prompt-tool ожидает; до v2.1.216 Claude Code сообщал это прерывание как "user_reject". Рассматривается как отклонение.
    • "user_reject": Выпускается, когда пользователь выбрал "Нет" при запросе. В интерактивном CLI это выпускается только для самого этого выбора; вызовы, которые совпадают с правилом запрета в личных параметрах пользователя, выпускают "config" вместо этого. В сеансах Agent SDK или неинтерактивных -p вызовы, которые совпадают с правилом запрета в личных параметрах, выпускают "user_reject". Рассматривается как отклонение.
  • tool_parameters (когда OTEL_LOG_TOOL_DETAILS=1): Строка JSON, содержащая параметры, специфичные для инструмента. Та же форма, что и Событие результата инструмента, минус поля после выполнения, такие как git_commit_id. Значения могут отличаться от tool_result для принятого вызова, если решение о разрешении переписывает вход инструмента через updatedInput. Используйте этот атрибут, чтобы увидеть, какая команда была отклонена, когда decision — это "reject".
    • Для инструментов "sdk_host_builtin_mcp": mcp_server_name и mcp_tool_name включаются даже когда OTEL_LOG_TOOL_DETAILS отключён, потому что приложение хоста определяет эти имена; без них отклонённый вызов одного из этих встроенных серверов был бы неатрибутируемым в потоке по умолчанию. Для серверов MCP, настроенных пользователем, tool_name события всегда является буквальным "mcp_tool", и имена сервера и инструмента появляются только в tool_parameters с включённым флагом; содержание аргумента требует флага везде. Требуется Claude Code v2.1.214 или позже
    • Для инструмента Bash: включает bash_command, full_command, timeout, description, dangerouslyDisableSandbox. Инструмент bash рабочей области приложения для рабочего стола также сообщает tool_name как Bash, но включает только bash_command, full_command и timeout
    • Для инструментов MCP: включает mcp_server_name, mcp_tool_name
    • Для инструмента Skill: включает skill_name
    • Для инструмента Agent или устаревшего инструмента Task: включает subagent_type

Событие изменения режима разрешения

Регистрируется, когда режим разрешения меняется, например из цикла Shift+Tab, выхода из режима плана или проверки ворот автоматического режима.

Имя события: claude_code.permission_mode_changed

Атрибуты:

  • Все стандартные атрибуты
  • 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

Атрибуты:

  • Все стандартные атрибуты
  • 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

Атрибуты:

  • Все стандартные атрибуты
  • 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): Стабильный хеш имени плагина и маркетплейса для группировки событий по плагину без раскрытия имени. Claude Code вычисляет его, как описано в событии загрузки плагина
  • 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. Сообщение об ошибке и трассировка стека никогда не включаются. Это событие не выпускается при работе с Amazon Bedrock, Agent Platform Google Cloud, Microsoft Foundry или когда установлен DISABLE_ERROR_REPORTING.

Имя события: claude_code.internal_error

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "internal_error"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • error_name: Имя класса ошибки, например "TypeError" или "SyntaxError"
  • error_code: Код errno Node.js, такой как "ENOENT", если присутствует в ошибке

Событие установки плагина

Регистрируется, когда плагин завершает установку, как из команды CLI claude plugin install, так и из интерактивного пользовательского интерфейса /plugin.

Имя события: claude_code.plugin_installed

Атрибуты:

  • Все стандартные атрибуты
  • 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

Атрибуты:

  • Все стандартные атрибуты
  • 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", "community", "org", "user-local" или "default-bundle"
  • enabled_via: как плагин стал включённым: "default-enable", "org-policy", "admin-install", "seed-mount" или "user-install". Значение "admin-install" означает, что плагин установлен как обязательный или автоустановка для вашей организации в Organization settings > Plugins & skills. До v2.1.246 Claude Code сообщал эти плагины как "user-install" или "seed-mount"
  • plugin_id_hash: детерминированный хеш имени плагина и маркетплейса, отправляемый только вашему настроенному экспортёру. Позволяет вам считать отдельные плагины третьих сторон, загруженные в вашем парке, без записи их имён. Для плагинов, синхронизированных из claude.ai, Claude Code хеширует имя плагина с именем маркетплейса, которое claude.ai сообщает для плагина, или с synced в противном случае. До v2.1.246 Claude Code не использовал имя маркетплейса claude.ai сообщает в хеше
  • 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, "false" в противном случае. В безопасном режиме это событие сообщает только настроенный инвентарь; команды, навыки, hooks и серверы MCP плагина не загружаются. Требуется Claude Code v2.1.169 или позже

Событие активации навыка

Регистрируется, когда навык вызывается, будь то Claude вызывает его через инструмент Skill или вы запускаете его как команду /.

Имя события: claude_code.skill_activated

Атрибуты:

  • Все стандартные атрибуты
  • 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", когда навык является навыком рабочего процесса. Отсутствует в противном случае
  • plugin.name (когда OTEL_LOG_TOOL_DETAILS=1 или плагин из официального маркетплейса): Имя владеющего плагина, когда навык предоставляется плагином
  • marketplace.name (когда OTEL_LOG_TOOL_DETAILS=1 или плагин из официального маркетплейса): Маркетплейс, из которого был установлен владеющий плагин, когда навык предоставляется плагином

Событие упоминания @

Регистрируется, когда Claude Code разрешает упоминание @ в запросе. Не каждое упоминание выпускает событие: пути раннего выхода, такие как отказы в разрешении, файлы чрезмерного размера, вложения ссылок PDF и сбои перечисления каталогов, возвращаются без логирования.

Имя события: claude_code.at_mention

Атрибуты:

Событие исчерпания повторных попыток API

Регистрируется один раз, когда запрос API не удаётся после более чем одной попытки. Выпускается вместе с финальным событием api_error.

Имя события: claude_code.api_retries_exhausted

Атрибуты:

  • Все стандартные атрибуты
  • 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

Атрибуты:

  • Все стандартные атрибуты
  • 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, "false" в противном случае. Требуется Claude Code v2.1.169 или позже
  • hook_matcher (когда OTEL_LOG_TOOL_DETAILS=1): строка сопоставления из конфигурации hook, когда она установлена
  • plugin.name (когда hook_source — это "pluginHook"): имя участвующего плагина. Для плагинов вне официального маркетплейса и встроенного пакета значение — это "third-party", если не установлен OTEL_LOG_TOOL_DETAILS=1
  • plugin_id_hash (когда hook_source — это "pluginHook"): детерминированный хеш имени плагина и маркетплейса, отправляемый только вашему настроенному экспортёру. Позволяет вам считать отдельные участвующие плагины без записи их имён. Claude Code вычисляет его, как описано в событии загрузки плагина

Событие начала выполнения hook

Регистрируется, когда один или несколько hooks начинают выполняться для события hook.

Имя события: claude_code.hook_execution_start

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "hook_execution_start"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • hook_event: Тип события hook, например "PreToolUse" или "PostToolUse"
  • hook_name: Полное имя hook, включая сопоставление, например "PreToolUse:Write"
  • num_hooks: Количество совпадающих команд hook
  • managed_only: "true", когда разрешены только hooks управляемой политики
  • hook_source: "policySettings" или "merged"
  • safe_mode: "true", когда сеанс был запущен с --safe-mode, "false" в противном случае. Требуется Claude Code v2.1.169 или позже
  • hook_definitions: Конфигурация hook, сериализованная в JSON. Включается только когда включены как детальная бета-трассировка, так и OTEL_LOG_TOOL_DETAILS=1

Событие завершения выполнения hook

Регистрируется, когда все hooks для события hook завершены.

Имя события: claude_code.hook_execution_complete

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "hook_execution_complete"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • hook_event: Тип события hook
  • hook_name: Полное имя hook, включая сопоставление
  • num_hooks: Количество совпадающих команд hook
  • num_success: Количество, которое завершилось успешно
  • num_blocking: Количество, которое вернуло решение блокировки
  • num_non_blocking_error: Количество, которое не удалось без блокировки
  • num_cancelled: Количество отменено до завершения
  • total_duration_ms: Длительность на стене всех совпадающих hooks
  • stdout_chars: Общее количество символов stdout в совпадающих hooks, которые успешно завершились. Требуется Claude Code v2.1.280 или позже
  • additional_context_chars: Общее количество символов additionalContext, возвращённых совпадающими hooks. Требуется Claude Code v2.1.280 или позже
  • system_message_chars: Общее количество символов systemMessage, возвращённых совпадающими hooks. Требуется Claude Code v2.1.280 или позже
  • initial_user_message_chars: Общее количество символов initialUserMessage, возвращённых совпадающими hooks. Требуется Claude Code v2.1.280 или позже
  • num_outputs_persisted: Количество выходов hook свыше 10 000-символьного лимита, которые Claude Code сохранил в файл. Требуется Claude Code v2.1.280 или позже
  • managed_only: "true", когда разрешены только hooks управляемой политики
  • hook_source: "policySettings" или "merged"
  • safe_mode: "true", когда сеанс был запущен с --safe-mode, "false" в противном случае. Требуется Claude Code v2.1.169 или позже
  • hook_definitions: Конфигурация hook, сериализованная в JSON. Включается только когда включены как детальная бета-трассировка, так и OTEL_LOG_TOOL_DETAILS=1

Событие метрик hook плагина

Регистрируется, когда hook плагина официального маркетплейса выпускает метрики на выполнение. Только плагины, установленные из официального маркетплейса Anthropic, могут выпускать эти. Плагины маркетплейса третьих сторон и настроенные пользователем hooks не выпускают в это событие. Используйте это событие для мониторинга поведения плагина, такого как поиск скоростей, затрат и длительностей из вашего собственного стека наблюдаемости.

Имя события: claude_code.hook_plugin_metrics

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "hook_plugin_metrics"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • plugin_id: идентификатор плагина в форме <name>@<marketplace>
  • hook_event: тип события hook, который выпустил метрики
  • До 20 ключей метрик, выпущенных плагином. Имена совпадают с ^[a-z][a-z0-9_]{0,39}$. Значения — это логическое значение или число.

Событие компактирования

Регистрируется, когда компактирование разговора завершается.

Имя события: claude_code.compaction

Атрибуты:

  • Все стандартные атрибуты
  • 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 или позже

Событие завершения подагента

Регистрируется, когда подагент завершает работу и возвращает свой результат в разговор, который его запустил. Используйте его для сворачивания использования инструментов и времени выполнения по типу подагента; для сворачивания токенов или стоимости используйте счётчик токенов и счётчик стоимости, отфильтрованные по query_source "subagent", так как total_tokens этого события охватывает только финальный запрос. Категория "subagent" также считает запросы из hooks на основе агентов, которые не выпускают событие подагента.

Имя события: claude_code.subagent_completed

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "subagent_completed"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • agent_type: Тип подагента. Встроенные имена агентов и агенты из официальных плагинов маркетплейса отображаются как есть; другие имена агентов заменяются на "custom", если не установлен OTEL_LOG_TOOL_DETAILS=1
  • agent.source: Откуда пришло определение агента: built-in, plugin или источник параметров, который определил пользовательского агента, например userSettings или projectSettings
  • is_built_in: Является ли подагент встроенным типом агента
  • is_async: Работал ли подагент в фоне
  • total_tokens: Объём токенов финального запроса API подагента: входные, создание кэша, чтение кэша и выходные токены этого одного запроса, примерно размер контекста подагента при завершении. Не сумма по всему запуску
  • total_tool_uses: Количество вызовов инструментов, которые подагент сделал во всём запуске
  • duration_ms: Время выполнения в миллисекундах
  • model: Модель, на которую был разрешён подагент для запуска
  • final_model: Модель, которая создала финальный ответ подагента, отличающаяся от model после переключения во время запуска, такого как резервный вариант. Требуется Claude Code v2.1.212 или позже
  • model_swapped: Обслуживала ли более одной модели запросы подагента. Требуется Claude Code v2.1.212 или позже
  • plugin_id_hash, plugin.name: Присутствует для агентов, предоставляемых плагинами. Имена плагинов официального маркетплейса отображаются как есть; другие имена плагинов заменяются на "third-party", если не установлен OTEL_LOG_TOOL_DETAILS=1

Событие опроса обратной связи

Регистрируется, когда показывается или отвечается опрос качества сеанса. См. Опросы качества сеанса для того, что опросы собирают и как их контролировать.

Имя события: claude_code.feedback_survey

Атрибуты:

  • Все стандартные атрибуты
  • 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. Выпускается как логическое значение, а не строка. Присутствует на событиях опроса session. Отфильтруйте по этому атрибуту, чтобы подтвердить, что переопределение применяется в парке

Событие развёртки удержания

Регистрируется один раз за запуск развёртки очистки удержания, которая удаляет транскрипты сеансов и другие данные приложения старше параметра cleanupPeriodDays. Claude Code запускает развёртку в фоне максимум один раз за сеанс, и запуск, который ничего не удаляет, всё равно выпускает событие. Если Claude Code запустил развёртку в любом сеансе на одной машине в последние 24 часа, он задерживает развёртку этого сеанса как минимум на 10 минут, поэтому сеанс, который выходит раньше, ничего не выпускает. Когда вы запускаете claude -p с --bare, Claude Code не запускает развёртку и ничего не выпускает.

Как каждое событие OTel на этой странице, оно идёт только на бэкенд телеметрии, который вы настраиваете. Требуется Claude Code v2.1.227 или позже.

Когда Claude Code не может безопасно определить период удержания, он приостанавливает развёртку и выпускает событие с result, установленным в "skipped" и skip_reason. Когда управляемые параметры устанавливают cleanupPeriodDays, управляемое значение закрепляет период удержания и развёртка работает даже когда файл параметров в более низком приоритете сломан или недействителен. Когда сам managed-settings.json не может быть прочитан, Claude Code всё равно приостанавливает развёртку, если только управляемый уровень не поставляет cleanupPeriodDays откуда-то ещё, например из параметров, управляемых сервером, или из managed-settings.d/ drop-in рядом с повреждённым файлом. Атрибуты счётчика удаления присутствуют только когда result — это "complete".

Имя события: claude_code.retention_sweep

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "retention_sweep"
  • event.timestamp: Временная метка ISO 8601
  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий
  • result: "complete", когда развёртка работала, "skipped", когда Claude Code её приостановил
  • period_days: Значение cleanupPeriodDays из объединённых параметров, в днях, или 30, когда ни один источник его не устанавливает. На пропущенных событиях значение, которое развёртка использовала бы, вычисленное из источников параметров, которые Claude Code мог прочитать
  • used_default: "true", когда ни один читаемый источник параметров не устанавливает cleanupPeriodDays, "false" в противном случае. На полных событиях "true" означает, что применён 30-дневный стандарт
  • skip_reason: Почему Claude Code приостановил развёртку. Присутствует только когда result — это "skipped":
    • "user_source_disabled": Параметры пользователя исключены, например флагом --setting-sources или опцией settingSources SDK, и ни один включённый источник не предоставляет cleanupPeriodDays
    • "settings_unknowable": Файл параметров не может быть прочитан или разобран, поэтому cleanupPeriodDays или desktopSessionCleanupPeriodDays может быть установлен в значение, которое Claude Code не может видеть
    • "settings_invalid_key_set": Параметры имеют ошибки валидации и cleanupPeriodDays или desktopSessionCleanupPeriodDays явно установлены, поэтому возврат к стандарту может удалить или сохранить файлы против этого параметра
  • transcripts_deleted: Количество транскриптов сеансов, файлы верхнего уровня ~/.claude/projects/*/*.jsonl, которые развёртка удалила
  • transcripts_exempted_desktop: Количество транскриптов прошлого периода удержания, которые развёртка сохранила в соответствии с правилом Claude Desktop и Cowork. Они не считаются в files_past_cutoff. Требуется Claude Code v2.1.248 или позже
  • session_files_deleted: Количество артефактов, которые развёртка файлов сеанса удалила: транскрипты плюс файлы-спутники для каждого сеанса, такие как боковые панели, записи и результаты инструментов
  • artifacts_deleted: Общее количество элементов, которые развёртка удалила в каталогах данных, которые она охватывает, включая файлы сеанса. Некоторые развёртки считают целое удалённое дерево каталогов как один элемент и несколько проходов очистки не вносят вклад в счётчик, поэтому рассматривайте значение как нижний предел, а не точный счёт файлов
  • files_retained_fresh: Файлы, проверенные и оставленные на месте, потому что они всё ещё находятся в пределах периода удержания. Только развёртки для каждого файла считают эти, поэтому значение — это нижний предел; ненулевое значение — это нормальное устойчивое состояние
  • files_past_cutoff: Файлы старше периода удержания, которые развёртка не смогла удалить, например из-за ошибки разрешения или файла, удерживаемого открытым. Значение выше нуля означает, что файлы пережили настроенный период удержания; ноль не является доказательством того, что они не были, потому что неудачное удаление целого каталога считается в error_count вместо этого
  • error_count: Количество ошибок, которые развёртка встретила при перечислении или удалении файлов

Событие разрешения управляемых параметров

Регистрируется с управляемыми параметрами, которые разрешил сеанс: один раз при запуске сеанса, снова когда либо управляемые параметры, либо состояние помощника политики меняется во время сеанса, и когда Claude Code отказывается запускаться или заканчивает сеанс по одной из причин, которые атрибут error.type перечисляет. Используйте это событие, чтобы найти машины, работающие на неожиданном управляемом источнике, машины, чей помощник политики не работает, и причину, по которой машина отказалась запускаться. Требуется Claude Code v2.1.274 или позже.

По умолчанию событие содержит управляемые источники и состояние помощника политики, но не сами параметры. Чтобы добавить скрытый атрибут managed_settings.settings и дайджест managed_settings.resolved_sha256, установите OTEL_LOG_MANAGED_SETTINGS=1:

  • Установите его в блоке env управляемых параметров, параметров пользователя или --settings, или в среде, в которой вы запускаете Claude Code. Значение в параметрах проекта или локальных параметрах не включает его, потому что клонированный репозиторий может их писать.
  • Параметры, управляемые сервером, могут установить его без отображения диалога одобрения безопасности, потому что переменная только добавляет вашу собственную скрытую политику организации к событию, которое ваша организация уже получает.

В интерактивном сеансе в папке, которую вы не доверили, Claude Code не экспортирует событие отказа.

Имя события: claude_code.managed_settings_resolved

Атрибуты:

  • Все стандартные атрибуты

  • event.name: "managed_settings_resolved"

  • event.timestamp: Временная метка ISO 8601

  • event.sequence: счётчик на процесс для упорядочивания событий, описанный в Атрибуты корреляции событий

  • managed_settings.trigger: "startup" для события запуска сеанса, "change", когда управляемые параметры или состояние помощника политики изменились позже в сеансе, или "refused", когда политика управляемых параметров остановила сеанс. Claude Code отправляет событие change только когда атрибут отличается от последнего события, которое он отправил, и изменённое значение параметра считается даже когда OTEL_LOG_MANAGED_SETTINGS отключён

  • error.type: почему Claude Code остановил сеанс. Присутствует только на событиях refused:

    • "helper_failed": запуск помощника политики не удался
    • "policy_invalid": управляемые параметры содержат ошибку, которая останавливает Claude Code от запуска, или источник администратора не смог загрузиться, поэтому Claude Code не может проверить принудительный вход организации
    • "consent_rejected": пользователь отклонил диалог одобрения безопасности для параметров, управляемых сервером
    • "force_refresh_failed": выборка параметров, которую требует forceRemoteSettingsRefresh, не удалась
    • "gateway_rejected": шлюз приложений Claude ответил на загрузку управляемых параметров с HTTP 403
    • "version_below_minimum": эта версия Claude Code ниже requiredMinimumVersion или выше requiredMaximumVersion
    • "_OTHER": загрузка управляемых параметров шлюза приложений Claude не удалась по другой причине

  • managed_settings.sources: каждый управляемый источник, который доставляет как минимум один ключ политики, в порядке убывания приоритета, включая источники, чьи ключи не вступают в силу в first-wins. Значения — это "remote", "plist" или "hklm" для политики MDM или уровня ОС, "file" для файлов управляемых параметров и drop-ins, "parent", когда хост встраивания поставляет параметры, и "hkcu" для значения реестра Windows HKCU, когда Claude Code его читает. Источник, который содержит только ключи управления или который Claude Code не смог прочитать, не указан. Выпускается как массив строк, пусто, когда ни один управляемый источник не доставляет ключ политики

  • managed_settings.source_behavior: значение managedSourcesBehavior, которое Claude Code прочитал, "first-wins" или "merge". "first-wins", когда ни один источник не устанавливает ключ

  • managed_settings.helper.state: состояние помощника политики, который выбранный источник MDM или файла настраивает:

    • "ok": выход помощника служит управляемыми параметрами
    • "bad_path", "not_a_file", "exit_nonzero", "timed_out", "oversize", "parse_failed", "envelope_invalid" или "schema_rejected": последний запуск помощника не удался. Сбои помощника описывает случаи
    • "none": помощник не настроен, или источник, который его настраивает, не является политикой MDM или файлом управляемых параметров

  • managed_settings.helper.applied: "output", пока выход помощника служит управляемыми параметрами, "none", когда он не служит

  • managed_settings.helper.entry: "policyHelper", когда Claude Code выбрал policyHelper. Отсутствует, когда он не выбрал помощника

  • managed_settings.helper.path: настроенный path помощника. Присутствует всякий раз, когда Claude Code выбрал помощника, независимо от того, установлен ли OTEL_LOG_MANAGED_SETTINGS

  • managed_settings.resolved_sha256 (когда OTEL_LOG_MANAGED_SETTINGS=1): SHA-256 разрешённых управляемых параметров перед скрытием, сериализованных как JSON с ключами, отсортированными рекурсивно и без пробелов. Машины с одинаковым дайджестом работают с одной и той же политикой. Claude Code отправляет дайджест только с opt-in, потому что короткая политика может быть восстановлена путём хеширования предположений. Отсутствует, когда управляемые параметры не разрешены, и на событиях refused

  • managed_settings.settings (когда OTEL_LOG_MANAGED_SETTINGS=1): имена и форма разрешённых управляемых параметров как строка JSON со скрытыми значениями. Отсутствует на событиях refused. Claude Code строит её из своей схемы параметров:

    • Имя параметра, которое схема объявляет, экспортируется, и ключ, который она не объявляет, опускается
    • Логические значения, числа и строковые значения, которые схема ограничивает фиксированным набором опций, например permissions.defaultMode, экспортируются как есть. sandbox.network.httpProxyPort и sandbox.network.socksProxyPort экспортируются как "[REDACTED]"
    • Каждая другая строка, такая как model, apiKeyHelper, каждое значение env, каждый URL и каждая команда, экспортируется как "[REDACTED]"
    • Имена записей карт, такие как имена переменных env и ID плагинов, экспортируются как есть. Параметр, чьи записи схема не типизирует, например vimInsertModeRemaps, экспортируется как одиночный "[REDACTED]", и sandbox.ignoreViolations экспортируется как список его списков путей без шаблонов команд
    • Список сохраняет свою длину, с каждой записью скрытой по тем же правилам
    • Правило permissions.allow, permissions.deny или permissions.ask экспортируется как его имя инструмента со скрытым содержанием, например Read([REDACTED]), когда инструмент встроен в эту версию Claude Code или является ссылкой mcp__, такой как mcp__jira__create_issue. Любое другое правило экспортируется как "[REDACTED]"
    • Hooks следуют тем же правилам, поэтому поля с фиксированными опциями и числовые поля, такие как type и timeout, показываются, пока каждая команда, URL, matcher и условие if экспортируются как "[REDACTED]"

    Например, управляемые параметры с apiKeyHelper, двумя переменными env и правилом запрета экспортируются как {"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}.

    Claude Code обрезает значение на 8 КБ UTF-8, и обрезанное значение не является действительным JSON

  • managed_settings.settings_truncated (когда managed_settings.settings присутствует): true, когда Claude Code обрезал managed_settings.settings на 8 КБ, false в противном случае. Выпускается как логическое значение, а не строка

Интерпретация данных метрик и событий

Экспортируемые метрики и события поддерживают ряд анализов:

Мониторинг использования

Метрика Возможность анализа
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

Claude Code учитывает каждый потоковый ответ в метриках затрат и токенов ровно один раз, включая случаи, когда шлюз или прокси-сервер за ANTHROPIC_BASE_URL потоком передает использование прогрессивно через несколько кадров. До версии 2.1.214 потоки, которые содержали использование более чем в одном кадре, завышали claude_code.cost.usage и claude_code.token.usage примерно на один дополнительный полный запрос на каждый дополнительный кадр.

Оповещения и сегментация

Распространенные оповещения, которые следует рассмотреть:

  • Скачки затрат
  • Необычное потребление токенов
  • Высокий объем сеансов от конкретных пользователей

Все метрики можно сегментировать по стандартным атрибутам. Атрибут model доступен на claude_code.token.usage, claude_code.cost.usage и начиная с версии 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. Начиная с версии 2.1.199, вы можете установить CLAUDE_CODE_RETRY_WATCHDOG для повышения значения по умолчанию и снятия ограничения.

Когда запрос исчерпывает все повторные попытки при переходной ошибке, attempt равен на один больше, чем это эффективное ограничение: 11 по умолчанию и никогда не более 16, если не установлен watchdog. Более низкое значение указывает на неповторяемую ошибку, такую как ответ 400, или причину с собственным меньшим бюджетом повторных попыток. Например, Claude Code повторяет сбой при загрузке учетных данных AWS или Google Cloud не более двух раз.

Чтобы различить сеанс, который восстановился, от того, который застопорился, сгруппируйте события по session.id и проверьте, существует ли более позднее событие api_request после ошибки.

Анализ событий

Данные событий предоставляют подробные сведения о каждом взаимодействии Claude Code:

Паттерны использования инструментов: анализируйте события результатов инструментов для выявления:

  • Наиболее часто используемых инструментов
  • Показателей успеха инструментов
  • Среднего времени выполнения инструментов
  • Паттернов ошибок по типам инструментов

Мониторинг производительности: отслеживайте длительность запросов API и время выполнения инструментов для выявления узких мест производительности.

Аудит событий безопасности

События OpenTelemetry являются источником данных аудита для активности Claude Code. Каждое событие содержит атрибуты идентификации, которые связывают вызовы инструментов, активность MCP и решения о разрешениях с пользователем, который их инициировал. Экспортер логов OTLP может доставлять эти события на любую платформу Security Information and Event Management (SIEM) с приемником OTLP или на OpenTelemetry Collector, который перенаправляет на ваш SIEM.

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

Стандартные атрибуты на каждом событии включают идентификацию аутентифицированного пользователя: user.email, user.account_uuid, user.account_id и organization.id при входе с учетной записью Claude или, в облачном сеансе, когда учетные данные самого сеанса их содержат, плюс user.id и область сеанса session.id. user.id является идентификатором, ограниченным установкой, за исключением сеансов Claude apps gateway, где это субъект IdP из выданного шлюзом токена.

В сеансе, который запускает разработчик, вызовы инструментов MCP, команды Bash и редактирование файлов поэтому приписываются этому разработчику. Claude Code не действует под отдельной учетной записью сервиса; идентификация, записанная на каждом событии, это собственная учетная запись Claude разработчика или идентификация IdP разработчика в сеансе Claude apps gateway. В сеансах канала Claude Tag, Claude работает как общая идентификация вашей организации.

Когда Claude Code аутентифицируется с прямым ключом API или против Amazon Bedrock, Google Cloud's Agent Platform или Microsoft Foundry, в сеансе нет учетной записи Claude и только user.id и session.id заполняются. В этих развертываниях прикрепите идентификацию пользователя самостоятельно с помощью OTEL_RESOURCE_ATTRIBUTES, установленного для каждого пользователя через файл управляемых параметров или оболочку запуска. Сеансы Claude apps gateway не требуют ничего из этого: CLI автоматически проставляет идентификацию IdP, как описано в Стандартные атрибуты.

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: сохраняет mcp_server_scope и tool_name, отредактированный на буквальное значение "mcp_tool" для пользовательских серверов, опускает содержимое аргументов. Для встроенных серверов Claude Desktop в сеансах, которыми владеет Claude Desktop, он также сохраняет пару mcp_server_name/mcp_tool_name внутри tool_parameters, то же исключение, написанное хостом, что и tool_decision, требующее Claude Code v2.1.214 или позже
  • tool_decision: сохраняет tool_source и tool_name, отредактированный на буквальное значение "mcp_tool" для пользовательских серверов, опускает содержимое аргументов. Для встроенных серверов Claude Desktop в сеансах, которыми владеет Claude Desktop, он также сохраняет пару mcp_server_name/mcp_tool_name внутри tool_parameters; tool_source и пара имен оба требуют Claude Code v2.1.214 или позже
  • 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)
Какие источники управляемых параметров запускает машина, здорова ли её помощник политики и почему машина отказалась запускаться managed_settings_resolved managed_settings.trigger, managed_settings.sources, managed_settings.source_behavior, managed_settings.helper.state, error.type; managed_settings.settings и managed_settings.resolved_sha256 с OTEL_LOG_MANAGED_SETTINGS=1

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

Отправка событий в SIEM

Укажите OTEL_EXPORTER_OTLP_LOGS_ENDPOINT на приемник OTLP вашего SIEM или на OpenTelemetry Collector, который перенаправляет на собственный API приема вашего SIEM. Следующий пример управляемых параметров экспортирует только события с полной деталью инструмента, включенной для аудита MCP и Bash:

{
  "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"
  }
}

Чтобы подтвердить, что события прибыли, отправьте подсказку в сеансе, работающем под этой конфигурацией, и проверьте ваш SIEM на событие claude_code.user_prompt. Если ничего не прибыло, запустите Claude Code с claude --debug-file <path> и проверьте этот журнал на ошибки экспорта [3P telemetry].

Рассмотрения бэкенда

Выбор вашего бэкенда метрик, логов и трассировок определяет типы анализов, которые вы можете выполнять:

Для метрик

  • Базы данных временных рядов: Расчеты скорости, агрегированные метрики
  • Колончатые хранилища: Сложные запросы, анализ уникальных пользователей
  • Полнофункциональные платформы наблюдаемости: Продвинутые запросы, визуализация, оповещения

Для событий/логов

  • Системы агрегации логов: Полнотекстовый поиск, анализ логов
  • Колончатые хранилища: Анализ структурированных событий
  • Полнофункциональные платформы наблюдаемости: Корреляция между метриками и событиями

Для трассировок

Выберите бэкенд, поддерживающий хранилище распределенных трассировок и корреляцию span:

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

Для организаций, требующих метрик Daily/Weekly/Monthly Active User (DAU/WAU/MAU), рассмотрите бэкенды, поддерживающие эффективные запросы уникальных значений.

Информация о сервисе

Все метрики и события экспортируются со следующими атрибутами ресурса:

  • service.name: claude-code для сеансов терминала, claude-code-desktop для сеансов, запущенных с вкладки Code в приложении Claude Desktop
  • service.version: Текущая версия Claude Code или версия приложения Desktop для сеансов вкладки Code
  • os.type: Тип операционной системы (например, linux, darwin, windows)
  • os.version: Строка версии операционной системы
  • host.arch: Архитектура хоста (например, amd64, arm64)
  • wsl.version: Номер версии WSL (присутствует только при запуске на Windows Subsystem for Linux)
  • Имя счетчика: com.anthropic.claude_code

Если ваши конвейеры сборщика или панели мониторинга фильтруют по service.name = claude-code, добавьте claude-code-desktop в фильтр, чтобы также захватить телеметрию из сеансов вкладки Code.

Ресурсы для измерения ROI

Для полного руководства по измерению возврата инвестиций для Claude Code, включая настройку телеметрии, анализ затрат, метрики производительности и автоматизированные отчеты, см. Руководство по измерению ROI Claude Code. Этот репозиторий предоставляет готовые конфигурации Docker Compose, настройки Prometheus и OpenTelemetry, а также шаблоны для создания отчетов о производительности, интегрированные с такими инструментами, как Linear.

Безопасность и конфиденциальность

  • Экспорт OpenTelemetry на ваш бэкенд является добровольным и требует явной конфигурации. Информацию об отдельной операционной телеметрии Anthropic и о том, как её отключить, см. в разделе Data usage
  • Содержимое файлов в исходном виде и фрагменты кода не включаются в метрики или события. Span трассировок — это отдельный путь данных: см. пункт OTEL_LOG_TOOL_CONTENT ниже
  • При аутентификации через OAuth user.email включается в атрибуты телеметрии, отправляется только на endpoint OTel, который вы настраиваете, никогда на Anthropic. Если это вызывает беспокойство для вашей организации, работайте с вашим бэкендом телеметрии для фильтрации или редактирования этого поля
  • Содержимое пользовательской подсказки не собирается по умолчанию. Записывается только длина подсказки. Чтобы включить содержимое подсказки, установите OTEL_LOG_USER_PROMPTS=1. При детальной бета-трассировке эта переменная действует шире, чем текст подсказки: она также управляет атрибутом span new_context, который содержит результаты инструментов на span claude_code.llm_request
  • Текст ответа помощника не собирается по умолчанию. Записывается только длина ответа. Чтобы включить текст ответа, установите 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. Для встроенных серверов Claude Desktop в сеансах, которыми владеет Claude Desktop, tool_decision и tool_result содержат пару mcp_server_name/mcp_tool_name, имена, созданные хостом, а не содержимое аргументов, даже с отключённым флагом. Исключение требует Claude Code v2.1.214 или позже. Эти данные отправляются только на 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 команд
    • Счётчики стоимости и токенов и события api_request, api_error и api_refusal содержат реальные имена агента, навыка, плагина и MCP сервера и инструмента в их атрибутах атрибуции
    • Span трассировки включают тот же атрибут tool_input и атрибуты, полученные из входных данных, такие как file_path, с тем же усечением, что и tool_input
  • Содержимое инструмента не логируется в span трассировок по умолчанию. Чтобы включить его, установите OTEL_LOG_TOOL_CONTENT=1. Span claude_code.tool затем содержит событие span tool.output с содержимым файлов в исходном виде, выходными данными команды Bash и тем, что возвращают MCP инструменты, WebFetch и WebSearch, усеченными на лимит содержимого (60 КБ по умолчанию) на атрибут. Результаты от MCP инструментов, WebFetch и WebSearch требуют Claude Code v2.1.283 или позже. Содержимое инструмента также достигает span через new_context, чей gate отличается для каждого span. Настройте ваш бэкенд телеметрии для фильтрации или редактирования этих атрибутов по мере необходимости
  • Тела запроса и ответа Anthropic Messages API в исходном виде не логируются по умолчанию. Чтобы включить их, установите OTEL_LOG_RAW_API_BODIES в вашей оболочке, пользовательских параметрах или управляемых параметрах. Это игнорируется в project and local settings. Тела содержат полную историю разговора, включая системную подсказку, каждый предыдущий ход пользователя и помощника, и результаты инструментов, поэтому включение этого подразумевает согласие со всем, что раскрыли бы другие флаги содержимого OTEL_LOG_*. Claude Code всегда скрывает содержимое расширенного мышления Claude из этих тел, независимо от других параметров. Значение, которое вы установите, определяет, как Claude Code доставляет тела:

    • С =1, Claude Code выдает события логов api_request_body и api_response_body для каждого вызова API. Атрибут body событий содержит JSON-сериализованную нагрузку, усеченную на лимит содержимого (60 КБ по умолчанию)

    • С =file:<dir>, Claude Code записывает неусеченные тела в файлы .request.json и .response.json в этом каталоге, и события содержат путь body_ref вместо встроенного тела. Отправьте каталог с коллектором логов или sidecar, а не через поток телеметрии.

      Для каждого успешного ответа Claude Code также добавляет одну строку в файл index.jsonl в этом каталоге, связывая файл ответа с файлом запроса, который его создал, и с сообщением транскрипта, которым он стал. Каждая строка не содержит содержимого сообщения, и раздел API response body event перечисляет его поля. Файл индекса требует Claude Code v2.1.274 или позже

Мониторинг Claude Code на Amazon Bedrock

Для подробного руководства по мониторингу использования Claude Code для Amazon Bedrock см. Реализация мониторинга Claude Code (Amazon Bedrock).