Cloud

Health Aggregation

Poll downstream service health endpoints in parallel and combine them into one healthy, degraded, or unhealthy report.

2 min readUpdated DocumentationEdit this page
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 statusCondition
upResponded with HTTP 200–399
downAny other status code (error: 'HTTP <code>') or a network error
timeoutNo response within timeoutMs; the request is aborted

Status Levels

StatusCondition
healthyEvery service is up
degradedAt least one timeout and none down
unhealthyAt 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

OptionTypeDefaultDescription
namestring—Service display name
urlstring—Health check URL (http or https)
timeoutMsnumber5000Request timeout in milliseconds
headersRecord<string, string>—Custom headers for the health check

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY