API Feature
Real-time

WebSocket API Events

Subscribe to real-time events for metrics, job progress, index updates, and system alerts.

WebSocket Protocol and Event Types

WebSocket event types and message flow

Connection

// Connect with authentication
const ws = new WebSocket('wss://api.mlgraph.io/ws', [
  'Bearer', 'mlg_your_token_here'
]);

// Or connect and authenticate after
const ws = new WebSocket('wss://api.mlgraph.io/ws');
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'mlg_your_token_here'
  }));
};

// Handle messages
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(message.type, message.data);
};

Event Types

metrics.*

  • • metrics.system
  • • metrics.index
  • • metrics.search
  • • metrics.ingest

job.*

  • • job.started
  • • job.progress
  • • job.completed
  • • job.failed

index.*

  • • index.created
  • • index.updated
  • • index.deleted
  • • index.shard_transition

alert.*

  • • alert.warning
  • • alert.error
  • • alert.resolved
  • • alert.rate_limit

Subscription Protocol

// Subscribe to channels
ws.send(JSON.stringify({
  type: 'subscribe',
  channels: ['metrics.system', 'job.*', 'alert.*']
}));

// Unsubscribe
ws.send(JSON.stringify({
  type: 'unsubscribe',
  channels: ['metrics.system']
}));

// Subscribe to specific index events
ws.send(JSON.stringify({
  type: 'subscribe',
  channels: ['index.production-vectors.*']
}));

// Ping/pong for keepalive
ws.send(JSON.stringify({ type: 'ping' }));
// Response: { type: 'pong', timestamp: '...' }

Message Format

// Metrics update
{
  "type": "metrics.system",
  "timestamp": "2024-12-22T10:30:00.123Z",
  "data": {
    "qps": 1250,
    "latency_p50_ms": 2.1,
    "latency_p99_ms": 15.3,
    "active_connections": 42,
    "memory_used_gb": 12.4
  }
}

// Job progress
{
  "type": "job.progress",
  "timestamp": "2024-12-22T10:30:01.456Z",
  "data": {
    "jobId": "import-abc123",
    "jobType": "import",
    "progress": 0.45,
    "processed": 450000,
    "total": 1000000,
    "rate": 15000,
    "eta_seconds": 37
  }
}

// Alert
{
  "type": "alert.warning",
  "timestamp": "2024-12-22T10:30:02.789Z",
  "data": {
    "alertId": "alert-xyz",
    "severity": "warning",
    "title": "High memory usage",
    "message": "Node n1 memory at 85%",
    "metadata": {
      "node": "n1",
      "value": 0.85,
      "threshold": 0.80
    }
  }
}

Connection Management

Best Practices

  • Auto-reconnect: Implement exponential backoff (1s, 2s, 4s... max 30s)
  • Heartbeat: Send ping every 30s to detect stale connections
  • Resubscribe: Re-send subscriptions after reconnect
  • State sync: Request full state on reconnect to catch missed events
Next: Three-Tier StorageBack to MLGraph Docs