Мониторинг

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

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

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

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

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

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

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

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

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

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

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

Traces (beta)

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

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

Spans скрывают текст пользовательской подсказки, детали входных данных инструмента и содержимое инструмента по умолчанию. Установите OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 и OTEL_LOG_TOOL_CONTENT=1 для их включения.

Когда трассировка активна, подпроцессы Bash и PowerShell автоматически наследуют переменную окружения TRACEPARENT, содержащую контекст трассировки W3C активного span выполнения инструмента. Это позволяет любому подпроцессу, который читает TRACEPARENT, родить свои собственные spans под той же трассировкой, обеспечивая сквозную распределенную трассировку через скрипты и команды, которые запускает Claude.

Когда трассировка активна и Claude Code подключен непосредственно к API Anthropic, каждый запрос модели несет заголовок W3C traceparent, установленный на контекст span claude_code.llm_request, и заголовок traceresponse API записывается как ссылка span. Вместе они соединяют spans Claude Code на стороне клиента с трассировкой на стороне сервера через любого совместимого посредника. Исходящие HTTP MCP запросы несут traceparent таким же образом. Заголовок не отправляется поставщикам третьих сторон.

По умолчанию заголовок traceparent на запросах модели и HTTP MCP отправляется только когда ANTHROPIC_BASE_URL не установлен или указывает на API Anthropic, так как некоторые прокси отклоняют неузнанные заголовки. Переменная TRACEPARENT подпроцесса управляется тем же переключателем для согласованности. Если вы запускаете Claude Code через пользовательский прокси ANTHROPIC_BASE_URL и хотите распространять контекст трассировки, установите CLAUDE_CODE_PROPAGATE_TRACEPARENT=1.

В Agent SDK и неинтерактивных сеансах, запущенных с -p, Claude Code также читает TRACEPARENT и TRACESTATE из своего собственного окружения при запуске каждого span взаимодействия. Это позволяет процессу встраивания передать свой активный контекст трассировки W3C в подпроцесс, так что spans Claude Code появляются как дочерние элементы трассировки вызывающей стороны. Интерактивные сеансы игнорируют входящий TRACEPARENT, чтобы избежать случайного наследования значений окружения из CI или контейнерных сред.

Иерархия span

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

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (требует детальную бета-трассировку)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (инструмент Agent) spans claude_code.llm_request / claude_code.tool подагента

В сеансах Agent SDK и claude -p, claude_code.interaction сам становится дочерним элементом span вызывающей стороны, когда TRACEPARENT установлен в окружении.

Атрибуты span

Каждый span несет стандартные атрибуты плюс атрибут 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 в дополнение к конфигурации экспортера трассировки выше. В интерактивных сеансах CLI это также требует, чтобы ваша организация была в списке разрешений для функции. Сеансы Agent SDK и неинтерактивные сеансы -p не имеют ограничений. Он не выдается, когда установлен только CLAUDE_CODE_ENHANCED_TELEMETRY_BETA.

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

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

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

Добавьте в ваш .claude/settings.json:

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_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 сообщает об ошибке в:

• выводе /doctor
• журнале отладки при запуске с --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. Поскольку большинство бэкендов метрик предоставляют атрибуты точек данных как запрашиваемые метки, вы можете группировать и фильтровать метрики по вашим пользовательским ключам напрямую. Пользовательские ключи никогда не переопределяют стандартные атрибуты, такие как user.id или session.id: когда ключ конфликтует, Claude Code сохраняет встроенное значение.

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

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

Установите эти переменные окружения перед запуском claude. Каждый блок показывает полную конфигурацию для другого экспортера или сценария развертывания:

# Отладка консоли (интервалы 1 секунда)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

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

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Несколько экспортеров
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Разные endpoints/бэкенды для метрик и логов
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

# Только метрики (без событий/логов)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Только события/логи (без метрик)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

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

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

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

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

• prompt.id: UUID, коррелирующий пользовательскую подсказку со всеми последующими событиями до следующей подсказки. См. Атрибуты корреляции событий.
• workspace.host_paths: каталоги рабочей области хоста, выбранные в приложении для рабочего стола, как массив строк

Метрики

