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 секунд (по умолчанию: 60000мс)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 секунд (по умолчанию: 5000мс)

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

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

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

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

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

Файл управляемых настроек находится по адресу:

  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux: /etc/claude-code/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Заголовки аутентификации для OTLPAuthorization=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 в метрикиtruefalse
OTEL_METRICS_INCLUDE_VERSIONВключить атрибут app.version в метрикиfalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDВключить атрибут user.account_uuid в метрикиtruefalse

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

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

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

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

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

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

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

# Отладка в консоли (интервалы в 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 CodeOTEL_METRICS_INCLUDE_VERSION (по умолчанию: false)
organization.idUUID организации (при аутентификации)Всегда включается, когда доступно
user.account_uuidUUID аккаунта (при аутентификации)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Количество созданных pull request’овcount
claude_code.commit.countКоличество созданных git коммитовcount
claude_code.cost.usageСтоимость сессии Claude CodeUSD
claude_code.token.usageКоличество использованных токеновtokens
claude_code.code_edit_tool.decisionКоличество решений о разрешении инструмента редактирования кодаcount

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

Счетчик сессий

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

Атрибуты:

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

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

Атрибуты:

Счетчик Pull Request’ов

Увеличивается при создании pull request’ов через Claude Code.

Атрибуты:

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

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

Атрибуты:

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

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

Атрибуты:

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

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

Атрибуты:

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

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

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

Атрибуты:

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

События

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
  • name: Название инструмента
  • success: "true" или "false"
  • duration_ms: Время выполнения в миллисекундах
  • error: Сообщение об ошибке (если неудачно)

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

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

Название события: claude_code.api_request

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "api_request"
  • event.timestamp: Временная метка ISO 8601
  • model: Используемая модель (например, “claude-3-5-sonnet-20241022”)
  • 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-3-5-sonnet-20241022”)
  • error: Сообщение об ошибке
  • status_code: HTTP код состояния (если применимо)
  • duration_ms: Продолжительность запроса в миллисекундах
  • attempt: Номер попытки (для повторных запросов)

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

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

Название события: claude_code.tool_decision

Атрибуты:

  • Все стандартные атрибуты
  • event.name: "tool_decision"
  • event.timestamp: Временная метка ISO 8601
  • tool_name: Название инструмента (например, “Read”, “Edit”, “MultiEdit”, “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 помогает с:

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

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

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

Все метрики экспортируются с:

  • Название сервиса: claude-code
  • Версия сервиса: Текущая версия Claude Code
  • Название измерителя: com.anthropic.claude_code

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

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