OmniRoute Reporting and Analytics: A Technical Deep Dive

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, 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, 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 to convert token counts into monetary values, while 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 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 and 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) 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.

// 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 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.

// 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, 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. 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 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) and visualizing savings on the dedicated Compression analytics page. Search-related usage is similarly tagged and aggregated through the same engine.

// 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 captures every API call with token counts and success flags.
• Persistent storage via src/lib/usage/usageHistory.ts maintains a complete audit trail of model usage and costs.
• SQL-based aggregation in 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 file computes monetary costs based on per-token rates, while 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. 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. 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.

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