Claude Code экспортирует следующие метрики:

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

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

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

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

Атрибуты:

• Все стандартные атрибуты
• start_type: Как был запущен сеанс. Один из "fresh", "resume" или "continue"

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

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

Атрибуты:

• Все стандартные атрибуты
• type: ("added", "removed")
• model: Идентификатор модели для модели, которая внесла изменение (например, "claude-sonnet-4-6"). Требует Claude Code v2.1.172 или позже

Счетчик pull request

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

Атрибуты:

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

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

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

Атрибуты:

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

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

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

Атрибуты:

• Все стандартные атрибуты
• model: Идентификатор модели (например, "claude-sonnet-4-6")
• 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 не запустился.
• mcp_tool.name: Инструмент MCP, который запустился в ходе, который произвел этот запрос, с тем же редактированием, что и mcp_server.name. Отсутствует, когда инструмент MCP не запустился.

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

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

Атрибуты:

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

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

Увеличивается, когда пользователь принимает или отклоняет использование инструмента 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, которые произошли при обработке этой подсказки.

Событие пользовательской подсказки

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

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

Атрибуты:

• Все стандартные атрибуты
• event.name: "user_prompt"
• event.timestamp: Временная метка ISO 8601
• event.sequence: монотонно возрастающий счетчик для упорядочивания событий в сеансе
• prompt_length: Длина подсказки
• prompt: Содержимое подсказки (скрыто по умолчанию, включите с помощью OTEL_LOG_USER_PROMPTS=1)
• command_name: Имя команды, когда подсказка вызывает одну. Встроенные и поставляемые имена команд, такие как compact или debug, выдаются как есть; псевдонимы, такие как reset, выдаются как введено, а не как каноническое имя. Пользовательские, плагин и MCP имена команд сворачиваются в custom или mcp, если не установлен OTEL_LOG_TOOL_DETAILS=1
• command_source: Происхождение команды, когда присутствует: builtin, custom или mcp. Команды, предоставляемые плагинами, сообщают как custom

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

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

Имя события: 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)
• tool_parameters (когда OTEL_LOG_TOOL_DETAILS=1): JSON строка, содержащая параметры, специфичные для инструмента:
  • Для инструмента Bash: включает bash_command, full_command, timeout, description, dangerouslyDisableSandbox и git_commit_id (SHA коммита, когда команда git commit успешна)
  • Для инструмента WorkspaceBash: включает bash_command, full_command, timeout
  • Для инструментов MCP: включает mcp_server_name, mcp_tool_name
  • Для инструмента Skill: включает skill_name
  • Для инструмента Agent или устаревшего инструмента Task: включает subagent_type
• tool_input (когда OTEL_LOG_TOOL_DETAILS=1): JSON-сериализованные аргументы инструмента. Отдельные значения более 512 символов усекаются, и полная нагрузка ограничена примерно 4 K символами. Применяется ко всем инструментам, включая инструменты MCP.

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

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

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

Атрибуты:

• Все стандартные атрибуты
• event.name: "api_request"
• event.timestamp: Временная метка ISO 8601
• event.sequence: монотонно возрастающий счетчик для упорядочивания событий в сеансе
• model: Используемая модель (например, "claude-sonnet-4-6")
• cost_usd: Приблизительная стоимость в USD
• duration_ms: Длительность запроса в миллисекундах
• input_tokens: Количество входных токенов
• output_tokens: Количество выходных токенов
• cache_read_tokens: Количество токенов, прочитанных из кэша
• cache_creation_tokens: Количество токенов, использованных для создания кэша
• request_id: ID запроса Anthropic API из заголовка ответа request-id, такой как "req_011...". Присутствует только, когда API возвращает его.
• speed: "fast" или "normal", указывающий, был ли активен быстрый режим
• query_source: Подсистема, которая выдала запрос, такая как "repl_main_thread", "compact" или имя подагента
• effort: Уровень усилий, применяемый к запросу: "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-4-6")
• error: Сообщение об ошибке
• status_code: HTTP код состояния в виде числа. Отсутствует для ошибок, не связанных с HTTP, таких как сбои соединения.
• duration_ms: Длительность запроса в миллисекундах
• attempt: Общее количество попыток, включая исходный запрос (1 означает, что повторных попыток не было)
• request_id: ID запроса Anthropic API из заголовка ответа request-id, такой как "req_011...". Присутствует только, когда API возвращает его.
• speed: "fast" или "normal", указывающий, был ли активен быстрый режим
• query_source: Подсистема, которая выдала запрос, такая как "repl_main_thread", "compact" или имя подагента
• effort: Уровень усилий, применяемый к запросу. Отсутствует, когда модель не поддерживает усилия.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Атрибуция навыка, плагина, агента и MCP для запроса. Определения и поведение редактирования см. в разделе Счетчик затрат.

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

Логируется, когда запрос API возвращает stop_reason: "refusal". Отказы поступают в успешном потоке ответов, а не как ошибка HTTP, поэтому событие 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 возвращает его.

Событие тела запроса 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"
• source: Источник решения:
  • "config": Решено автоматически без запроса, на основе параметров проекта, правил разрешения или запрета в личных параметрах пользователя, корпоративной управляемой политики, флагов --allowedTools или --disallowedTools, активного режима разрешений, разрешения в области сеанса из более ранней подсказки в том же интерактивном сеансе CLI, или потому что инструмент по своей природе безопасен. Событие не указывает, какой из этих источников совпал.
  • "hook": Hook PreToolUse или PermissionRequest вернул решение.
  • "user_permanent": Выдается, когда пользователь выбрал "Да, и больше не спрашивать для ..." при запросе разрешения, что сохраняет правило разрешения в его личных параметрах. В интерактивном CLI это выдается только для самого этого выбора; более поздние вызовы, которые соответствуют сохраненному правилу, выдают "config" вместо этого. В Agent SDK или неинтерактивных сеансах -p как начальный выбор, так и более поздние совпадения правил выдают "user_permanent". Рассматривается как принятие.
  • "user_temporary": Выдается, когда пользователь выбрал "Да" при запросе разрешения для одноразового одобрения, или выбрал один из вариантов "... во время этого сеанса" на запросе редактирования или чтения файла. В интерактивном CLI это выдается только для самого выбора; более поздние вызовы, разрешенные этим разрешением в области сеанса, выдают "config" вместо этого. В Agent SDK или неинтерактивных сеансах -p как выбор, так и более поздние совпадения выдают "user_temporary". Рассматривается как принятие.
  • "user_abort": Выдается, когда пользователь отклонил запрос разрешения без ответа. Рассматривается как отклонение.
  • "user_reject": Выдается, когда пользователь выбрал "Нет" при запросе. В интерактивном CLI это выдается только для самого этого выбора; вызовы, которые соответствуют правилу отказа в личных параметрах пользователя, выдают "config" вместо этого. В Agent SDK или неинтерактивных сеансах -p вызовы, которые соответствуют правилу отказа в личных параметрах, выдают "user_reject". Рассматривается как отклонение.
• tool_parameters (когда OTEL_LOG_TOOL_DETAILS=1): JSON строка, содержащая параметры, специфичные для инструмента. Та же форма, что и Событие результата инструмента, минус поля после выполнения, такие как git_commit_id. Значения могут отличаться от tool_result для принятого вызова, если решение о разрешении переписывает входные данные инструмента через updatedInput. Используйте этот атрибут, чтобы увидеть, какая команда была отклонена, когда decision это "reject".
  • Для инструмента Bash: включает bash_command, full_command, timeout, description, dangerouslyDisableSandbox
  • Для инструмента WorkspaceBash: включает bash_command, full_command, timeout
  • Для инструментов MCP: включает mcp_server_name, mcp_tool_name
  • Для инструмента Skill: включает skill_name
  • Для инструмента Agent или устаревшего инструмента Task: включает subagent_type

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

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

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

Атрибуты:

