@adalo/metrics

Utility library for Prometheus metrics and HTTP request counting in Node.js applications.

Constructor

new MetricsClient({
  appName,            // defaults: process.env.BUILD_APP_NAME || 'unknown-app'
  dynoId,             // defaults: process.env.HOSTNAME || 'unknown-dyno'
  processType,        // defaults: process.env.BUILD_DYNO_PROCESS_TYPE || 'undefined_build_dyno_type'
  enabled,            // defaults: process.env.METRICS_ENABLED === 'true'
  logValues,          // defaults: process.env.METRICS_LOG_VALUES === 'true'
  pushgatewayUrl,     // defaults: process.env.METRICS_PUSHGATEWAY_URL || ''
  pushgatewayUser,    // defaults: process.env.METRICS_PUSHGATEWAY_USER || ''
  pushgatewayPassword,// defaults: process.env.METRICS_PUSHGATEWAY_PASSWORD || ''
  intervalSec         // defaults: process.env.METRICS_INTERVAL_SEC || 15
})

Example Usage

import { MetricsClient } from '@adalo/metrics-js'

const metrics = new MetricsClient({ appName: 'my-app', enabled: true })

// Express middleware
app.use(metrics.trackHttpRequestMiddleware)


// Start metrics push
metrics.startPush()

Custom usage

// Create custom gauges and counters

const metrics = new MetricsClient()
const testGauge = metricsClient.createGauge({
  name: 'app_test_usage_percent',
  help: 'Current test usage of the Node.js process in percent',
  labelNames: metricsClient.withDefaultLabels(['test_result']),
})

// Push metrics manually
metricsClient.gatewayPush({ groupings: { process_type: 'web' } })

// Automatically push metrics at intervals
metricsClient.startPush(15) // interval in seconds

HealthCheckClient

Provides a health check endpoint for external monitoring services like BetterStack. Validates database and Redis connections with rate limiting to prevent excessive load.

import { HealthCheckClient } from '@adalo/metrics'
import Redis from 'ioredis'

const redisClient = new Redis()
const healthCheck = new HealthCheckClient({
  databaseUrl: process.env.DATABASE_URL,
  databaseName: 'main',
  additionalDatabaseUrls: {
    cluster_1: process.env.CLUSTER_1_URL,
    cluster_2: process.env.CLUSTER_2_URL,
  },
  redisClient,
})

// Register on Express app
healthCheck.registerHealthEndpoint(app, '/betterstack-health')

Response format (BetterStack compatible):

{
  "status": "healthy",
  "timestamp": "2026-01-20T12:00:00.000Z",
  "cached": false,
  "components": {
    "database": {
      "status": "healthy",
      "clusters": {
        "main": { "status": "healthy", "latencyMs": 5 },
        "cluster_1": { "status": "healthy", "latencyMs": 8 },
        "cluster_2": { "status": "healthy", "latencyMs": 6 }
      }
    },
    "redis": { "status": "healthy", "latencyMs": 2 }
  }
}

Status codes:

• 200 - healthy or degraded
• 503 - unhealthy (at least one component failed)

Environment variables: | Variable | Description | Default | |----------|-------------|---------| | DATABASE_URL | Main PostgreSQL connection URL | - |

Tips

secret env was created as

Buffer.from(`${username}:${password}`).toString('base64')