Cloud
Health Aggregation
Poll downstream service health endpoints in parallel and combine them into one healthy, degraded, or unhealthy report.
On this page7
Overview
HealthAggregator polls multiple downstream services in parallel over
node:http / node:https and combines their health into a single report.
Ideal for API gateways and operational dashboards.
Usage
TypeScript
TS
1import { HealthAggregator } from '@axiljs/cloud'
2
3const aggregator = new HealthAggregator([
4 { name: 'auth-service', url: 'http://auth:3001/health' },
5 { name: 'payment-service', url: 'http://payments:3002/health' },
6 { name: 'search-service', url: 'http://search:3003/health', timeoutMs: 2000 },
7])
8
9const report = await aggregator.check()Response Format
JSON
JSON
1{
2 "status": "degraded",
3 "services": [
4 { "name": "auth-service", "status": "up", "latencyMs": 12 },
5 { "name": "payment-service", "status": "up", "latencyMs": 45 },
6 { "name": "search-service", "status": "timeout", "latencyMs": 2001, "error": "Timed out after 2000ms" }
7 ],
8 "timestamp": "2026-11-11T12:00:00.000Z"
9}Each service is reported as:
| Service status | Condition |
|---|---|
up | Responded with HTTP 200–399 |
down | Any other status code (error: 'HTTP <code>') or a network error |
timeout | No response within timeoutMs; the request is aborted |
Status Levels
| Status | Condition |
|---|---|
healthy | Every service is up |
degraded | At least one timeout and none down |
unhealthy | At least one service is down |
Adding Services Dynamically
TypeScript
TS
1aggregator.addService({
2 name: 'notification-service',
3 url: 'http://notify:3004/health',
4 timeoutMs: 3000,
5 headers: { 'Authorization': 'Bearer internal-token' },
6})Exposing as an Endpoint
TypeScript
TS
1app.get('/api/health/aggregated', async (req, res) => {
2 const report = await aggregator.check()
3 const statusCode = report.status === 'unhealthy' ? 503 : 200
4 res.status(statusCode).json(report)
5})Service Configuration
| Option | Type | Default | Description |
|---|---|---|---|
name | string | — | Service display name |
url | string | — | Health check URL (http or https) |
timeoutMs | number | 5000 | Request timeout in milliseconds |
headers | Record<string, string> | — | Custom headers for the health check |
Was this page helpful?