Мониторинг

Узнайте, как включить и настроить 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 --debug и проверьте журнал отладки. 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 не передает переменные окружения OTEL_* подпроцессам, которые он порождает, включая инструмент Bash, hooks, MCP серверы и языковые серверы. Приложение, инструментированное OpenTelemetry, которое вы запускаете через инструмент Bash, не наследует endpoint экспортера Claude Code или заголовки, поэтому установите эти переменные непосредственно в команде, если это приложение должно экспортировать свою собственную телеметрию.

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

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

• 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 или позже.

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

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

Эти переменные настраивают экспортеры, endpoints и поведение экспорта для всех развертываний. Если вы установите переменную endpoint или протокола для конкретного сигнала, такую как OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, Claude Code использует её вместо универсальной переменной для этого сигнала. Если вы установите переменную заголовков для конкретного сигнала, такую как OTEL_EXPORTER_OTLP_METRICS_HEADERS, Claude Code объединяет её с универсальной переменной OTEL_EXPORTER_OTLP_HEADERS для этого сигнала. На машинах с управляемыми параметрами см. Как управляемые параметры блокируют назначение OTLP для информации о том, что Claude Code удаляет.

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

Аутентификация mTLS

Способ настройки сертификатов клиента для экспортера OTLP зависит от протокола OTLP, используемого для этого сигнала, установленного через OTEL_EXPORTER_OTLP_PROTOCOL или переопределение для каждого сигнала. Одна и та же конфигурация применяется к метрикам, логам и трассировкам.

Для grpc SDK OpenTelemetry читает стандартные переменные OTLP напрямую, поэтому существующие конфигурации, которые устанавливают переменные метрик для каждого сигнала, продолжают работать. На машинах с управляемыми параметрами Claude Code может удалить установленные разработчиком учетные данные и endpoints для каждого сигнала при запуске.

Управление кардинальностью метрик

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

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

Traces (beta)

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

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

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

claude_code.llm_request

Каждая повторная попытка также записывается как событие span gen_ai.request.attempt с атрибутами attempt и client_request_id.

claude_code.tool

Когда OTEL_LOG_TOOL_CONTENT=1, этот span также записывает событие span tool.output, чьи атрибуты содержат входные и выходные тела инструмента, усеченные на лимит содержимого (60 КБ по умолчанию) на атрибут.

claude_code.tool.blocked_on_user

claude_code.tool.execution

claude_code.hook

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

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

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

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

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

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

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

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

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

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

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

Если помощник не удается или выводит содержимое, которое не соответствует этим требованиям, Claude Code сообщает об ошибке в:

• выводе /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

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

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

Для экспорта только метрик, без событий или логов:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Для экспорта только событий и логов, без метрик:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

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

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

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

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

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

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

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

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

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

Метрики

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

Когда 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, локальный пользовательский интерфейс, запущенный пользователем, а не разговорный сеанс. Отфильтруйте по этому значению, чтобы отделить запуски процесса UI от разговорных сеансов в ваших панелях управления.

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

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

Атрибуты:

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

Счетчик pull request

Увеличивается при создании pull request или merge request через команду shell или инструмент MCP.

Атрибуты:

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

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

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

Атрибуты:

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

Счетчик затрат

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

Атрибуты:

• Все стандартные атрибуты
• model: Идентификатор модели (например, "claude-sonnet-5")
• query_source: Категория подсистемы, которая выдала запрос. Один из "main", "subagent" или "auxiliary"
• speed: "fast" когда запрос использовал быстрый режим. Отсутствует в противном случае
• effort: Уровень усилий, применяемый к запросу: "low", "medium", "high", "xhigh" или "max". Отсутствует, когда модель не поддерживает усилия.
• agent.name: Тип подагента, который выдал запрос. Встроенные имена агентов и агенты из официальных плагинов маркетплейса появляются как есть. Другие определяемые пользователем имена агентов заменяются на "custom". Отсутствует, когда запрос не был выдан именованным типом подагента.
• skill.name: Навык, активный для запроса, установленный инструментом Skill, командой / или унаследованный порожденным подагентом. Встроенные, поставляемые, определяемые пользователем и навыки плагинов официального маркетплейса появляются как есть. Навыки плагинов третьих сторон заменяются на "third-party". Отсутствует, когда нет активного навыка.
• plugin.name: Владельцы плагина, когда активный навык или подагент предоставляются плагином. Имена плагинов официального маркетплейса появляются как есть. Имена плагинов третьих сторон заменяются на "third-party". Отсутствует, когда ни навык, ни подагент не имеют владельца плагина.
• marketplace.name: Маркетплейс, из которого был установлен владельцы плагин. Выдается только для плагинов официального маркетплейса. Отсутствует в противном случае.
• mcp_server.name: MCP сервер, чей результат инструмента этот запрос потребил. Встроенные, claude.ai-проксированные и официальные имена серверов реестра появляются как есть. Пользовательские имена серверов заменяются на "custom". Отсутствует, когда запрос не потребил результат инструмента MCP. До 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. Это возвращает событие 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
• 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 запроса Anthropic API из заголовка ответа request-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
  • Для инструмента bash рабочей области приложения для рабочего стола, который также сообщает 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 K символами. Применяется ко всем инструментам, включая инструменты 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 запроса Anthropic API из заголовка ответа request-id, такой как "req_011...". Присутствует только, когда API возвращает его.
