VANTAGE
Documentation

Aegis Status Probes & Incident Management (@xtnd/vantage-aegis)

Package: @xtnd/vantage-aegis
Source Directory: xtnd-vantage/packages/aegis/

1. Overview

@xtnd/vantage-aegis is the operational status monitoring and incident reporting engine of XTND Vantage. It powers live status pages, edge health checks, and global incident broadcasts across the XTND service network.

2. Health & Status Interfaces

Component Status Levels

export type ComponentStatus =
  | 'OPERATIONAL'
  | 'DEGRADED_PERFORMANCE'
  | 'PARTIAL_OUTAGE'
  | 'MAJOR_OUTAGE';

Component Health Record

export interface ComponentHealth {
  componentId: string;       // Unique identifier (e.g. "api-gateway", "edge-sin01")
  name: string;              // Human-readable title (e.g. "Vantage Central Gateway")
  status: ComponentStatus;   // Current operational state
  latencyMs?: number;        // Round-trip latency in milliseconds
  uptimePercent?: number;    // Calculated uptime (e.g. 99.98)
  lastChecked: number;       // Epoch timestamp in milliseconds
}

3. Core Capabilities (VantageStatusProbe)

3.1 Heartbeat Monitoring (recordHeartbeat)

Periodic health pings from edge regions or background workers:

  • Updates the internal status map.
  • Emits a P3_DEFERRED event (status:heartbeat).
  • Enqueued with lowest network priority so status heartbeats never interfere with revenue-critical user traffic.

3.2 Instant Incident Declaration (declareIncident)

When an outage, provider degradation, or database connection drop occurs:

  • Updates component status to DEGRADED_PERFORMANCE, PARTIAL_OUTAGE, or MAJOR_OUTAGE.
  • Emits a P0_CRITICAL event (outage:declared) with isCritical: true.
  • Bypasses all batch intervals, immediately publishing the incident notice to Cloudflare KV and broadcasting to the Argus Command Center dashboard.

3.3 Incident Resolution (resolveIncident)

  • Restores component status to OPERATIONAL.
  • Emits a P1_HIGH event (incident:resolved) carrying post-mortem resolution notes.

4. Usage Example

import { VantageStatusProbe } from '@xtnd/vantage-aegis';

const probe = new VantageStatusProbe(storageManager);

// 1. Record healthy heartbeat ping
probe.recordHeartbeat('openai-proxy', 'OpenAI Edge Proxy', 32);

// 2. Declare an upstream incident (Broadcasts P0 alert immediately)
probe.declareIncident('openai-proxy', {
  title: 'OpenAI API Elevated Error Rates',
  severity: 'DEGRADED_PERFORMANCE',
  description: 'Upstream provider returning HTTP 503 errors; routing fallback models.'
});

// 3. Inspect global status overview
const healthReport = probe.getStatusOverview();
console.table(healthReport);

// 4. Resolve the incident
probe.resolveIncident('openai-proxy', 'Upstream provider recovered. Error rate back to 0.01%.');