​

OpenTelemetry в Claude Code

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

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

​

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

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

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

# 2. Выберите экспортер
export OTEL_METRICS_EXPORTER=otlp       # Варианты: otlp, prometheus, 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. Для отладки: уменьшите интервал экспорта (по умолчанию: 600000мс/10мин)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 секунд

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

Полные параметры конфигурации см. в спецификации 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_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

​

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

​

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

​

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

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

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

​

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

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

​

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

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

​

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

Все метрики имеют следующие стандартные атрибуты:

• session.id: Уникальный идентификатор сессии (контролируется OTEL_METRICS_INCLUDE_SESSION_ID)
• app.version: Текущая версия Claude Code (контролируется OTEL_METRICS_INCLUDE_VERSION)
• organization.id: UUID организации (при аутентификации)
• user.account_uuid: UUID аккаунта (при аутентификации, контролируется OTEL_METRICS_INCLUDE_ACCOUNT_UUID)

​

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

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

​

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

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

• Дополнительный атрибут: type ("added" или "removed")

​

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

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

​

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

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

​

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

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

• Дополнительный атрибут: model

​

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

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

• Дополнительные атрибуты: type ("input", "output", "cacheRead", "cacheCreation") и model

​

Интерпретация данных метрик

Эти метрики предоставляют информацию о моделях использования, продуктивности и затратах:

​

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

​

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

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

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

​

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

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

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

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

​

Соображения по бэкенду

Для метрик DAU/WAU/MAU выбирайте бэкенды, которые поддерживают эффективные запросы уникальных значений.

​

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

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

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

​

Соображения безопасности

• Телеметрия является опциональной и требует явной конфигурации
• Конфиденциальная информация, такая как API-ключи или содержимое файлов, никогда не включается в метрики