• Все стандартные атрибуты
• 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): Стабильный хеш имени плагина и маркетплейса для группировки событий по плагину без раскрытия имени
• plugin.name (когда is_plugin это true): Имя плагина, который предоставляет сервер. Для плагинов третьих сторон это буквальная строка "third-party", если не установлен OTEL_LOG_TOOL_DETAILS=1; это защищает имена плагинов третьих сторон от появления в логах по умолчанию. Плагины из официальных источников Anthropic всегда идентифицируются по имени. Атрибуты plugin_id_hash и plugin.name поступают на ваш собственный бэкенд мониторинга и не отправляются в Anthropic
• server_name (когда OTEL_LOG_TOOL_DETAILS=1): Настроенное имя сервера
• error (когда OTEL_LOG_TOOL_DETAILS=1): Полное сообщение об ошибке при сбое подключения

Событие внутренней ошибки

Логируется, когда Claude Code перехватывает неожиданную внутреннюю ошибку. Записываются только имя класса ошибки и код в стиле errno. Сообщение об ошибке и трассировка стека никогда не включаются. Это событие не выдается при запуске против Bedrock, Vertex или Foundry, или когда установлен DISABLE_ERROR_REPORTING.

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

Атрибуты:

• Все стандартные атрибуты
• 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", "org", "user-local" или "default-bundle"
• enabled_via: как плагин был включен: "default-enable", "org-policy", "seed-mount" или "user-install"
• plugin_id_hash: детерминированный хеш имени плагина и маркетплейса, отправляемый только на ваш настроенный экспортер. Позволяет вам подсчитать, сколько различных плагинов третьих сторон загружено в вашем парке, без записи их имен
• has_hooks: предоставляет ли плагин hooks
• has_mcp: предоставляет ли плагин MCP серверы
• host_owned_mcp: true когда хост SDK управляет подключениями MCP этого плагина и Claude Code пропустил чтение конфигурации MCP сервера плагина, false в противном случае. Требует Claude Code v2.1.172 или позже
• skill_path_count: количество каталогов навыков, которые объявляет плагин
• command_path_count: количество каталогов команд, которые объявляет плагин
• agent_path_count: количество каталогов агентов, которые объявляет плагин
• safe_mode: "true" когда сеанс был запущен с --safe-mode, "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")
• 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"): детерминированный хеш имени плагина и маркетплейса, отправляемый только на ваш настроенный экспортер. Позволяет вам подсчитать различные участвующие плагины без записи их имен

Событие начала выполнения 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 или позже

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

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

Имя события: 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. Отфильтруйте по этому атрибуту, чтобы подтвердить, что переопределение применяется в вашем парке

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

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

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

Мониторинг затрат

Метрика claude_code.cost.usage помогает с:

• Отслеживанием тенденций использования по командам или отдельным лицам
• Выявлением сеансов с высоким использованием для оптимизации
• Атрибуцией расходов конкретным навыкам, плагинам или типам подагентов через атрибуты skill.name, plugin.name и agent.name

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

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

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

Все метрики можно сегментировать по стандартным атрибутам. Атрибут model доступен на claude_code.token.usage, claude_code.cost.usage и {/* min-version: 2.1.172 */}начиная с версии 2.1.172, claude_code.lines_of_code.count. Разбивки по моделям для коммитов можно только приблизительно оценить, объединив данные с метриками токенов или затрат по session.id, поскольку один сеанс может охватывать несколько моделей.

Обнаружение исчерпания повторных попыток

Claude Code повторяет неудачные запросы API внутри и выдает одно событие claude_code.api_error только после того, как сдается, поэтому само событие является терминальным сигналом для этого запроса. Промежуточные повторные попытки не логируются как отдельные события.

Атрибут attempt на событии записывает, сколько попыток было сделано в общей сложности. Значение больше CLAUDE_CODE_MAX_RETRIES (по умолчанию 10) указывает, что запрос исчерпал все повторные попытки при переходной ошибке. Более низкое значение указывает на неповторяемую ошибку, такую как ответ 400.

Чтобы различить сеанс, который восстановился, от того, который застопорился, сгруппируйте события по 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.

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

