Cloud

Health Aggregation

Multi-service health monitoring and status aggregation.

2 min readDocumentationEdit this page

Overview

The health aggregator polls multiple downstream services in parallel and combines their health status into a single aggregated report. Ideal for API gateways and operational dashboards.

Usage

typescript
import { HealthAggregator } from '@axiljs/cloud'
 
const aggregator = new HealthAggregator([
  { name: 'auth-service',    url: 'http://auth:3001/health' },
  { name: 'payment-service', url: 'http://payments:3002/health' },
  { name: 'search-service',  url: 'http://search:3003/health', timeoutMs: 2000 },
])
 
const report = await aggregator.check()

Response Format

json
{
  "status": "healthy",
  "services": [
    { "name": "auth-service",    "status": "up",   "latencyMs": 12 },
    { "name": "payment-service", "status": "up",   "latencyMs": 45 },
    { "name": "search-service",  "status": "down", "latencyMs": 2001, "error": "Timed out" }
  ],
  "timestamp": "2025-08-21T12:00:00.000Z"
}

Status Levels

StatusCondition
healthyAll services are responding
degradedSome services are timing out
unhealthyOne or more services are down

Adding Services Dynamically

typescript
aggregator.addService({
  name: 'notification-service',
  url: 'http://notify:3004/health',
  timeoutMs: 3000,
  headers: { 'Authorization': 'Bearer internal-token' },
})

Exposing as an Endpoint

typescript
app.get('/api/health/aggregated', async (req, res) => {
  const report = await aggregator.check()
  const statusCode = report.status === 'healthy' ? 200
    : report.status === 'degraded' ? 200
    : 503
  res.status(statusCode).json(report)
})

Service Configuration

OptionTypeDefaultDescription
namestring—Service display name
urlstring—Health check URL
timeoutMsnumber5000Request timeout in milliseconds
headersobject—Custom headers for the health check

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY