Мониторинг - Claude Code Docs

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

Поддержка OpenTelemetry в настоящее время находится в бета-версии, и детали могут измениться.

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

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

# 1. Включить телеметрию
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Выбрать экспортеры (оба опциональны - настройте только необходимое)
export OTEL_METRICS_EXPORTER=otlp       # Опции: otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # Опции: otlp, console

# 3. Настроить конечную точку OTLP (для экспортера OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Установить аутентификацию (если требуется)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Для отладки: сократить интервалы экспорта
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 секунд (по умолчанию: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 секунд (по умолчанию: 5000ms)

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

Интервалы экспорта по умолчанию составляют 60 секунд для метрик и 5 секунд для логов. Во время настройки вы можете использовать более короткие интервалы для отладки. Помните, что нужно сбросить эти значения для использования в производстве.

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

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

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

macOS: /Library/Application Support/ClaudeCode/managed-settings.json
Linux и WSL: /etc/claude-code/managed-settings.json
Windows: C:\ProgramData\ClaudeCode\managed-settings.json

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

{
  "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.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

Управляемые параметры могут распространяться через MDM (Mobile Device Management) или другие решения для управления устройствами. Переменные окружения, определенные в файле управляемых параметров, имеют высокий приоритет и не могут быть переопределены пользователями.

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

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

Переменная окружения	Описание	Примеры значений
`CLAUDE_CODE_ENABLE_TELEMETRY`	Включает сбор телеметрии (обязательно)	`1`
`OTEL_METRICS_EXPORTER`	Тип(ы) экспортера метрик (разделены запятыми)	`console`, `otlp`, `prometheus`
`OTEL_LOGS_EXPORTER`	Тип(ы) экспортера логов/событий (разделены запятыми)	`console`, `otlp`
`OTEL_EXPORTER_OTLP_PROTOCOL`	Протокол для экспортера OTLP (все сигналы)	`grpc`, `http/json`, `http/protobuf`
`OTEL_EXPORTER_OTLP_ENDPOINT`	Конечная точка сборщика OTLP (все сигналы)	`http://localhost:4317`
`OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`	Протокол для метрик (переопределяет общий)	`grpc`, `http/json`, `http/protobuf`
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	Конечная точка метрик OTLP (переопределяет общую)	`http://localhost:4318/v1/metrics`
`OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`	Протокол для логов (переопределяет общий)	`grpc`, `http/json`, `http/protobuf`
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Конечная точка логов OTLP (переопределяет общую)	`http://localhost:4318/v1/logs`
`OTEL_EXPORTER_OTLP_HEADERS`	Заголовки аутентификации для OTLP	`Authorization=Bearer token`
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY`	Ключ клиента для аутентификации mTLS	Путь к файлу ключа клиента
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE`	Сертификат клиента для аутентификации mTLS	Путь к файлу сертификата клиента
`OTEL_METRIC_EXPORT_INTERVAL`	Интервал экспорта в миллисекундах (по умолчанию: 60000)	`5000`, `60000`
`OTEL_LOGS_EXPORT_INTERVAL`	Интервал экспорта логов в миллисекундах (по умолчанию: 5000)	`1000`, `10000`
`OTEL_LOG_USER_PROMPTS`	Включить логирование содержимого пользовательских подсказок (по умолчанию: отключено)	`1` для включения

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

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

Переменная окружения	Описание	Значение по умолчанию	Пример отключения
`OTEL_METRICS_INCLUDE_SESSION_ID`	Включить атрибут session.id в метрики	`true`	`false`
`OTEL_METRICS_INCLUDE_VERSION`	Включить атрибут app.version в метрики	`false`	`true`
`OTEL_METRICS_INCLUDE_ACCOUNT_UUID`	Включить атрибут user.account_uuid в метрики	`true`	`false`

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

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

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

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

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

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

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

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

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

Важные ограничения

Заголовки загружаются только при запуске, а не во время выполнения. Это связано с ограничениями архитектуры экспортера OpenTelemetry. Для сценариев, требующих частого обновления токена, используйте OpenTelemetry Collector в качестве прокси, который может обновлять свои собственные заголовки.

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

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

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

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

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

Важные требования к форматированию для OTEL_RESOURCE_ATTRIBUTES:Переменная окружения OTEL_RESOURCE_ATTRIBUTES следует спецификации W3C Baggage, которая имеет строгие требования к форматированию:

Пробелы не допускаются: Значения не могут содержать пробелы. Например, user.organizationName=My Company недопустимо
Формат: Должны быть пары ключ=значение, разделенные запятыми: key1=value1,key2=value2
Допустимые символы: Только символы US-ASCII, исключая управляющие символы, пробелы, двойные кавычки, запятые, точки с запятой и обратные слэши
Специальные символы: Символы вне допустимого диапазона должны быть закодированы в процентах

Примеры:

# ❌ Недопустимо - содержит пробелы
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Допустимо - используйте подчеркивания или camelCase вместо этого
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Допустимо - закодируйте специальные символы в процентах, если необходимо
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Примечание: Заключение всей пары ключ=значение в кавычки (например, "key=value with spaces") не поддерживается спецификацией OpenTelemetry и приведет к тому, что атрибуты будут иметь префикс с кавычками.

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

# Отладка консоли (интервалы 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

# Разные конечные точки/бэкенды для метрик и логов
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.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317

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

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

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

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

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

Атрибут	Описание	Управляется
`session.id`	Уникальный идентификатор сеанса	`OTEL_METRICS_INCLUDE_SESSION_ID` (по умолчанию: true)
`app.version`	Текущая версия Claude Code	`OTEL_METRICS_INCLUDE_VERSION` (по умолчанию: false)
`organization.id`	UUID организации (при аутентификации)	Всегда включается, когда доступно
`user.account_uuid`	UUID учетной записи (при аутентификации)	`OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (по умолчанию: true)
`terminal.type`	Тип терминала (например, `iTerm.app`, `vscode`, `cursor`, `tmux`)	Всегда включается при обнаружении

Метрики

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

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

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

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

Увеличивается в начале каждого сеанса. Атрибуты:

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

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

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

Все стандартные атрибуты
type: ("added", "removed")

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

Увеличивается при создании запросов на слияние через Claude Code. Атрибуты:

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

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

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

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

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

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

Все стандартные атрибуты
model: Идентификатор модели (например, “claude-sonnet-4-5-20250929”)

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

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

Все стандартные атрибуты
type: ("input", "output", "cacheRead", "cacheCreation")
model: Идентификатор модели (например, “claude-sonnet-4-5-20250929”)

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

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

Все стандартные атрибуты
tool: Имя инструмента ("Edit", "Write", "NotebookEdit")
decision: Решение пользователя ("accept", "reject")
language: Язык программирования отредактированного файла (например, "TypeScript", "Python", "JavaScript", "Markdown"). Возвращает "unknown" для неизвестных расширений файлов.

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

Отслеживает фактическое время активного использования Claude Code (не время простоя). Эта метрика увеличивается во время взаимодействия пользователя, такого как ввод подсказок или получение ответов. Атрибуты:

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

События

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

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

Регистрируется, когда пользователь отправляет подсказку. Имя события: claude_code.user_prompt Атрибуты:

Все стандартные атрибуты
event.name: "user_prompt"
event.timestamp: Временная метка ISO 8601
prompt_length: Длина подсказки
prompt: Содержимое подсказки (скрыто по умолчанию, включить с помощью OTEL_LOG_USER_PROMPTS=1)

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

Регистрируется при завершении выполнения инструмента. Имя события: claude_code.tool_result Атрибуты:

Все стандартные атрибуты
event.name: "tool_result"
event.timestamp: Временная метка ISO 8601
tool_name: Имя инструмента
success: "true" или "false"
duration_ms: Время выполнения в миллисекундах
error: Сообщение об ошибке (если не удалось)
decision: Либо "accept", либо "reject"
source: Источник решения - "config", "user_permanent", "user_temporary", "user_abort" или "user_reject"
tool_parameters: Строка JSON, содержащая параметры, специфичные для инструмента (если доступно)
- Для инструмента Bash: включает bash_command, full_command, timeout, description, sandbox

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

Регистрируется для каждого запроса API к Claude. Имя события: claude_code.api_request Атрибуты:

Все стандартные атрибуты
event.name: "api_request"
event.timestamp: Временная метка ISO 8601
model: Используемая модель (например, “claude-sonnet-4-5-20250929”)
cost_usd: Приблизительная стоимость в USD
duration_ms: Продолжительность запроса в миллисекундах
input_tokens: Количество входных токенов
output_tokens: Количество выходных токенов
cache_read_tokens: Количество токенов, прочитанных из кэша
cache_creation_tokens: Количество токенов, использованных для создания кэша

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

Регистрируется, когда запрос API к Claude не удается. Имя события: claude_code.api_error Атрибуты:

Все стандартные атрибуты
event.name: "api_error"
event.timestamp: Временная метка ISO 8601
model: Используемая модель (например, “claude-sonnet-4-5-20250929”)
error: Сообщение об ошибке
status_code: Код состояния HTTP (если применимо)
duration_ms: Продолжительность запроса в миллисекундах
attempt: Номер попытки (для повторных запросов)

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

Регистрируется, когда принимается решение о разрешении инструмента (принять/отклонить). Имя события: claude_code.tool_decision Атрибуты:

Все стандартные атрибуты
event.name: "tool_decision"
event.timestamp: Временная метка ISO 8601
tool_name: Имя инструмента (например, “Read”, “Edit”, “Write”, “NotebookEdit” и т. д.)
decision: Либо "accept", либо "reject"
source: Источник решения - "config", "user_permanent", "user_temporary", "user_abort" или "user_reject"

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

Метрики, экспортируемые Claude Code, предоставляют ценные сведения о закономерностях использования и производительности. Вот некоторые распространенные визуализации и анализы, которые вы можете создать:

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

Метрика	Возможность анализа
`claude_code.token.usage`	Разбить по `type` (input/output), пользователю, команде или модели
`claude_code.session.count`	Отслеживать внедрение и вовлеченность во времени
`claude_code.lines_of_code.count`	Измерить производительность, отслеживая добавления/удаления кода
`claude_code.commit.count` & `claude_code.pull_request.count`	Понять влияние на рабочие процессы разработки

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

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

Отслеживанием тенденций использования по командам или отдельным лицам
Выявлением сеансов с высоким использованием для оптимизации

Метрики затрат являются приблизительными. Для официальных данных о выставлении счетов обратитесь к поставщику API (Claude Console, AWS Bedrock или Google Cloud Vertex).

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

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

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

Все метрики можно сегментировать по user.account_uuid, organization.id, session.id, model и app.version.

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

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

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

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

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

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

Для метрик:

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

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

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

Для организаций, требующих метрик 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.

Рассмотрения безопасности/конфиденциальности

Телеметрия является добровольной и требует явной конфигурации
Конфиденциальная информация, такая как ключи API или содержимое файлов, никогда не включается в метрики или события
Содержимое пользовательских подсказок скрыто по умолчанию - записывается только длина подсказки. Чтобы включить логирование пользовательских подсказок, установите OTEL_LOG_USER_PROMPTS=1

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

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

Администрирование

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

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

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

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

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

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

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

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

​Важные ограничения

​Поддержка многокомандной организации

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

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

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

​Метрики

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

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

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

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

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

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

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

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

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

​События

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

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

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

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

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

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

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

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

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

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

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

​Для метрик:

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

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

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

​Рассмотрения безопасности/конфиденциальности

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

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

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

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

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

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

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

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

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

Важные ограничения

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

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

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

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

Метрики

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

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

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

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

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

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

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

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

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

События

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

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

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

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

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

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

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

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

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

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

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

Для метрик:

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

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

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

Рассмотрения безопасности/конфиденциальности

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