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

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

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

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

Добавьте в ваш .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 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Количество запущенных сеансов CLIcount
claude_code.lines_of_code.countКоличество строк кода, которые были измененыcount
claude_code.pull_request.countКоличество созданных запросов на слияниеcount
claude_code.commit.countКоличество созданных коммитов gitcount
claude_code.cost.usageСтоимость сеанса Claude CodeUSD
claude_code.token.usageКоличество использованных токеновtokens
claude_code.code_edit_tool.decisionКоличество решений о разрешении инструмента редактирования кодаcount
claude_code.active_time.totalОбщее активное время в секундахs

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

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

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

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

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

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

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

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

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

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

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

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

Увеличивается после каждого запроса 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).