OmniRoute/docs/i18n/sr/docs/ops/MONITORING_GUIDE.md

Monitoring & Observability Guide (Српски)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

TL;DR: OmniRoute се испоручује са уграђеним надзором здравља, аутопилотом добављача, праћењем квота и кукама за опсервабилност. Овај водич обухвата контролну таблу, упозорења и решавање проблема.

Извори:

• src/lib/monitoring/observability.ts — снимак опсервабилности
• src/lib/monitoring/comboHealthAutopilot.ts — аутопилот здравља комбинација
• src/lib/monitoring/providerHealthAutopilot.ts — аутопилот добављача
• src/lib/monitoring/providerHealthMatrix.ts — матрица здравља добављача
• src/lib/localHealthCheck.ts — локална провера здравља
• src/lib/tokenHealthCheck.ts — здравље освежавања токена
• src/lib/proxyHealth.ts — кеш здравља проксија (обрађено у PROXY_GUIDE.md)

---

Преглед

OmniRoute има 3 слоја надзора:

┌──────────────────────────────────────────────────────────────┐
│  Слој 1: Здравље система (на нивоу сервера)                   │
│  ├─ localHealthCheck.ts — база података, портови, изворне зависности │
│  ├─ db/healthCheck.ts — интегритет, страни кључеви, напуштени артефакти │
│  └─ Контролна табла: /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 грешака са траговима стека
Коришћење ресурса	Меморију, CPU, индикатор оптерећења хипа

/dashboard/providers (Здравље добављача)

Контролна табла за сваког добављача:

Колона	Опис
Добављач	ID добављача + назив за приказ
Здравље	Зелени/жути/црвени статус
Коло	Отворено/затворено/полуотворено стање
Везе	Број веза, последње освежавање
Модели	Доступни модели, здравље по моделу
Трошак	Данашњи трошак, тренд током 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	Детаљни резиме система и добављача (база података, хип, број ставки каталога, …)	Захтевно (синхрони рад са базом података / надзором)	Контролне табле, детаљне blackbox провере, уграђена 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: кеш провера наспрам SQLite test_status

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). И даље осцилира ако је петља блокирана процесорским радом. Одговор 200 након више секунди не означава исправно стање (#10303) — то значи да је петља догађаја била ускраћена за ресурсе пре него што је покренут руковалац од 3 бајта
Живост	HTTP GET /livez, или TCP на главном порту сервиса (PORT, подразумевано 20128)	/livez проверава само да ли је процес активан (увек враћа 200 ако се руковалац покрене). И даље дели петљу догађаја — заузето ≠ мртво, а изгладњивање петље догађаја (#10303) не открива ништа боље од TCP-а. Дајте предност TCP-у ако HTTP провере истичу под оптерећењем каталога/компресије; ни у једном случају немојте прекидати pod због кратких застоја петље догађаја
Дубинска провера стања	GET /api/monitoring/health из спољне провере	Није намењено за kubelet livenessProbe / учестали 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 враћа комплетан снимак система за AI агенте:

{
  "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 канала за упозорења:

Канал	Подешавање	Намена
Банер контролне табле	Увек укључен	Обавештења унутар апликације
Webhook	Конфигуришите URL	Slack, Discord, PagerDuty
Евиденција	Подразумевано	За спољно обједињавање евиденција

Webhook конфигурација

Напомена: Конфигурацијом Webhook упозорења управља се преко странице Подешавања на контролној табли. Погледајте кориснички интерфејс Подешавања за Webhook URL, филтрирање догађаја и прилагођавање корисног садржаја.

Типови упозорења

Упозорење	Када	Подразумевана озбиљност
provider_circuit_open	Коло се отвори	критична
provider_circuit_half_open	Коло тестира опоравак	информативна
quota_warning	Квота је на 80%+	упозорење
quota_exhausted	Квота је на 100%	критична
token_refresh_failed	3+ узастопна неуспешна освежавања	упозорење
token_expired	Токену је истекао рок	критична
combo_target_unhealthy	Комбиновано одредиште је на паузи 1ч+	упозорење
db_integrity_warning	Број кршења спољних кључева > 0	упозорење
heap_pressure	Употреба хипа > 80% граничне вредности	упозорење

---

Метрике перформанси

Праћене метрике

Метрика	Тип	Извор
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, Datadog HTTP check итд.).

---

Рецепти за упозорења

Slack

Напомена: Webhook упозорења конфигуришу се на страници Settings контролне табле — не постоје наменске webhook променљиве окружења (grep -rn не враћа ниједан резултат). У корисничком интерфејсу Settings погледајте URL webhook-а, филтрирање догађаја и прилагођавање садржаја.

Discord

Webhook упозорења користе исти ток у корисничком интерфејсу Settings као Slack. Discord прихвата исти облик JSON садржаја.

PagerDuty

Webhook упозорења користе исти ток у корисничком интерфејсу Settings. Кључеви за усмеравање PagerDuty Events API v2 конфигуришу се у корисничком интерфејсу Settings.

Прилагођени webhook (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 линија кода)