Мониторинг

​

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

# 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 endpoint (для 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

​

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

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

​

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

​

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

​

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

​

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

​

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

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

​

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

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

​

Поведение обновления

​

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

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

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

# ❌ Недопустимо - содержит пробелы
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"

​

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

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

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

​

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

​

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

• prompt.id: UUID, коррелирующий пользовательскую подсказку со всеми последующими событиями до следующей подсказки. См. Атрибуты корреляции событий.
• workspace.host_paths: каталоги рабочей области хоста, выбранные в приложении для рабочего стола, как массив строк

​

Метрики

​

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

​

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

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

​

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

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

​

Счетчик pull request

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

​

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

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

​

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

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

​

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

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

​

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

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

​

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

• Все стандартные атрибуты
• type: "user" для взаимодействия с клавиатурой, "cli" для выполнения инструментов и ответов AI

​

События

​

Атрибуты корреляции событий

​

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

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

​

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

• Все стандартные атрибуты
• event.name: "tool_result"
• event.timestamp: Временная метка ISO 8601
• event.sequence: монотонно возрастающий счетчик для упорядочивания событий в сеансе
• tool_name: Имя инструмента
• success: "true" или "false"
• duration_ms: Время выполнения в миллисекундах
• error: Сообщение об ошибке (если не удалось)
• decision_type: Либо "accept", либо "reject"
• decision_source: Источник решения - "config", "hook", "user_permanent", "user_temporary", "user_abort" или "user_reject"
• tool_result_size_bytes: Размер результата инструмента в байтах
• mcp_server_scope: Идентификатор области MCP сервера (для инструментов MCP)
• tool_parameters: JSON строка, содержащая параметры, специфичные для инструмента (когда доступно)
  • Для инструмента Bash: включает bash_command, full_command, timeout, description, dangerouslyDisableSandbox и git_commit_id (SHA коммита, когда команда git commit успешна)
  • Для инструментов MCP (когда OTEL_LOG_TOOL_DETAILS=1): включает mcp_server_name, mcp_tool_name
  • Для инструмента Skill (когда OTEL_LOG_TOOL_DETAILS=1): включает skill_name
• tool_input (когда OTEL_LOG_TOOL_DETAILS=1): JSON-сериализованные аргументы инструмента. Отдельные значения более 512 символов усекаются, и полная нагрузка ограничена примерно 4 K символами. Применяется ко всем инструментам, включая инструменты MCP.

​

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

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

​

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

• Все стандартные атрибуты
• event.name: "api_error"
• event.timestamp: Временная метка ISO 8601
• event.sequence: монотонно возрастающий счетчик для упорядочивания событий в сеансе
• model: Используемая модель (например, “claude-sonnet-4-6”)
• error: Сообщение об ошибке
• status_code: HTTP код состояния в виде строки или "undefined" для ошибок, не связанных с HTTP
• duration_ms: Длительность запроса в миллисекундах
• attempt: Номер попытки (для повторных запросов)
• speed: "fast" или "normal", указывающий, был ли активен быстрый режим

​

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

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

​

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

​

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

​

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

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

​

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

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

​

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

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

​

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

​

Для метрик

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

​

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

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

​

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

• 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

​

Безопасность и конфиденциальность

• Телеметрия является добровольной и требует явной конфигурации
• Содержимое файлов в исходном виде и фрагменты кода не включаются в метрики или события. События выполнения инструментов включают команды bash и пути к файлам в поле tool_parameters, которое может содержать конфиденциальные значения. Если ваши команды могут включать секреты, настройте ваш бэкенд телеметрии для фильтрации или редактирования tool_parameters
• При аутентификации через OAuth user.email включается в атрибуты телеметрии. Если это вызывает беспокойство для вашей организации, работайте с вашим бэкендом телеметрии для фильтрации или редактирования этого поля
• Содержимое пользовательской подсказки не собирается по умолчанию. Записывается только длина подсказки. Чтобы включить содержимое подсказки, установите OTEL_LOG_USER_PROMPTS=1
• Аргументы входных данных инструмента не логируются по умолчанию. Чтобы включить их, установите OTEL_LOG_TOOL_DETAILS=1. Когда включено, события tool_result включают имена MCP сервера/инструмента и имена навыков плюс атрибут tool_input с путями к файлам, URL-адресами, шаблонами поиска и другими аргументами. Отдельные значения более 512 символов усекаются, и общее количество ограничено примерно 4 K символами, но аргументы могут по-прежнему содержать конфиденциальные значения. Настройте ваш бэкенд телеметрии для фильтрации или редактирования tool_input по мере необходимости

​

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