SSE Event Contract

This document describes the Server-Sent Events (SSE) contract for the /events (alias: /requests/stream) endpoint.

Related:

• Monitoring Guide - Dashboard and alerting setup
• Metrics Reference - Available Prometheus metrics
• Dashboard Guide - Real-time dashboard visualization

Dashboard Visualization

The Requests page displays real-time events from the SSE stream:

Trace Table - View individual request events:

Log Entries - Real-time event log:

Connection

Endpoint: GET /events or GET /requests/stream

Query Parameters:

• types (optional): Comma-separated list of event types to subscribe to. Default: all
  • Valid types: request, kpi, alert, all

Example:

GET /events?types=request,kpi

Event Contract

Every SSE message follows this contract:

event: <eventType>
data: <JSON payload>

Standard Message Envelope

All event payloads include these fields:

Plus event-specific fields described below.

Sequence Number Semantics:

• seq is a global counter incremented once per broadcast event
• All clients subscribed to the same event type receive the same seq value
• The connected event has its own seq (unique to that client’s connection)
• Clients can detect missed events by checking seq > lastSeq + 1
• Note: If you’re subscribed to a subset of event types, you’ll see gaps in seq (this is expected)

Event Types

connected

Sent immediately on connection. Includes recent requests for initial state hydration.

{
  "seq": 1,
  "ts": 1706380800000,
  "schemaVersion": 1,
  "type": "connected",
  "clientId": "sse-1706380800000-abc123xyz",
  "subscribedTypes": ["all"],
  "recentRequests": [
    { /* request object */ }
  ]
}

request

Emitted for each proxied request completion. Critical event - clients that can’t keep up may be disconnected.

{
  "seq": 42,
  "ts": 1706380801234,
  "schemaVersion": 1,
  "type": "request",
  "requestId": "req-abc123",
  "keyIndex": 0,
  "keyPrefix": "sk-abc...",
  "status": 200,
  "latencyMs": 1234,
  "model": "claude-3-5-sonnet-20241022",
  "mappedModel": "glm-4-plus",
  "inputTokens": 1000,
  "outputTokens": 500,
  "cost": 0.0225,
  "costStatus": "calculated",
  "streaming": true,
  "retries": 0,
  "errorType": null,
  "timestamp": 1706380801234
}

kpi

Periodic lightweight stats snapshot. Emitted every 30 seconds. Non-critical - may be dropped under backpressure.

{
  "seq": 100,
  "ts": 1706380830000,
  "schemaVersion": 1,
  "type": "kpi",
  "uptime": 3600000,
  "activeKeys": 3,
  "totalKeys": 5,
  "requests": 1234,
  "errors": 12,
  "activeConnections": 5,
  "sseClients": 2,
  "poolStatus": {
    "inCooldown": false,
    "cooldownRemainingMs": 0,
    "pool429Count": 0
  }
}

alert

Budget or threshold alerts. Emitted when cost thresholds are exceeded.

{
  "seq": 150,
  "ts": 1706380900000,
  "schemaVersion": 1,
  "type": "alert",
  "alertType": "budget_warning",
  "severity": "warning",
  "message": "Daily budget 80% consumed",
  "details": {
    "period": "today",
    "current": 80.00,
    "limit": 100.00,
    "percentUsed": 80
  }
}

Heartbeat

The server sends comment-line pings every 15 seconds to keep the connection alive:

: ping 1706380815000

These are SSE comments (start with :) and are not JSON events.

Backpressure Handling

Performance: See Load Testing Guide for throughput optimization under high load.

The server implements backpressure to protect against slow clients:

1. Non-critical events (kpi): Silently dropped when client buffer is full
2. Critical events (request): Client disconnected after 30 seconds of backpressure

Clients should:

• Process events quickly
• Track seq numbers to detect gaps
• Reconnect and hydrate from recentRequests if gaps detected

Client Implementation

Recommended Pattern

const evtSource = new EventSource('/events?types=request,kpi');

let lastSeq = 0;

evtSource.addEventListener('connected', (e) => {
  const data = JSON.parse(e.data);
  // Hydrate initial state from recentRequests
  data.recentRequests.forEach(req => store.addRequest(req));
  lastSeq = data.seq;
});

evtSource.addEventListener('request', (e) => {
  const data = JSON.parse(e.data);
  // Check for gaps
  if (data.seq > lastSeq + 1) {
    console.warn(`Gap detected: ${lastSeq} -> ${data.seq}`);
    // Consider refetching state
  }
  lastSeq = data.seq;
  store.addRequest(data);
});

evtSource.addEventListener('kpi', (e) => {
  const data = JSON.parse(e.data);
  store.updateKPI(data);
});

evtSource.onerror = () => {
  // Reconnect logic with exponential backoff
};

Gap Recovery

When a sequence gap is detected:

1. Continue processing new events
2. Fetch /stats for current aggregate state
3. Fetch /requests?limit=100 for recent request history
4. Merge with local state

Schema Versioning

The schemaVersion field enables backward-compatible evolution:

• Version 1 (current): Initial schema as documented above
• Future versions will increment this number
• Clients should handle unknown fields gracefully

Related Endpoints

Reference: See Metrics Reference for all available /stats and /metrics fields.