How to Use the OmniRoute Dashboard for Monitoring: A Complete Guide

The OmniRoute dashboard provides real-time monitoring of provider health, quota usage, and request telemetry through its Next.js-based UI, WebSocket live streaming, and REST API endpoints.

This guide walks you through the OmniRoute monitoring system as implemented in the diegosouzapw/OmniRoute repository. Whether you're troubleshooting provider failures or optimizing auto-combo routing, the dashboard aggregates circuit-breaker states, connection cooldowns, and live request events into a unified interface.

Dashboard Architecture Overview

The monitoring system relies on three core infrastructure components:

• Health API (src/app/api/monitoring/health/route.ts) – Returns system-wide resilience state via GET and resets breakers via DELETE
• Live WebSocket Server (src/server/ws/liveServer.ts) – Streams real-time events on port 20129
• Dashboard Pages (src/app/(dashboard)/dashboard/*) – React components for health, usage, combo, and translator monitoring

These components feed five primary dashboard tabs that refresh automatically every 5 seconds.

Accessing the Health Monitoring API

The /api/monitoring/health endpoint serves as the single source of truth for system status. When loaded in src/app/(dashboard)/dashboard/health/page.tsx, it aggregates:

• Circuit-breaker states from src/lib/credentialHealth/cache.ts
• Connection cooldowns via src/lib/resilience/settings.ts
• Model lockout policies from src/domain/lockoutPolicy.ts
• Telemetry aggregates (latency percentiles, error rates) from src/shared/utils/requestTelemetry.ts

The response is cached for 5 seconds to balance responsiveness with freshness.

// Fetching health data in a dashboard component
useEffect(() => {
  fetch("/api/monitoring/health")
    .then(r => r.json())
    .then(data => setHealth(data));
}, []);

To reset all circuit-breakers programmatically, call the DELETE method:

await fetch("/api/monitoring/health", { method: "DELETE" });

This functionality is exposed in the UI through the "Reset All" button in src/app/(dashboard)/dashboard/health/TelemetryCard.tsx.

Setting Up Real-Time WebSocket Streaming

Live monitoring bypasses polling through a dedicated WebSocket connection. The server implementation in src/server/ws/liveServer.ts handles subscription management, heartbeat tracking, and broadcast distribution.

Connect to the live stream from any dashboard component:

export const useLiveDashboard = () => {
  const ws = useMemo(() => {
    return new WebSocket(
      `ws://${location.host}:20129/live?topics=requests,combo`
    );
  }, []);

  useEffect(() => {
    ws.onmessage = (ev) => {
      const msg = JSON.parse(ev.data);
      // Update UI state with live events
    };
    return () => ws.close();
  }, [ws]);
};

Valid subscription topics include requests, combo, and credentials. The Translator → Monitor tab (src/app/(dashboard)/dashboard/translator/components/MonitorTab.tsx) uses this hook to display live request/response pairs without page reloads.

Monitoring Provider Health and Quota Usage

Provider Topology Visualization

The Provider Topology section in src/app/(dashboard)/dashboard/home/ProviderTopology.tsx renders a graph of configured providers with real-time health flags. Each node reflects the aggregated state from the health API.

Quota Monitoring

Quota consumption appears in the Usage tab through src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaCard.tsx. These cards display:

• Token consumption per provider
• Cost accumulation
• Percentage of quota exhausted

Status icons (monitoring, monitor_heart, etc.) in src/app/(dashboard)/dashboard/health/ProviderHealthAutopilotCard.tsx provide at-a-glance quota health.

Health Matrix View

Navigate to /dashboard/providers/health for a matrix visualization powered by src/app/api/providers/health-matrix/route.ts. This view shows:

• Open providers (healthy and accepting requests)
• Half-open providers (probing after failure)
• Closed providers (circuit-breaker engaged)

Recent error rates accompany each status for quick diagnosis.

Tracking Auto-Combo Health and Routing Decisions

The Combo tab reveals why OmniRoute selected specific providers during request processing. The health-autopilot report—generated by src/lib/monitoring/comboHealthAutopilot.ts—drives the live cascade visualization in src/app/(dashboard)/dashboard/combos/live/ComboLiveStudio.tsx.

Each candidate provider displays:

• Current circuit-breaker state
• Remaining cooldown duration
• Scoring contributions to the final routing decision

This transparency helps operators understand routing behavior without inspecting logs.

Configuring Dashboard Features Through Flags

Feature-flag controls in src/app/(dashboard)/dashboard/settings/components/FeatureFlagCard.tsx gate access to experimental or resource-intensive features. Flags are defined in src/lib/monitoring/observability.ts and include options for:

• Live WebSocket enablement
• Quota-share page visibility
• Advanced telemetry collection

Changing a flag triggers an automatic UI reload to apply the new behavior.

Summary

• Health API (/api/monitoring/health) provides centralized system status with GET for retrieval and DELETE for breaker reset
• WebSocket server on port 20129 streams live events for the Translator Monitor and Combo tabs
• Dashboard tabs cover Health (breakers/quota), Usage (consumption), Combo (routing decisions), and Translator (live sessions)
• Auto-refresh occurs every 5 seconds with manual override available
• Feature flags control access to advanced monitoring capabilities

Frequently Asked Questions

How do I reset a stuck circuit-breaker from the dashboard?

Click the "Reset All" button in the Health tab, or call DELETE /api/monitoring/health directly. This clears all breaker states, cooldowns, and lockouts simultaneously. Use this when providers recover externally but OmniRoute hasn't detected the restoration.

Why are my live events not appearing in the Monitor tab?

Verify that the WebSocket server is running on port 20129 and that your connection includes valid topics (requests, combo, or credentials). Check browser devtools for connection errors, and confirm the feature flag for live monitoring is enabled in dashboard settings.

Where does the quota usage data originate?

Quota consumption aggregates from src/lib/monitoring/observability.ts, which collates token counts and cost estimates from the request telemetry pipeline. The data flows through /api/monitoring/health into QuotaCard.tsx for visualization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}