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

> Master OmniRoute dashboard monitoring with this comprehensive guide. Learn to track provider health, quota usage, and request telemetry in real-time via its intuitive Next.js UI and APIs.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/credentialHealth/cache.ts)
- **Connection cooldowns** via [`src/lib/resilience/settings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/resilience/settings.ts)
- **Model lockout policies** from [`src/domain/lockoutPolicy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/lockoutPolicy.ts)
- **Telemetry aggregates** (latency percentiles, error rates) from [`src/shared/utils/requestTelemetry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/requestTelemetry.ts)

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

```typescript
// 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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/ws/liveServer.ts) handles subscription management, heartbeat tracking, and broadcast distribution.

Connect to the live stream from any dashboard component:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/QuotaCard.tsx) for visualization.