# OmniRoute Reporting and Analytics: A Technical Deep Dive

> Unlock OmniRoute reporting and analytics with request logging, SQL aggregation, WebSocket feeds, and a dashboard. Monitor token usage, costs, success rates & provider health.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-07-15

---

**OmniRoute provides comprehensive reporting and analytics through request-level logging, SQL-based aggregation engines, real-time WebSocket feeds, and a dedicated dashboard UI that tracks token usage, costs, success rates, and provider health metrics.**

OmniRoute is an open-source AI gateway that ships with a full-stack analytics subsystem designed to monitor every inference request. The platform captures detailed usage data at the database level, computes costs across multiple billing models, and surfaces operational insights through both REST APIs and interactive dashboard visualizations.

## How OmniRoute Captures Request-Level Analytics

Every inference request passing through OmniRoute is instrumented for **usage analytics** before it reaches the upstream provider.

In [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts), each request is annotated with the API key and a usage analytics flag that stores success/failure states alongside token counts. This raw telemetry is then persisted to the `usage_history` table via [`src/lib/usage/usageHistory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/usageHistory.ts), which saves a row containing the model name, provider, token usage, computed cost, and timestamp for every completed request.

The cost calculation layer handles both per-token and flat-rate billing models. The system uses [`src/lib/usage/costCalculator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/costCalculator.ts) to convert token counts into monetary values, while [`src/lib/usage/flatRateProviders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/flatRateProviders.ts) manages providers that charge fixed fees rather than per-token rates.

## The Aggregation Engine and Database Layer

OmniRoute reporting and analytics rely on a hybrid aggregation architecture that combines TypeScript utilities with optimized SQL views.

The [`src/lib/usageAnalytics.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usageAnalytics.ts) module contains pure functions that read from the `usage_history` table and compute the metrics required by the dashboard UI. For heavy-weight aggregations—such as monthly totals, per-model breakdowns, and success rate calculations—the system queries pre-built SQL views defined in [`src/lib/db/usageAnalytics.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/usageAnalytics.ts) and [`src/lib/db/usageAnalytics/sources.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/usageAnalytics/sources.ts). These SQLite-based analytics views efficiently aggregate raw request data into consumable statistics without requiring full table scans on every dashboard load.

## REST API Endpoints for Analytics Data

Applications can access OmniRoute reporting and analytics programmatically through dedicated REST endpoints.

The **GET `/api/usage/analytics`** endpoint (implemented in [`src/app/api/usage/analytics/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/usage/analytics/route.ts)) serves the pre-computed aggregates from the analytics views, returning a JSON payload containing total tokens consumed, cumulative costs, success rates, and temporal breakdowns. For data portability, the `/api/settings/export-json` endpoint reuses the same aggregation logic to generate downloadable analytics snapshots.

```typescript
// Fetch aggregated usage analytics from the server
const resp = await fetch('/api/usage/analytics');
const analytics = await resp.json();

console.log('Total tokens used:', analytics.totalTokens);
console.log('Cost this month (USD):', analytics.totalCost);

```

## Real-Time Analytics with WebSocket Feeds

Beyond batch aggregation, OmniRoute provides **live analytics** through WebSocket connections for real-time monitoring.

The WebSocket server in [`src/server/ws/liveServer.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/ws/liveServer.ts) emits events formatted as `analytics-${row.id}` immediately after a request finishes processing. This allows dashboard visualizations to update charts and metrics without requiring a full page refresh.

```typescript
// Listening to live analytics updates via WebSocket
const ws = new WebSocket('wss://your-omniroute.local/ws');
ws.addEventListener('message', (ev) => {
  const data = JSON.parse(ev.data);
  if (data.type?.startsWith('analytics-')) {
    console.log('Live update for request', data.requestId, data);
  }
});

```

## Dashboard Visualization and UI Components

The analytics interface is organized into dedicated dashboard pages registered in [`src/shared/constants/sidebarVisibility/sections.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/sidebarVisibility/sections.ts), including `analytics-utilization`, `analytics-combo-health`, and `analytics-compression`.

Each page queries the analytics API and renders charts using color palettes defined in [`src/shared/constants/colors.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/colors.ts). The visualization layer supports tables, charts, and heat-maps that display historical trends and current system health.

## Specialized Reporting: Combo Health and Compression

OmniRoute reporting and analytics extend beyond basic usage metrics to include provider-specific health monitoring and optimization tracking.

**Combo health metrics** are gathered in [`src/lib/db/usageAnalytics.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/usageAnalytics.ts) and exposed through the `analytics-combo-health` sidebar section, allowing operators to monitor the reliability of specific provider combinations. **Compression analytics** track the efficiency of context compression runs, writing data to the `compression_analytics` table (defined in migration 091 within [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts)) and visualizing savings on the dedicated Compression analytics page. Search-related usage is similarly tagged and aggregated through the same engine.

```typescript
// Programmatic export of analytics data
await fetch('/api/settings/export-json', {
  method: 'GET',
  headers: { Accept: 'application/json' },
})
  .then((r) => r.blob())
  .then((blob) => saveAs(blob, 'omniroute-analytics.json'));

```

## Summary

- **Request-level instrumentation** in [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts) captures every API call with token counts and success flags.
- **Persistent storage** via [`src/lib/usage/usageHistory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/usageHistory.ts) maintains a complete audit trail of model usage and costs.
- **SQL-based aggregation** in [`src/lib/db/usageAnalytics.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/usageAnalytics.ts) efficiently computes metrics for dashboard display.
- **REST API** endpoints provide programmatic access to usage statistics and JSON export functionality.
- **Real-time updates** through WebSocket events enable live monitoring without page refreshes.
- **Specialized analytics** track combo health and compression efficiency alongside standard usage metrics.

## Frequently Asked Questions

### How does OmniRoute calculate costs for different provider billing models?

OmniRoute handles both per-token and flat-rate pricing through specialized modules. The [`src/lib/usage/costCalculator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/costCalculator.ts) file computes monetary costs based on per-token rates, while [`src/lib/usage/flatRateProviders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/usage/flatRateProviders.ts) manages providers that charge fixed subscription fees rather than usage-based pricing. Both systems write normalized cost data to the `usage_history` table for consistent reporting.

### Can I export OmniRoute analytics data for external analysis?

Yes. OmniRoute provides the `/api/settings/export-json` endpoint that generates downloadable snapshots of your analytics data. Additionally, you can query the **GET `/api/usage/analytics`** endpoint directly to fetch JSON aggregates for integration with external business intelligence tools or custom monitoring systems.

### What real-time capabilities does OmniRoute offer for monitoring usage?

OmniRoute emits live analytics events through WebSocket connections managed by [`src/server/ws/liveServer.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/ws/liveServer.ts). When a request completes, the system broadcasts an event with the pattern `analytics-${row.id}`, allowing dashboard interfaces to update visualizations instantly. This enables real-time monitoring of token consumption, costs, and error rates as traffic flows through the gateway.

### Where is analytics data stored in OmniRoute?

Analytics data is primarily stored in SQLite tables managed through the database layer in [`src/lib/db/usageAnalytics.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/usageAnalytics.ts). The system uses a `usage_history` table for raw request logs and a `usage_analytics` view for pre-aggregated metrics. Specialized data like compression statistics reside in dedicated tables such as `compression_analytics`, created via the migration system in [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts).