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

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

• Уведомлении предупреждения в интерактивных сеансах, 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

Для отправки метрик и логов на разные 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, 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 удалённые хранилища одного репозитория создают идентичные значения:

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

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

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

Метрики

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

Когда 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.

Атрибуты:

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

Атрибуты:

• Все стандартные атрибуты
• 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): строка сопоставления из конфигурации 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: Сериализованная 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, включая сопоставление
• 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: Сериализованная 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 или опцией 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.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. При детальной бета-трассировке эта переменная действует шире, чем текст подсказки: она также управляет атрибутом 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 команд
  • Span трассировки включают тот же атрибут tool_input и атрибуты, полученные из входных данных, такие как file_path, с тем же усечением, что и tool_input
• Содержимое инструмента не логируется в span трассировок по умолчанию. Чтобы включить его, установите OTEL_LOG_TOOL_CONTENT=1. Span claude_code.tool затем содержит событие span tool.output с содержимым файлов в исходном виде и выходными данными команды Bash, усеченными на лимит содержимого (60 КБ по умолчанию) на атрибут. Содержимое инструмента также достигает 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).