Мониторинг
Узнайте, как включить и настроить OpenTelemetry для Claude Code.
Claude Code поддерживает метрики и события OpenTelemetry (OTel) для мониторинга и наблюдаемости.
Все метрики представляют собой данные временных рядов, экспортируемые через стандартный протокол метрик OpenTelemetry, а события экспортируются через протокол логов/событий OpenTelemetry. Пользователь несет ответственность за обеспечение правильной настройки своих бэкендов метрик и логов, а также за то, чтобы детализация агрегации соответствовала их требованиям к мониторингу.
Поддержка OpenTelemetry в настоящее время находится в бета-версии, и детали могут изменяться.
Быстрый старт
Настройте OpenTelemetry с помощью переменных окружения:
Интервалы экспорта по умолчанию составляют 60 секунд для метрик и 5 секунд для логов. Во время настройки вы можете использовать более короткие интервалы для целей отладки. Не забудьте сбросить их для использования в продакшене.
Для полных опций конфигурации см. спецификацию OpenTelemetry.
Конфигурация администратора
Администраторы могут настроить параметры OpenTelemetry для всех пользователей через файл управляемых настроек. Это позволяет централизованно контролировать настройки телеметрии в организации. См. приоритет настроек для получения дополнительной информации о том, как применяются настройки.
Файл управляемых настроек находится по адресу:
- macOS:
/Library/Application Support/ClaudeCode/managed-settings.json
- Linux:
/etc/claude-code/managed-settings.json
Пример конфигурации управляемых настроек:
Управляемые настройки могут распространяться через 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 |
Эти переменные помогают контролировать кардинальность метрик, что влияет на требования к хранению и производительность запросов в вашем бэкенде метрик. Более низкая кардинальность обычно означает лучшую производительность и более низкие затраты на хранение, но менее детализированные данные для анализа.
Поддержка многокомандных организаций
Организации с несколькими командами или отделами могут добавлять пользовательские атрибуты для различения между разными группами, используя переменную окружения OTEL_RESOURCE_ATTRIBUTES
:
Эти пользовательские атрибуты будут включены во все метрики и события, позволяя вам:
- Фильтровать метрики по команде или отделу
- Отслеживать затраты по центру затрат
- Создавать панели мониторинга для конкретных команд
- Настраивать оповещения для конкретных команд
Примеры конфигураций
Доступные метрики и события
Стандартные атрибуты
Все метрики и события имеют эти стандартные атрибуты:
Атрибут | Описание | Контролируется |
---|---|---|
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 | Количество созданных pull request’ов | 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 |
Детали метрик
Счетчик сессий
Увеличивается в начале каждой сессии.
Атрибуты:
Счетчик строк кода
Увеличивается при добавлении или удалении кода.
Атрибуты:
- Все стандартные атрибуты
type
: ("added"
,"removed"
)
Счетчик Pull Request’ов
Увеличивается при создании pull request’ов через Claude Code.
Атрибуты:
Счетчик коммитов
Увеличивается при создании git коммитов через Claude Code.
Атрибуты:
Счетчик стоимости
Увеличивается после каждого API-запроса.
Атрибуты:
- Все стандартные атрибуты
model
: Идентификатор модели (например, “claude-3-5-sonnet-20241022”)
Счетчик токенов
Увеличивается после каждого 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 8601prompt_length
: Длина запросаprompt
: Содержимое запроса (по умолчанию скрыто, включается сOTEL_LOG_USER_PROMPTS=1
)
Событие результата инструмента
Логируется, когда инструмент завершает выполнение.
Название события: claude_code.tool_result
Атрибуты:
- Все стандартные атрибуты
event.name
:"tool_result"
event.timestamp
: Временная метка ISO 8601name
: Название инструментаsuccess
:"true"
или"false"
duration_ms
: Время выполнения в миллисекундахerror
: Сообщение об ошибке (если неудачно)
Событие API-запроса
Логируется для каждого API-запроса к Claude.
Название события: claude_code.api_request
Атрибуты:
- Все стандартные атрибуты
event.name
:"api_request"
event.timestamp
: Временная метка ISO 8601model
: Используемая модель (например, “claude-3-5-sonnet-20241022”)cost_usd
: Оценочная стоимость в USDduration_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 8601model
: Используемая модель (например, “claude-3-5-sonnet-20241022”)error
: Сообщение об ошибкеstatus_code
: HTTP код состояния (если применимо)duration_ms
: Продолжительность запроса в миллисекундахattempt
: Номер попытки (для повторных запросов)
Событие решения инструмента
Логируется, когда принимается решение о разрешении инструмента (принять/отклонить).
Название события: claude_code.tool_decision
Атрибуты:
- Все стандартные атрибуты
event.name
:"tool_decision"
event.timestamp
: Временная метка ISO 8601tool_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