Monitoring & Observability Guide (Русский)

Обзор

В OmniRoute предусмотрено 3 уровня мониторинга:

┌──────────────────────────────────────────────────────────────┐
│  Уровень 1: Состояние системы (на уровне сервера)             │
│  ├─ localHealthCheck.ts — БД, порты, нативные зависимости     │
│  ├─ db/healthCheck.ts — целостность, FK, потерянные артефакты  │
│  └─ Панель мониторинга: /dashboard/health                     │
├──────────────────────────────────────────────────────────────┤
│  Уровень 2: Состояние провайдеров (отказоустойчивость          │
│  для каждого провайдера)                                      │
│  ├─ providerHealthAutopilot.ts — автоматический выключатель,   │
│  │  периоды ожидания                                           │
│  ├─ providerHealthMatrix.ts — оценки состояния по              │
│  │  провайдерам/моделям                                        │
│  └─ Панель мониторинга: /dashboard/providers                  │
├──────────────────────────────────────────────────────────────┤
│  Уровень 3: Наблюдаемость в реальном времени                   │
│  (снимки среды выполнения)                                     │
│  ├─ observability.ts — автоматические выключатели, сеансы,     │
│  │  квота                                                       │
│  ├─ tokenHealthCheck.ts — состояние обновления токенов OAuth   │
│  └─ Инструменты MCP: omniroute_get_health,                     │
│     omniroute_get_session_snapshot                             │
└──────────────────────────────────────────────────────────────┘

---

Страницы панели мониторинга

/dashboard/health (Состояние системы)

Панель мониторинга состояния верхнего уровня показывает:

Раздел	Что отображается
Состояние сервера	Время работы, версия, порт, активные подключения
База данных	Подключение, целостность, размер WAL, последние миграции
Сводка провайдеров	Количество активных и исправных провайдеров, число разомкнутых автоматических выключателей
Мониторы квот	Активные сеансы, оповещения, исчерпанные квоты
Последние ошибки	Последние 10 ошибок с трассировками стека
Использование ресурсов	Память, ЦП, индикатор нагрузки на кучу

/dashboard/providers (Состояние провайдеров)

Панель мониторинга для каждого провайдера:

Столбец	Описание
Провайдер	Идентификатор провайдера + отображаемое имя
Состояние	Зелёный/жёлтый/красный статус
Выключатель	Разомкнутое/замкнутое/полуразомкнутое состояние
Подключения	Количество подключений, последнее обновление
Модели	Доступные модели, состояние каждой модели
Стоимость	Стоимость за сегодня, тенденция за 7 дней
Ошибки	Число ошибок за последние 24 ч, основной класс ошибок

Нажмите на провайдера, чтобы увидеть:

• Последние запросы с разбивкой задержки
• Оценки состояния для каждого подключения
• Блокировки для каждой модели
• Рекомендации автопилота

/dashboard/quota (Отслеживание квот)

Для каждого API-ключа:

• Текущее использование относительно лимита (индикатор выполнения)
• Динамика квоты (график за 30 дней)
• Время следующего сброса
• История оповещений

/dashboard/combos (Состояние комбинаций)

Для каждой комбинации:

• Стратегия + целевые объекты
• Состояние каждого целевого объекта
• Последние события переключения на резерв
• Доля успешных запросов (24 ч, 7 дн., 30 дн.)

---

API проверки работоспособности

OmniRoute предоставляет две HTTP-точки проверки работоспособности. Они не являются взаимозаменяемыми для оркестраторов.

Путь	Назначение	Нагрузка	Использование
GET /healthz	Проверка жизнеспособности/готовности жизненного цикла (ok / starting / stopping)	Минимальная (только флаг фазы)	Готовность Kubernetes; щадящая проверка жизнеспособности, если необходимо использовать HTTP
GET /api/monitoring/health	Подробная сводка по системе и провайдерам (БД, куча, количество записей в каталоге, …)	Высокая (синхронная работа с БД / мониторингом)	Панели мониторинга, глубокие внешние проверки, встроенная проверка работоспособности Docker

