@adalo/metrics

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

Testing and staging (for contributors)

• Run tests: yarn test (or yarn test:watch). CI runs tests on every pull request.
• Test locally in a consuming app (without publishing):
  • From this repo: yarn link
  • In the app repo (e.g. backend): yarn link @adalo/metrics
  • Or use a file dependency: "@adalo/metrics": "file:../path/to/metrics-js"
• Test on staging before merging to main:
  • Push your changes to the staging branch (create it if needed). The Deploy Staging workflow will build and publish to npm with the dist-tag staging (version like 0.0.0-staging.123).
  • In the app that uses this library (e.g. backend), point the dependency to the staging build:
    • In package.json: "@adalo/metrics": "staging" (resolves to latest @adalo/metrics@staging), or pin a specific version: "@adalo/metrics": "0.0.0-staging.123".
  • Deploy that app to staging and verify metrics/behavior. When satisfied, merge metrics-js into main and release a normal version; then update the app back to "@adalo/metrics": "^x.y.z" or "latest".

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 || ''
  pushgatewaySecret,  // defaults: process.env.METRICS_PUSHGATEWAY_SECRET || '' (Base64 of user:password)
  intervalSec,        // defaults: process.env.METRICS_INTERVAL_SEC || 15
})

Architecture

See ../docs/METRICS.md (flow diagrams, Redis HTTP path, env vars).

DatabaseMetricsClient / QueueRedisMetricsClient / RedisMetricsClient exit with code 0 (no logs) if the resolved processType is wrong only when METRICS_ENABLED is true. When metrics are off, that check is skipped.

Example Usage

const { MetricsClient, HttpMetricsRedisRecorder } = require('@adalo/metrics')
const { redisClient } = require('./redis')

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

app.use(httpRecorder.trackHttpRequestMiddleware.bind(httpRecorder))

metrics.startPush()

Custom usage

// Create custom gauges and counters

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

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

// Automatically push metrics at intervals (staging: 60s; prod: 900 or 1800 for 15/30 min)
metrics.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", "connectMs": 5.2 },
        "cluster_1": { "status": "healthy", "connectMs": 8.1 },
        "cluster_2": { "status": "healthy", "connectMs": 6.4 }
      }
    },
    "redis": { "status": "healthy" }
  }
}

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')