How to Use the Traffic Inspector for Capturing and Replaying HTTP Requests in OmniRoute

OmniRoute's Traffic Inspector lets you capture live HTTP traffic through a WebSocket-powered dashboard and replay any request via CLI or UI with identical routing and guard-rail processing.

The OmniRoute traffic inspector is a built-in observability tool for the open-source AI proxy. It intercepts inbound requests, streams them to a real-time dashboard, and enables deterministic replay for debugging or regression testing. This guide walks through activation, capture mechanics, and replay workflows based on the diegosouzapw/OmniRoute source code.

Enabling Traffic Inspector Capture

Traffic inspection is implemented as middleware that clones requests before they reach the routing layer.

Capture Middleware Location

The core capture logic resides in src/middleware/traffic-inspector.ts. This middleware:

1. Clones the incoming NextRequest to preserve the original for proxying
2. Extracts method, URL, headers, and body into a serializable object
3. Assigns a UUID and pushes to the WebSocket broadcaster
4. Returns control to next() for normal routing

// src/middleware/traffic-inspector.ts
export async function trafficInspector(req: NextRequest, next: NextHandler) {
  const clone = req.clone();                     // keep original for proxying
  const body = await clone.text();               // capture raw payload
  const capture = { 
    id: uuidv4(), 
    method: req.method, 
    url: req.url, 
    body,
    headers: Object.fromEntries(req.headers),
    timestamp: Date.now()
  };
  broadcastCapture(capture);                     // push to WS broadcaster
  return next();                                 // continue to provider
}

Middleware Registration

The middleware is registered in OmniRoute's main router configuration. Captured traffic flows through the same authentication, rate-limiting, and guard-rail layers as production requests.

Accessing the Live Traffic Dashboard

The dashboard UI provides real-time visibility into captured requests.

Dashboard Page Structure

The Traffic Inspector dashboard is implemented in src/app/dashboard/traffic-inspector/page.tsx. Key components include:

• Capture table: Lists all captured requests with method, host, status, and timestamp
• Filter controls: Filter by HTTP method, response status, or hostname substring
• Replay button: Triggers replay for any selected capture entry
• WebSocket connection: Maintains live subscription to new captures

// src/app/dashboard/traffic-inspector/page.tsx (structure reference)
export default function TrafficInspectorPage() {
  const [entries, setEntries] = useState<CaptureEntry[]>([]);
  
  useEffect(() => {
    const ws = new WebSocket('/api/traffic-inspector/ws');
    ws.onmessage = (ev) => {
      const capture = JSON.parse(ev.data);
      setEntries(prev => [capture, ...prev]);
    };
    return () => ws.close();
  }, []);
  
  // render table with filters and replay controls...
}

WebSocket Endpoint

The server-side broadcaster is implemented in src/app/api/traffic-inspector/ws.ts. It maintains an in-memory queue of recent captures and broadcasts to all connected dashboard clients.

Replaying Captured HTTP Requests

OmniRoute supports two replay mechanisms: dashboard-initiated replays and CLI-driven replays.

CLI Replay Command

The primary replay interface is bin/cli/api-commands/traffic-inspector.mjs. This Node.js script:

• Retrieves a capture by UUID from memory or optional SQLite storage
• Reconstructs the original HTTP request configuration
• Selects the appropriate executor for the target provider
• Executes the request with full policy enforcement

# List recent captures

node bin/cli/api-commands/traffic-inspector.mjs list

# Replay specific capture by ID

node bin/cli/api-commands/traffic-inspector.mjs replay abc-123-def

# Replay with verbose output

node bin/cli/api-commands/traffic-inspector.mjs replay abc-123-def --verbose

Replay Implementation

The CLI reuses OmniRoute's standard execution pipeline:

// bin/cli/api-commands/traffic-inspector.mjs
const capture = await getCaptureById(id);
const executor = getExecutor(capture.providerId);  // DefaultExecutor, etc.