Примечание: Матрицы состояния провайдеров, проблемы автопилота, мониторы квот, состояние токенов и подробные данные о задержках, не входящие в /api/monitoring/health, доступны через инструмент MCP observability_snapshot или страницы панели мониторинга — отдельных REST-маршрутов для них нет.

Оба маршрута выполняются в том же цикле событий Node, что и обработка запросов. CPU-зависимый путь (обработка большого каталога GET /v1/models, сжатие длинного контекста / подсчёт токенов) может задержать все HTTP-обработчики, включая /healthz. Занятый цикл событий ≠ мёртвый процесс. Предпочтительно устранить причину нагрузки; настройка проверок лишь уменьшает количество ошибочных завершений процесса.

Легковесная проверка оркестратора

GET /healthz
# или HEAD /healthz

• 200 + тело ok, когда фаза жизненного цикла сервера находится в состоянии готовности
• 503 + starting / stopping во время запуска или завершения работы
• Реализация: src/app/healthz/route.ts (без проверки связи с БД)

Состояние системы (подробная проверка)

GET /api/monitoring/health

Ответ:

{
  "status": "healthy",
  "version": "3.8.16",
  "uptime": 123456,
  "checks": {
    "database": { "status": "pass", "latency_ms": 2 },
    "writeable": { "status": "pass" },
    "integrity": { "status": "pass", "result": "ok" },
    "foreign_keys": { "status": "pass", "violations": 0 },
    "heap_pressure": { "status": "pass", "usage_mb": 142, "threshold_mb": 512 },
    "active_sessions": 12,
    "providers": {
      "total": 7,
      "healthy": 6,
      "degraded": 1,
      "down": 0
    }
  }
}

credentialHealth: кеш проверок и test_status в SQLite

GET /api/monitoring/health → credentialHealth — это метрика кеша проверок в памяти, а не актуальная выгрузка provider_connections.test_status. После #12532 путь обработки запроса считывает только getCachedCredentialHealthSummary(); фоновые проверки обновляют кеш вне цикла событий.

Уровень	Где	Что это означает
Метрика кеша проверок	credentialHealth.total / healthy / failed / unknown / stale	Последние результаты проверки состояния учётных данных, которые всё ещё хранятся в памяти процесса. Значение source всегда равно probe-cache.
Сведения об ошибочных подключениях	credentialHealth.failedConnections	Присутствуют только при failed > 0. Ограниченный список строк кеша со status=error (connectionId, status, очищенные lastError / lastErrorType). Если список был ограничен, устанавливается failedOmitted.
Закреплённый статус SQLite	credentialHealth.staleDbNonOkCount	Количество строк активных (is_active=1) подключений, у которых сохранённый test_status имеет известное состояние, отличное от успешного (error, expired, credits_exhausted, banned, deactivated, unavailable).

Эти два уровня могут намеренно расходиться:

• Метрика failed=0, когда staleDbNonOkCount>0 — в SQLite всё ещё хранится закреплённый test_status (например, expired или credits_exhausted), который последний снимок кеша проверок не учитывает как status=error.
• Метрика failed>0, когда согласно SQLite всё исправно — недавняя проверка завершилась ошибкой и была закеширована; строка БД ещё не обновлена или впоследствии была очищена.

Не создавайте оповещения исключительно на основе provider_connections.test_status при сборе данных из этой конечной точки. Используйте failed + failedConnections для актуальных ошибок проверок и staleDbNonOkCount, когда требуется количество сохранённых закреплённых статусов.

Рекомендации по проверкам Kubernetes

OmniRoute представляет собой один процесс Node (с одним циклом событий). Стандартная Docker-проверка HEALTHCHECK обращается к легковесному маршруту /healthz. /api/monitoring/health слишком ресурсоёмок для интервалов проверки жизнеспособности kubelet.