• 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". Отсутствует, когда модель не поддерживает усилия.
• 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 запроса Anthropic API из заголовка ответа request-id, такой как "req_011...". Присутствует только, когда API возвращает его.
• 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: Уровень усилий, применяемый к запросу. Отсутствует, когда модель не поддерживает усилия.
• 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 запроса Anthropic API из заголовка ответа request-id, такой как "req_011...". Присутствует только, когда API возвращает его.
• query_source: Подсистема, которая выдала запрос, такая как "repl_main_thread", "compact" или имя подагента. Определения см. в разделе api_request.
• speed: Либо "fast" когда активен Fast mode, либо "normal"
• attempt: Номер попытки повтора. Первая попытка это 1.
• effort: Уровень усилий, применяемый к запросу. Отсутствует, когда модель не поддерживает усилия.
• 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")

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

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

Имя события: 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 запроса Anthropic API из заголовка ответа request-id, такой как "req_011...". Присутствует только, когда API возвращает его.

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

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

Имя события: 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", когда сам запрос на запрос разрешения не удается, например когда callback 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, выходе из Plan Mode или проверке gate автоматического режима.

Имя события: 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, Google Cloud's Agent Platform или 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, так и из интерактивного UI /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. До 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" когда навык является навыком workflow. Отсутствует в противном случае
• plugin.name (когда OTEL_LOG_TOOL_DETAILS=1 или плагин из официального маркетплейса): Имя владельца плагина, когда навык предоставляется плагином
• marketplace.name (когда OTEL_LOG_TOOL_DETAILS=1 или плагин из официального маркетплейса): Маркетплейс владельца плагина, когда навык предоставляется плагином

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

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

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

Атрибуты:

• Все стандартные атрибуты
• event.name: "at_mention"
• event.timestamp: Временная метка ISO 8601
• event.sequence: счетчик для каждого процесса для упорядочивания событий, описанный в разделе Атрибуты корреляции событий
• mention_type: Тип упоминания ("file", "directory", "agent", "mcp_resource", "peer"). Значение "peer" означает, что вы упомянули один из ваших других сеансов Claude Code. Требует Claude Code v2.1.232 или позже
• success: Было ли упоминание успешно разрешено ("true" или "false")

Событие исчерпания повторных попыток 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): строка matcher из конфигурации 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, включая matcher, такой как "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: JSON-сериализованная конфигурация hook. Включается только, когда включены как детальная бета-трассировка, так и 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, включая matcher
• num_hooks: Количество соответствующих команд hook
• num_success: Количество, которые завершились успешно
• num_blocking: Количество, которые вернули решение блокировки
• num_non_blocking_error: Количество, которые не удались без блокировки
• num_cancelled: Количество, отмененные до завершения
• total_duration_ms: Длительность в реальном времени всех соответствующих hooks
• managed_only: "true" когда разрешены только управляемые политики hooks
• hook_source: "policySettings" или "merged"
• safe_mode: "true" когда сеанс был запущен с --safe-mode, "false" в противном случае. Требует Claude Code v2.1.169 или позже
• hook_definitions: JSON-сериализованная конфигурация hook. Включается только, когда включены как детальная бета-трассировка, так и 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 или опцией SDK settingSources, и ни один включенный источник не предоставляет 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: Количество артефактов, которые очистка файлов сеанса удалила: транскрипты плюс файлы-спутники для каждого сеанса, такие как sidecars, записи и результаты инструментов
• artifacts_deleted: Общее количество элементов, которые очистка удалила по всем каталогам данных, которые она охватывает, включая файлы сеанса. Некоторые очистки подсчитывают целое удаленное дерево каталогов как один элемент и несколько проходов очистки не вносят вклад в счетчик, поэтому рассматривайте значение как нижний предел, а не точный подсчет файлов
• files_retained_fresh: Файлы, проверенные и оставленные на месте, потому что они все еще находятся в пределах периода удержания. Только очистки для каждого файла подсчитывают эти, поэтому значение является нижним пределом; ненулевое значение является нормальным устойчивым состоянием
• files_past_cutoff: Файлы, старше чем период удержания, которые очистка не смогла удалить, например из-за ошибки разрешения или файла, удерживаемого открытым. Значение выше нуля означает, что файлы пережили настроенный период удержания; ноль не является доказательством того, что они не были, потому что неудачное удаление целого каталога учитывается в error_count вместо этого
• error_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 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 затем производит структурированные события, которые несут имя сервера, имя инструмента и аргументы вызова вместе со стандартными атрибутами идентификации:

Без 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", поэтому серверы, предоставляемые плагинами, остаются различимыми без подробного логирования

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

При построении правил обнаружения найдите сигнал, который вы хотите отслеживать, и запросите ваш бэкенд для соответствующего события и атрибутов:

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 --debug и проверьте журнал отладки на ошибки экспорта [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
• Текст ответа помощника не собирается по умолчанию. Записывается только длина ответа. Чтобы включить текст ответа, установите 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 команд
  • Span трассировки включают тот же атрибут tool_input и атрибуты, полученные из входных данных, такие как file_path, с тем же усечением, что и tool_input
• Входные и выходные данные инструмента не логируются в span событиях по умолчанию. Чтобы включить их, установите OTEL_LOG_TOOL_CONTENT=1. Когда включено, события span включают полное содержимое входных и выходных данных инструмента, усеченное на лимит содержимого (60 КБ по умолчанию) на атрибут. Это может включать содержимое исходного файла из результатов инструмента Read и выходные данные команды Bash. Настройте ваш бэкенд телеметрии для фильтрации или редактирования этих атрибутов по мере необходимости
• Тела запроса и ответа 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 на Amazon Bedrock

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