const response = await executor.execute({
  method: capture.method,
  url: capture.url,
  body: capture.body,
  headers: capture.headers,
  // routing, combo, and guard-rail config inherited from capture
});

console.log('Status:', response.status);
console.log('Body:', await response.json());

Dashboard-Initiated Replay

When clicking Replay in the dashboard UI, the browser sends a request to the replay endpoint, which delegates to the same CLI logic. The replayed request:

• Appears as a new capture entry (distinguishable by replayedFrom metadata)
• Passes through identical provider selection and transformation
• Respects current rate limits and quota balances

Capture Storage and Persistence

By default, captures reside in memory only and clear on server restart.

Optional SQLite Persistence

The src/lib/db/traffic-inspector.ts module provides optional SQLite storage for:

• Long-term capture retention
• Cross-restart inspection
• Historical analysis and export

Enable persistence via environment configuration:

TRAFFIC_INSPECTOR_PERSISTENCE=sqlite
TRAFFIC_INSPECTOR_RETENTION_HOURS=168  # 7 days

Filtering and Analyzing Traffic

The dashboard supports精细 filtering for debugging specific provider interactions.

Common Filter Patterns

// tests/integration/traffic-inspector-requests.test.ts (illustrative)
// Filter successful OpenAI requests
const openaiSuccess = entries.filter(
  e => e.status === 200 && e.host.includes('openai.com')
);

// Filter by specific error code
const rateLimited = entries.filter(
  e => e.status === 429
);

// Filter by request method
const postRequests = entries.filter(
  e => e.method === 'POST'
);

Integration Testing Reference

The OmniRoute test suite validates Traffic Inspector functionality across multiple dimensions:

• UI tests: tests/unit/ui/traffic-inspector-page.test.tsx — WebSocket connection, rendering, interaction
• Integration tests: tests/integration/traffic-inspector-requests.test.ts — End-to-end capture and replay
• Capture mode tests: tests/integration/traffic-inspector-capture-modes.test.tsx — Persistence and filtering behavior

Summary

• Traffic Inspector consists of capture middleware (src/middleware/traffic-inspector.ts), WebSocket broadcaster (src/app/api/traffic-inspector/ws.ts), dashboard UI (src/app/dashboard/traffic-inspector/page.tsx), and CLI replay tool (bin/cli/api-commands/traffic-inspector.mjs)
• Captures are in-memory by default with optional SQLite persistence via src/lib/db/traffic-inspector.ts
• Replayed requests execute through the same pipeline as live traffic, ensuring authentic rate-limit, combo-routing, and guard-rail behavior
• The WebSocket stream enables sub-second latency between request capture and dashboard visibility
• All capture and replay operations respect OmniRoute's existing authentication and authorization layers

Frequently Asked Questions

How do I enable Traffic Inspector in OmniRoute?

Traffic Inspector is enabled by default when you start the OmniRoute server with standard middleware configuration. The middleware auto-registers and begins capturing once the server accepts HTTP traffic. No explicit activation is required beyond ensuring the dashboard is accessible at /dashboard/traffic-inspector.

What's the difference between live capture and replayed requests?

Live captures are original client requests passing through the proxy. Replayed requests are synthetic re-executions created from stored capture data. Both flow through identical provider executors and policy enforcement, but replays include replayedFrom metadata linking to the original capture UUID.

Does Traffic Inspector impact request latency?

The capture middleware uses request.clone() and non-blocking broadcast operations. In practice, overhead is typically under 5ms per request. The original request proceeds to routing immediately while capture serialization happens asynchronously.

Can I export captured traffic for external analysis?

Yes. When SQLite persistence is enabled, captures are queryable via the CLI or direct database access. The capture schema includes method, URL, headers, body, response status, timing, and provider routing decisions — sufficient for reconstructing full request/response cycles in tools like Postman or for compliance auditing.

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