Когда Claude Code аутентифицируется с прямым ключом API или против Bedrock, Vertex AI или Microsoft Foundry, в сеансе нет учетной записи Claude и только user.id и session.id заполняются. В этих развертываниях прикрепите идентификацию пользователя самостоятельно с помощью OTEL_RESOURCE_ATTRIBUTES, установленного для каждого пользователя через файл управляемых параметров или оболочку запуска:

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: сохраняет tool_name и mcp_server_scope, опускает mcp_server_name, mcp_tool_name и аргументы
• tool_decision: сохраняет tool_name, опускает tool_parameters
• mcp_server_connection: опускает server_name и сообщение об ошибке, но сохраняет is_plugin, plugin_id_hash и plugin.name, с именами плагинов, не относящихся к Anthropic, отредактированными на буквальное значение "third-party", поэтому серверы, предоставляемые плагинами, остаются различимыми без подробного логирования

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

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

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

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

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

Для метрик

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

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

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

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

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

• Системы распределенной трассировки (например, Jaeger, Zipkin, Grafana Tempo): Визуализация span, водопады запросов, анализ задержки
• Полнофункциональные платформы наблюдаемости (например, Honeycomb, Datadog, Grafana Cloud): Поиск трассировок и корреляция с метриками и логами

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

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

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

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

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

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

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

• Экспорт OpenTelemetry на ваш бэкенд является добровольным и требует явной конфигурации. Информацию об отдельной операционной телеметрии Anthropic и о том, как её отключить, см. в разделе Data usage
• Содержимое файлов в исходном виде и фрагменты кода не включаются в метрики или события. Span трассировок — это отдельный путь данных: см. пункт OTEL_LOG_TOOL_CONTENT ниже
• При аутентификации через OAuth user.email включается в атрибуты телеметрии. Если это вызывает беспокойство для вашей организации, работайте с вашим бэкендом телеметрии для фильтрации или редактирования этого поля
• Содержимое пользовательской подсказки не собирается по умолчанию. Записывается только длина подсказки. Чтобы включить содержимое подсказки, установите OTEL_LOG_USER_PROMPTS=1
• Аргументы входных данных инструмента и параметры не логируются по умолчанию. Чтобы включить их, установите OTEL_LOG_TOOL_DETAILS=1. Эти данные отправляются только на endpoint OTEL, который вы настраиваете, никогда на Anthropic. Аргументы могут по-прежнему содержать конфиденциальные значения, поэтому настройте ваш бэкенд телеметрии для фильтрации или редактирования этих атрибутов по мере необходимости. Когда включено:
  • События tool_result и tool_decision включают атрибут tool_parameters с командами Bash, именами MCP сервера и инструмента и именами навыков. Поля, такие как full_command, выдаются неусеченными
  • События tool_result дополнительно включают атрибут tool_input с путями к файлам, URL-адресами, шаблонами поиска и другими аргументами. Отдельные значения более 512 символов усекаются, и общее количество ограничено примерно 4 K символами
  • События user_prompt включают буквальное command_name для пользовательских, плагин и MCP команд
  • Span трассировки включают тот же атрибут tool_input и атрибуты, полученные из входных данных, такие как file_path, с тем же усечением, что и tool_input
• Входные и выходные данные инструмента не логируются в span событиях по умолчанию. Чтобы включить их, установите OTEL_LOG_TOOL_CONTENT=1. Когда включено, события span включают полное содержимое входных и выходных данных инструмента, усеченное на 60 КБ на span. Это может включать содержимое исходного файла из результатов инструмента Read и выходные данные команды Bash. Настройте ваш бэкенд телеметрии для фильтрации или редактирования этих атрибутов по мере необходимости
• Тела запроса и ответа Anthropic Messages API в исходном виде не логируются по умолчанию. Чтобы включить их, установите OTEL_LOG_RAW_API_BODIES. С =1 каждый вызов API выдает события логов api_request_body и api_response_body, чей атрибут body является JSON-сериализованной нагрузкой, усеченной на 60 КБ. С =file:<dir>, неусеченные тела записываются в файлы .request.json и .response.json в этом каталоге, и события несут путь body_ref вместо встроенного тела. Отправьте каталог с коллектором логов или sidecar, а не через поток телеметрии. В обоих режимах тела содержат полную историю разговора (системная подсказка, каждый предыдущий ход пользователя и помощника, результаты инструментов), поэтому включение этого подразумевает согласие со всем, что раскрыли бы другие флаги содержимого OTEL_LOG_*. Содержимое расширенного мышления Claude всегда скрыто из этих тел независимо от других параметров

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

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