Проверка	Рекомендуемая цель	Примечания
Запуск	HTTP GET /healthz с большим failureThreshold (или длительным startPeriod)	Холодный запуск + миграция SQLite могут занять более нескольких секунд
Готовность	HTTP GET /healthz	Состояние жизненного цикла ok / starting / stopping (200 или 503). Проверка по-прежнему может нестабильно срабатывать, если цикл событий заблокирован вычислениями CPU. Ответ 200, полученный через несколько секунд, не означает исправную работу (#10303) — это значит, что цикл событий был лишён ресурсов до выполнения обработчика, возвращающего 3 байта
Работоспособность	HTTP GET /livez или TCP на основном порту сервиса (PORT, по умолчанию 20128)	/livez проверяет только, что процесс запущен (всегда возвращает 200, если обработчик выполняется). Но он использует тот же цикл событий — занятость ≠ отказ, и он выявляет нехватку ресурсов цикла событий (#10303) не лучше, чем TCP. Предпочитайте TCP, если HTTP-проверки завершаются по тайм-ауту под нагрузкой каталога/сжатия; в любом случае не завершайте pod из-за кратковременных задержек цикла событий
Глубокая проверка состояния	GET /api/monitoring/health из внешней системы проверки	Не предназначено для livenessProbe kubelet или частой readinessProbe

Пример конфигурации (настройте пороговые значения с учётом нагрузки при холодном запуске и сжатии):

ports:
  - name: http
    containerPort: 20128
startupProbe:
  httpGet:
    path: /healthz
    port: http
  failureThreshold: 30
  periodSeconds: 5
readinessProbe:
  httpGet:
    path: /healthz
    port: http
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 6
livenessProbe:
  httpGet:
    path: /livez
    port: http
  periodSeconds: 10
  timeoutSeconds: 3
  failureThreshold: 6
  # При задержке цикла событий HTTP-запрос к /livez всё равно может завершиться
  # по тайм-ауту. TCP — более консервативная альтернатива:
  # tcpSocket:
  #   port: http

Не направляйте проверку работоспособности kubelet на /api/monitoring/health. Этот путь выполняет реальную работу с БД и мониторингом и под нагрузкой будет давать ложные срабатывания.

См. также: #10052 (проверки, когда цикл событий занят), #9685 / #10055 (чрезмерная нагрузка из-за расчёта цен каталога), #10117 (чрезмерная нагрузка из-за подсчёта токенов при сжатии).

Необязательная обработка запросов (память, навыки, обновление токенов)

Извлечение памяти, внедрение навыков и обновление токенов OAuth используют основной цикл событий Node совместно с /healthz. Это функции, переключаемые в панели управления (memoryEnabled, skillsEnabled), а не пул рабочих процессов. См. Окружение — нагрузка на цикл событий.

Состояние провайдера

REST-эндпоинт отсутствует. Данные о состоянии провайдеров доступны через MCP-инструмент observability_snapshot или на странице /dashboard/providers панели управления.

Сведения о провайдере

REST-эндпоинт отсутствует. Подробные сведения по каждому провайдеру доступны на странице /dashboard/providers панели управления.

---

Автопилот состояния провайдеров

Модуль providerHealthAutopilot.ts представляет собой самовосстанавливающуюся систему, которая:

1. Обнаруживает проблемы провайдеров (разомкнутые цепи, периоды ожидания, блокировки, предупреждения о квотах)
2. Формирует рекомендуемые действия для их устранения
3. При необходимости автоматически выполняет действия с низким уровнем риска

Типы обнаруживаемых проблем

Тип проблемы	Серьёзность	Пример условия
provider_circuit_open	критическая	Цепь разомкнута после 5 сбоев
provider_circuit_half_open	предупреждение	Цепь проверяет восстановление
connection_cooldown	предупреждение	Подключение находится в периоде ожидания после 429
stale_connection_error	предупреждение	Последнее обновление завершилось сбоем более 30 минут назад
terminal_connection_error	критическая	OAuth отозван, ключ недействителен
inactive_connection	информационная	Подключение отключено в настройках
model_lockout	предупреждение	Конкретная модель помещена в карантин
quota_monitor_warning	предупреждение	Использовано не менее 80% квоты

Типы формируемых действий

Действие	Риск	Описание
clear_provider_breaker	средний	Сбросить автоматический выключатель в замкнутое состояние
clear_connection_cooldown	низкий	Снять период ожидания с подключения
clear_stale_connection_error	низкий	Сбросить флаг устаревшей ошибки
clear_model_lockout	низкий	Повторно включить модель из карантина
reactivate_connection	средний	Повторно включить деактивированное подключение
deactivate_connection	высокий	Отключить проблемное подключение

API

REST-эндпоинт отсутствует. Проблемы, обнаруженные автопилотом, доступны через инструмент MCP observability_snapshot или панель мониторинга. Автопилот работает внутри системы; его поведение настраивается через БД настроек (поле autopilotMode для каждого подключения), а не через переменные окружения — команда grep -rn для переменной окружения режима автопилота не возвращает результатов.

Режим автопилота

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

---

Автопилот состояния комбинаций

comboHealthAutopilot.ts — это ориентированный на комбинации аналог автопилота провайдеров. Он:

• Обнаруживает неработоспособные комбинации
• Рекомендует изменить порядок целей
• Предлагает отключить неисправные цели
• Автоматически удаляет неработающие цели после N сбоев

Примеры проблем с комбинациями

Комбинация "always-on" (стратегия приоритетов)
├─ Цель 1: openai/gpt-5 (работоспособна)
├─ Цель 2: anthropic/claude-opus-4-6 (⚠️ модель заблокирована до 14:00)
└─ Цель 3: kiro/claude-sonnet-4-5 (работоспособна)

Рекомендуемое действие: изменить порядок — переместить kiro выше anthropic до истечения срока блокировки

---

Мониторы квот

observability.ts предоставляет мониторы квот для каждого сеанса для провайдеров с подпиской (Claude Code, Codex, GitHub Copilot):

interface QuotaMonitorSnapshot {
  sessionId: string;
  provider: string;
  accountId: string;
  status: "starting" | "idle" | "healthy" | "warning" | "exhausted" | "error";
  lastQuotaPercent: number | null; // 0–100
  lastQuotaUsed: number | null;
  lastQuotaTotal: number | null;
  lastResetAt: string | null;
  nextPollAt: string | null;
  totalPolls: number;
  totalAlerts: number;
  consecutiveFailures: number;
}

Значения статусов

Статус	Когда	Действие интерфейса
starting	Выполняется первоначальный опрос	Индикатор загрузки
idle	Нет недавней активности	Скрыть с панели мониторинга
healthy	Осталось более 50% квоты	Зелёная точка
warning	Осталось менее 50% квоты	Жёлтое предупреждение
exhausted	Квота = 0%	Красный блок, перенаправление к следующему провайдеру
error	Опрос завершился сбоем	Красная точка, вскоре повторить попытку

API

REST-эндпоинт отсутствует. Данные монитора квот доступны через инструмент MCP observability_snapshot или панель мониторинга.

---

Снимок наблюдаемости

Инструмент MCP observability_snapshot возвращает полный снимок состояния системы для ИИ-агентов:

{
  "circuitBreakers": [
    {
      "name": "openai",
      "state": "closed",
      "failureCount": 0,
      "lastFailureTime": null,
      "retryAfterMs": null
    }
  ],
  "sessions": [
    {
      "sessionId": "sess-123",
      "createdAt": 1234567890,
      "lastActive": 1234567999,
      "requestCount": 42,
      "connectionId": "conn-456",
      "ageMs": 109
    }
  ],
  "quotaMonitors": {/* см. выше */},
  "uptime": 12345,
  "version": "3.8.16"
}

Агенты используют его для принятия решений о маршрутизации — например: «если цепь openai разомкнута, сначала направить запрос к anthropic».

---

Проверка состояния токенов

Провайдерам OAuth (Claude Code, GitHub Copilot, Cursor) требуется периодическое обновление токенов. src/lib/tokenHealthCheck.ts запускает фоновый планировщик:

• Цикл сканирования: каждые 60 секунд (сканирование с интервалом TICK_MS = 60 * 1000 в src/lib/tokenHealthCheck.ts:30)
• Интервал проверки состояния каждого подключения: по умолчанию 60 минут (DEFAULT_HEALTH_CHECK_INTERVAL_MIN = 60); настраивается через базу данных настроек
• Упреждающее обновление при ошибке 401: обрабатывается перехватчиком соответствующего подключения

Состояние токена

interface TokenHealth {
  connectionId: string;
  provider: string;
  status: "valid" | "expiring_soon" | "expired" | "refresh_failed";
  expiresAt: string;
  lastRefresh: string;
  nextRefresh: string;
  consecutiveFailures: number;
}

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

Конфигурация проверки состояния токенов обрабатывается внутри tokenHealthCheck.ts.

Состояние токенов

Конечная точка REST отсутствует. Данные о состоянии токенов доступны через панель управления или инструмент MCP observability_snapshot.

---

Оповещения

Встроенные каналы

OmniRoute поддерживает 3 канала оповещений:

Канал	Настройка	Сценарий использования
Баннер панели управления	Всегда включён	Уведомления внутри приложения
Вебхук	Настройте URL	Slack, Discord, PagerDuty
Журнал	По умолчанию	Для внешней агрегации журналов

Настройка вебхука

Примечание: Настройка оповещений через вебхук выполняется на странице Settings панели управления. Параметры URL вебхука, фильтрации событий и настройки полезной нагрузки см. в интерфейсе Settings.

Типы оповещений

Оповещение	Условие	Уровень серьёзности по умолчанию
provider_circuit_open	Цепь размыкается	critical
provider_circuit_half_open	Цепь тестирует восстановление	info
quota_warning	Квота использована на 80% и более	warning
quota_exhausted	Квота использована на 100%	critical
token_refresh_failed	3 и более последовательных сбоев обновления	warning
token_expired	Срок действия токена истёк	critical
combo_target_unhealthy	Цель комбинации в режиме ожидания более 1 ч	warning
db_integrity_warning	Нарушений внешних ключей > 0	warning
heap_pressure	Использование кучи > 80% от порогового значения	warning

---

Метрики производительности

Отслеживаемые метрики

Метрика	Тип	Источник
request_count	счётчик	services/usage.ts
request_latency_ms	гистограмма	services/usage.ts
tokens_consumed	счётчик	services/usage.ts
cost_usd	счётчик	services/usage.ts
provider_errors	счётчик	services/errorClassifier.ts
circuit_state_changes	счётчик	services/resilience.ts
cache_hits	счётчик	services/signatureCache.ts
compression_savings	гистограмма	services/compression/stats.ts
quota_used	индикатор	services/quotaMonitor.ts
memory_used_mb	индикатор	observability.ts

Процентили задержки (p50/p95/p99)

REST-эндпоинт отсутствует. Данные о процентилях задержки доступны на странице панели мониторинга /dashboard/health. Экспорт в Prometheus/OpenTelemetry запланирован на v3.9.

Экспорт в Prometheus / OpenTelemetry (этап 2)

В v3.9 запланирован встроенный экспорт в Prometheus, OpenTelemetry и Datadog.

Пока используйте опрос /api/monitoring/health с помощью любой системы мониторинга на основе HTTP (Prometheus blackbox exporter, HTTP-проверка Datadog и т. д.).

---

Рецепты настройки оповещений

Slack

Примечание: Оповещения через вебхуки настраиваются на странице Settings панели управления — специальных переменных окружения для вебхуков нет (grep -rn не находит ни одного совпадения). URL вебхука, фильтрацию событий и настройку полезной нагрузки см. в интерфейсе Settings.

Discord

Оповещения через вебхуки настраиваются в том же интерфейсе Settings, что и для Slack. Discord принимает полезную нагрузку JSON той же структуры.

PagerDuty

Оповещения через вебхуки настраиваются в том же интерфейсе Settings. Ключи маршрутизации PagerDuty Events API v2 задаются в интерфейсе Settings.

Пользовательский вебхук (JSON)

Подойдёт любой HTTP-эндпоинт, принимающий POST-запросы с телом в формате JSON. Укажите URL в интерфейсе Settings.

---

Настройка панели мониторинга

Настройка панели состояния

Создайте файл ~/.omniroute/dashboard.json:

{
  "health": {
    "sections": ["server_status", "database", "providers", "quota_monitors", "recent_errors"],
    "refresh_interval_ms": 5000
  }
}

Закрепление провайдера в верхней части

{
  "health": {
    "pinned_providers": ["openai", "anthropic"]
  }
}

---

Устранение неполадок

«Провайдер отображается как работоспособный, но запросы завершаются ошибкой»

1. Проверьте проблемы автопилота — возможно, модель заблокирована
2. Просмотрите недавние ошибки, относящиеся к конкретному классу ошибок
3. Запустите проверку подключения в карточке провайдера
4. Проверьте, не применяется ли провайдером ограничение частоты запросов на вышестоящей стороне (локально это не отображается)

«Квота отображается как доступная, но я получаю ошибки 429»

• Код 429 означает, что, по данным провайдера, вы исчерпали свою квоту
• Данные OmniRoute об использовании квоты могут быть устаревшими — актуальные данные находятся на стороне провайдера
• Данные о квоте автоматически обновляются внутренним монитором квот

«Комбинация не работает, хотя все целевые ресурсы выглядят работоспособными»

• Проверьте состояние комбинации на панели мониторинга на наличие проблем с порядком целевых ресурсов
• Просмотрите события переключения на резервный ресурс — возможно, комбинация слишком быстро исчерпывает доступные варианты
• Убедитесь, что стратегия соответствует вашему сценарию использования (приоритет, циклический перебор или автоматический режим)

«Проверка состояния базы данных завершается ошибкой»

• Выполните sqlite3 ~/.omniroute/storage.sqlite "PRAGMA integrity_check;"
• Если результат — «ok», это ложная тревога: проверка состояния слишком строгая
• Если результат любой другой — остановите OmniRoute и следуйте руководству по аварийному восстановлению

«Нагрузка на кучу памяти достигла критического уровня»

# Проверьте текущее состояние кучи
node -e "console.log(process.memoryUsage())"

# Запустите сборку мусора вручную (если используется --expose-gc)
node --expose-gc -e "global.gc(); console.log(process.memoryUsage())"

# Уменьшите количество параллельных запросов (задаётся на странице Settings панели управления, а не через переменную окружения)
# Переменной окружения `MAX_CONCURRENT_REQUESTS` не существует — настройте этот параметр в Settings → Concurrency.

---

См. также

• USAGE_QUOTA_GUIDE.md — отслеживание использования и затрат
• DATABASE_GUIDE.md — схема БД и её состояние
• PROXY_GUIDE.md — состояние прокси (отдельный кэш)
• ARCHITECTURE.md — архитектура системы
• RESILIENCE_GUIDE.md — подробности о предохранителе
• Исходный код: src/lib/monitoring/ (4 файла, 2121 строка кода)

---

Исходный код OmniRoute (a58000c7685f)