Наблюдаемость с помощью OpenTelemetry

Узнайте, как включить и настроить OpenTelemetry для Qwen Code.

Наблюдаемость с помощью OpenTelemetry

Ключевые преимущества

🔍 Аналитика использования: Понимание паттернов взаимодействия и adoption rate функций в вашей команде
⚡ Мониторинг производительности: Отслеживание времени отклика, потребления токенов и использования ресурсов
🐛 Отладка в реальном времени: Выявление узких мест, сбоев и паттернов ошибок по мере их возникновения
📊 Оптимизация рабочих процессов: Принятие обоснованных решений для улучшения конфигураций и процессов
🏢 Корпоративное управление: Мониторинг использования между командами, отслеживание затрат, обеспечение compliance и интеграция с существующей инфраструктурой мониторинга

Интеграция с OpenTelemetry

Основанная на OpenTelemetry — независимом от вендоров, отраслевом стандарте фреймворка наблюдаемости — система наблюдаемости Qwen Code предоставляет:

Универсальную совместимость: Экспорт в любой бэкенд OpenTelemetry (Google Cloud, Jaeger, Prometheus, Datadog и т. д.)
Стандартизированные данные: Использование согласованных форматов и методов сбора данных в вашем инструментарии
Интеграция на будущее: Подключение к существующей и будущей инфраструктуре наблюдаемости
Отсутствие привязки к поставщику: Переключение между бэкендами без изменения вашей инструментации

Конфигурация

Все параметры телеметрии управляются через ваш файл .qwen/settings.json.
Эти настройки можно переопределить с помощью переменных окружения или флагов CLI.

Параметр	Переменная окружения	Флаг CLI	Описание	Значения	По умолчанию
`enabled`	`GEMINI_TELEMETRY_ENABLED`	`--telemetry` / `--no-telemetry`	Включить или отключить телеметрию	`true`/`false`	`false`
`target`	`GEMINI_TELEMETRY_TARGET`	`--telemetry-target <local\|gcp>`	Куда отправлять данные телеметрии	`"gcp"`/`"local"`	`"local"`
`otlpEndpoint`	`GEMINI_TELEMETRY_OTLP_ENDPOINT`	`--telemetry-otlp-endpoint <URL>`	Endpoint OTLP collector	URL строка	`http://localhost:4317`
`otlpProtocol`	`GEMINI_TELEMETRY_OTLP_PROTOCOL`	`--telemetry-otlp-protocol <grpc\|http>`	Транспортный протокол OTLP	`"grpc"`/`"http"`	`"grpc"`
`outfile`	`GEMINI_TELEMETRY_OUTFILE`	`--telemetry-outfile <path>`	Сохранить телеметрию в файл (переопределяет `otlpEndpoint`)	путь к файлу	-
`logPrompts`	`GEMINI_TELEMETRY_LOG_PROMPTS`	`--telemetry-log-prompts` / `--no-telemetry-log-prompts`	Включать промпты в логи телеметрии	`true`/`false`	`true`
`useCollector`	`GEMINI_TELEMETRY_USE_COLLECTOR`	-	Использовать внешний OTLP collector (advanced)	`true`/`false`	`false`

Примечание по boolean переменным окружения: Для boolean параметров (enabled,
logPrompts, useCollector) установка соответствующей переменной окружения в
true или 1 включит функцию. Любое другое значение отключит её.

Подробную информацию обо всех параметрах конфигурации см. в
Руководстве по конфигурации.

Телеметрия Google Cloud

Предварительные требования

Перед использованием любого из методов ниже выполните следующие шаги:

Установите ID вашего проекта Google Cloud:
- Для телеметрии в отдельном проекте от inference:
```
export OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id"
```
- Для телеметрии в том же проекте, что и inference:
```
export GOOGLE_CLOUD_PROJECT="your-project-id"
```
Аутентифицируйтесь в Google Cloud:
- Если используете пользовательский аккаунт:
```
gcloud auth application-default login
```
- Если используете service account:
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account.json"
```
Убедитесь, что ваш аккаунт или service account имеет следующие роли IAM:
- Cloud Trace Agent
- Monitoring Metric Writer
- Logs Writer

Включите необходимые Google Cloud API (если они еще не включены):


gcloud services enable \
  cloudtrace.googleapis.com \
  monitoring.googleapis.com \
  logging.googleapis.com \
  --project="$OTLP_GOOGLE_CLOUD_PROJECT"

Прямой экспорт (рекомендуется)

Отправляет телеметрию напрямую в сервисы Google Cloud. Коллектор не требуется.

Включите телеметрию в вашем .qwen/settings.json:


{
  "telemetry": {
    "enabled": true,
    "target": "gcp"
  }
}

Запустите Qwen Code и отправьте промпты.
Просмотрите логи и метрики:
- Откройте Google Cloud Console в браузере после отправки промптов:
  - Логи: https://console.cloud.google.com/logs/
  - Метрики: https://console.cloud.google.com/monitoring/metrics-explorer
  - Трассировки: https://console.cloud.google.com/traces/list

Экспорт через Collector (для продвинутых)

Для кастомной обработки, фильтрации или маршрутизации данных используйте OpenTelemetry collector для пересылки данных в Google Cloud.

Настройте ваш .qwen/settings.json:


{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "useCollector": true
  }
}

Запустите скрипт автоматизации:
```
npm run telemetry -- --target=gcp
```
Это сделает следующее:
- Запустит локальный OTEL collector, который будет пересылать данные в Google Cloud
- Настроит ваш workspace
- Предоставит ссылки для просмотра трассировок, метрик и логов в Google Cloud Console
- Сохранит логи collector’а в ~/.qwen/tmp/<projectHash>/otel/collector-gcp.log
- Остановит collector при выходе (например, по Ctrl+C)
Запустите Qwen Code и отправьте промпты.
Просмотрите логи и метрики:
- Откройте Google Cloud Console в браузере после отправки промптов:
  - Логи: https://console.cloud.google.com/logs/
  - Метрики: https://console.cloud.google.com/monitoring/metrics-explorer
  - Трассировки: https://console.cloud.google.com/traces/list
- Откройте ~/.qwen/tmp/<projectHash>/otel/collector-gcp.log, чтобы посмотреть локальные логи collector’а.

Локальная телеметрия

Для локальной разработки и отладки вы можете сохранять данные телеметрии локально:

Вывод в файл (рекомендуется)

Включите телеметрию в вашем .qwen/settings.json:


{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "",
    "outfile": ".qwen/telemetry.log"
  }
}

Запустите Qwen Code и отправьте промпты.
Просматривайте логи и метрики в указанном файле (например, .qwen/telemetry.log).

Экспорт через Collector (Продвинутый уровень)

Запустите скрипт автоматизации:
```
npm run telemetry -- --target=local
```
Это сделает следующее:
- Скачает и запустит Jaeger и OTEL collector
- Настроит ваше рабочее пространство для локальной телеметрии
- Предоставит интерфейс Jaeger по адресу http://localhost:16686
- Сохранит логи/метрики в ~/.qwen/tmp/<projectHash>/otel/collector.log
- Остановит collector при выходе (например, Ctrl+C)
Запустите Qwen Code и отправьте промпты.
Просмотрите трассировки по адресу http://localhost:16686 , а логи и метрики — в файле лога collector’а.

Логи и Метрики

В этом разделе описывается структура логов и метрик, генерируемых для Qwen Code.

sessionId добавляется как общее свойство ко всем логам и метрикам.

Логи

Логи — это записи с меткой времени о конкретных событиях. Для Qwen Code логируются следующие события:

qwen-code.config: Это событие происходит один раз при запуске и содержит конфигурацию CLI.
- Атрибуты:
  - model (string)
  - embedding_model (string)
  - sandbox_enabled (boolean)
  - core_tools_enabled (string)
  - approval_mode (string)
  - api_key_enabled (boolean)
  - vertex_ai_enabled (boolean)
  - code_assist_enabled (boolean)
  - log_prompts_enabled (boolean)
  - file_filtering_respect_git_ignore (boolean)
  - debug_mode (boolean)
  - mcp_servers (string)
  - output_format (string: “text” или “json”)
qwen-code.user_prompt: Это событие происходит, когда пользователь отправляет prompt.
- Атрибуты:
  - prompt_length (int)
  - prompt_id (string)
  - prompt (string, этот атрибут исключается, если log_prompts_enabled установлен в false)
  - auth_type (string)
qwen-code.tool_call: Это событие происходит при каждом вызове функции.
- Атрибуты:
  - function_name
  - function_args
  - duration_ms
  - success (boolean)
  - decision (string: “accept”, “reject”, “auto_accept” или “modify”, если применимо)
  - error (если применимо)
  - error_type (если применимо)
  - content_length (int, если применимо)
  - metadata (если применимо, словарь string -> any)
qwen-code.file_operation: Это событие происходит при каждой операции с файлом.
- Атрибуты:
  - tool_name (string)
  - operation (string: “create”, “read”, “update”)
  - lines (int, если применимо)
  - mimetype (string, если применимо)
  - extension (string, если применимо)
  - programming_language (string, если применимо)
  - diff_stat (json string, если применимо): JSON-строка со следующими полями:
    - ai_added_lines (int)
    - ai_removed_lines (int)
    - user_added_lines (int)
    - user_removed_lines (int)
qwen-code.api_request: Это событие происходит при отправке запроса к Qwen API.
- Атрибуты:
  - model
  - request_text (если применимо)
qwen-code.api_error: Это событие происходит, если запрос к API завершился ошибкой.
- Атрибуты:
  - model
  - error
  - error_type
  - status_code
  - duration_ms
  - auth_type
qwen-code.api_response: Это событие происходит при получении ответа от Qwen API.
- Атрибуты:
  - model
  - status_code
  - duration_ms
  - error (опционально)
  - input_token_count
  - output_token_count
  - cached_content_token_count
  - thoughts_token_count
  - tool_token_count
  - response_text (если применимо)
  - auth_type
qwen-code.tool_output_truncated: Это событие происходит, когда вывод от вызова инструмента слишком большой и был усечен.
- Атрибуты:
  - tool_name (string)
  - original_content_length (int)
  - truncated_content_length (int)
  - threshold (int)
  - lines (int)
  - prompt_id (string)
qwen-code.malformed_json_response: Это событие происходит, когда ответ generateJson от Qwen API не может быть распаршен как JSON.
- Атрибуты:
  - model
qwen-code.flash_fallback: Это событие происходит, когда Qwen Code переключается на flash в качестве резервного варианта.
- Атрибуты:
  - auth_type
qwen-code.slash_command: Это событие происходит, когда пользователь выполняет slash-команду.
- Атрибуты:
  - command (string)
  - subcommand (string, если применимо)
qwen-code.extension_enable: Это событие происходит, когда расширение включено.
qwen-code.extension_install: Это событие происходит, когда расширение установлено.
- Атрибуты:
  - extension_name (string)
  - extension_version (string)
  - extension_source (string)
  - status (string)
qwen-code.extension_uninstall: Это событие происходит, когда расширение удалено.

Метрики

Метрики — это числовые измерения поведения за определённый период времени. Для Qwen Code собираются следующие метрики (названия метрик остаются в формате qwen-code.* для обратной совместимости):

qwen-code.session.count (Counter, Int): Увеличивается на 1 при каждом запуске CLI.
qwen-code.tool.call.count (Counter, Int): Считает количество вызовов инструментов.
- Атрибуты:
  - function_name
  - success (boolean)
  - decision (string: “accept”, “reject”, или “modify”, если применимо)
  - tool_type (string: “mcp”, или “native”, если применимо)
qwen-code.tool.call.latency (Histogram, ms): Измеряет задержку вызова инструментов.
- Атрибуты:
  - function_name
  - decision (string: “accept”, “reject”, или “modify”, если применимо)
qwen-code.api.request.count (Counter, Int): Считает все API запросы.
- Атрибуты:
  - model
  - status_code
  - error_type (если применимо)
qwen-code.api.request.latency (Histogram, ms): Измеряет задержку API запросов.
- Атрибуты:
  - model
qwen-code.token.usage (Counter, Int): Считает количество использованных токенов.
- Атрибуты:
  - model
  - type (string: “input”, “output”, “thought”, “cache”, или “tool”)
qwen-code.file.operation.count (Counter, Int): Считает операции с файлами.
- Атрибуты:
  - operation (string: “create”, “read”, “update”): Тип операции с файлом.
  - lines (Int, если применимо): Количество строк в файле.
  - mimetype (string, если применимо): MIME-тип файла.
  - extension (string, если применимо): Расширение файла.
  - model_added_lines (Int, если применимо): Количество строк, добавленных/изменённых моделью.
  - model_removed_lines (Int, если применимо): Количество строк, удалённых/изменённых моделью.
  - user_added_lines (Int, если применимо): Количество строк, добавленных/изменённых пользователем в предложенных ИИ изменениях.
  - user_removed_lines (Int, если применимо): Количество строк, удалённых/изменённых пользователем в предложенных ИИ изменениях.
  - programming_language (string, если применимо): Язык программирования файла.
qwen-code.chat_compression (Counter, Int): Считает операции сжатия чата.
- Атрибуты:
  - tokens_before: (Int): Количество токенов в контексте до сжатия.
  - tokens_after: (Int): Количество токенов в контексте после сжатия.