@adalo/metrics 0.1.0

package/src/metricsClient.js

@@ -0,0 +1,378 @@
+const client = require('prom-client')
+const fs = require('fs')
+const os = require('os')
+const https = require('https')
+
+/**
+ * MetricsClient handles Prometheus metrics collection and push.
+ * Supports gauges, counters, default metrics, and custom metrics.
+ */
+class MetricsClient {
+  /**
+   * @param {Object} config
+   * @param {string} [config.appName] Name of the application
+   * @param {string} [config.dynoId] Dyno/instance ID
+   * @param {string} [config.processType] Process type (web, worker, etc.)
+   * @param {boolean} [config.enabled] Enable metrics collection
+   * @param {boolean} [config.logValues] Log metrics values to console
+   * @param {string} [config.pushgatewayUrl] PushGateway URL
+   * @param {string} [config.pushgatewayUser] PushGateway username
+   * @param {string} [config.pushgatewayPassword] PushGateway password
+   * @param {number} [config.intervalSec] Interval in seconds for pushing metrics
+   */
+  constructor(config = {}) {
+    this.appName =
+      config.appName || process.env.METRICS_APP_NAME || 'unknown-app'
+    this.dynoId = config.dynoId || process.env.HOSTNAME || 'unknown-dyno'
+    this.processType =
+      config.processType ||
+      process.env.BUILD_DYNO_PROCESS_TYPE ||
+      'undefined_build_dyno_type'
+    this.enabled = config.enabled ?? process.env.METRICS_ENABLED === 'true'
+    this.logValues =
+      config.logValues ?? process.env.METRICS_LOG_VALUES === 'true'
+    this.pushgatewayUrl =
+      config.pushgatewayUrl || process.env.METRICS_PUSHGATEWAY_URL || ''
+    this.pushgatewayUser =
+      config.pushgatewayUser || process.env.METRICS_PUSHGATEWAY_USER || ''
+    this.pushgatewayPassword =
+      config.pushgatewayPassword ||
+      process.env.METRICS_PUSHGATEWAY_PASSWORD ||
+      ''
+    this.intervalSec =
+      config.intervalSec ||
+      parseInt(process.env.METRICS_INTERVAL_SEC || '', 10) ||
+      15
+
+    this.prefixLogs = `[${this.processType}] [${this.appName}] [${this.dynoId}] [Monitoring]`
+
+    this.registry = new client.Registry()
+    client.collectDefaultMetrics({ register: this.registry })
+
+    this.defaultLabels = {
+      app: this.appName,
+      dyno_id: this.dynoId,
+      process_type: this.processType,
+    }
+
+    const authToken = Buffer.from(
+      `${this.pushgatewayUser}:${this.pushgatewayPassword}`
+    ).toString('base64')
+    this.gateway = new client.Pushgateway(
+      this.pushgatewayUrl,
+      {
+        headers: { Authorization: `Basic ${authToken}` },
+        agent: new https.Agent({ keepAlive: true }),
+      },
+      this.registry
+    )
+
+    this.gauges = {}
+    this.counters = {}
+
+    /** @type {Object<string, function(): number | Promise<number>>} */
+    this.gaugeUpdaters = {}
+    /** @type {Object<string, function(data?: object, value?: number): void>} */
+    this.counterUpdaters = {}
+
+    this._lastUsageMicros = 0
+    this._lastCheckTime = Date.now()
+
+    this._initDefaultMetrics()
+  }
+
+  /**
+   * Register default gauges and counters.
+   * @private
+   */
+  _initDefaultMetrics = () => {
+    this.createGauge(
+      'app_process_cpu_usage_percent',
+      'Current CPU usage of the Node.js process in percent',
+      this.getCpuUsagePercent
+    )
+    this.createGauge(
+      'app_available_cpu_count',
+      'How many CPU cores are available to this process',
+      this.getAvailableCPUs
+    )
+    this.createGauge(
+      'app_container_memory_usage_bytes',
+      'Current container RAM usage from cgroup',
+      this.getContainerMemoryUsage
+    )
+    this.createGauge(
+      'app_event_loop_lag_ms',
+      'Estimated event loop lag in milliseconds',
+      this.measureLag
+    )
+    this.createGauge(
+      'app_container_memory_limit_bytes',
+      'Max RAM available to container from cgroup (memory.max)',
+      this.getContainerMemoryLimit
+    )
+    this.createGauge(
+      'app_uptime_seconds',
+      'How long the process has been running',
+      process.uptime
+    )
+
+    this.createCounter(
+      'app_http_requests_total',
+      'Total number of HTTP requests handled by this process',
+      [
+        ...Object.keys(this.defaultLabels),
+        'method',
+        'route',
+        'appId',
+        'databaseId',
+        'duration',
+        'requestSize',
+        'status_code',
+      ]
+    )
+  }
+
+  /**
+   * Create a gauge metric.
+   * @param {string} name
+   * @param {string} help
+   * @param {function(): number|Promise<number>} [updateFn] Optional function returning value
+   * @param {string[]} [labelNames]
+   * @returns {client.Gauge}
+   */
+  createGauge = (
+    name,
+    help,
+    updateFn,
+    labelNames = Object.keys(this.defaultLabels)
+  ) => {
+    if (this.gauges[name]) return this.gauges[name]
+
+    const g = new client.Gauge({
+      name,
+      help,
+      labelNames,
+      registers: [this.registry],
+    })
+    this.gauges[name] = g
+
+    if (typeof updateFn === 'function') this.gaugeUpdaters[name] = updateFn
+
+    return g
+  }
+
+  /**
+   * Create a counter metric.
+   * Returns a trigger function to increment the counter manually.
+   * @param {string} name
+   * @param {string} help
+   * @param {string[]} [labelNames]
+   * @returns {function(data?: object, value?: number): void} triggerFn
+   */
+  createCounter(name, help, labelNames = Object.keys(this.defaultLabels)) {
+    if (this.counters[name]) return this.counters[name].triggerFn
+
+    const c = new client.Counter({
+      name,
+      help,
+      labelNames,
+      registers: [this.registry],
+    })
+    this.counters[name] = c
+
+    const triggerFn = (data = {}, value = 1) => {
+      c.inc({ ...this.defaultLabels, ...data }, value)
+    }
+
+    this.counters[name].triggerFn = triggerFn
+    return triggerFn
+  }
+
+  /**
+   * Get CPU usage percent (cgroup-aware)
+   * @returns {number}
+   */
+  getCpuUsagePercent = () => {
+    try {
+      const stat = fs.readFileSync('/sys/fs/cgroup/cpu.stat', 'utf-8')
+      const match = stat.match(/usage_usec (\d+)/)
+      if (!match) return 0
+
+      const now = Date.now()
+      const currentUsage = parseInt(match[1], 10)
+
+      if (this._lastUsageMicros === 0) {
+        this._lastUsageMicros = currentUsage
+        this._lastCheckTime = now
+        return 0
+      }
+
+      const deltaUsage = currentUsage - this._lastUsageMicros
+      const deltaTime = now - this._lastCheckTime
+
+      this._lastUsageMicros = currentUsage
+      this._lastCheckTime = now
+
+      return (deltaUsage / (deltaTime * 1000)) * 100
+    } catch {
+      return 0
+    }
+  }
+
+  /**
+   * Get available CPU cores.
+   * @returns {number}
+   */
+  getAvailableCPUs() {
+    try {
+      const cpuMaxPath = '/sys/fs/cgroup/cpu.max'
+      if (fs.existsSync(cpuMaxPath)) {
+        const [quotaStr, periodStr] = fs
+          .readFileSync(cpuMaxPath, 'utf8')
+          .trim()
+          .split(' ')
+        if (quotaStr === 'max') return os.cpus().length
+        return parseInt(quotaStr, 10) / parseInt(periodStr, 10)
+      }
+      return os.cpus().length
+    } catch {
+      return 1
+    }
+  }
+
+  /**
+   * Get container memory usage in bytes.
+   * @returns {number}
+   */
+  getContainerMemoryUsage() {
+    try {
+      return parseInt(
+        fs.readFileSync('/sys/fs/cgroup/memory.current', 'utf-8').trim(),
+        10
+      )
+    } catch {
+      return process.memoryUsage().rss
+    }
+  }
+
+  /**
+   * Get container memory limit in bytes.
+   * @returns {number}
+   */
+  getContainerMemoryLimit() {
+    try {
+      const path = '/sys/fs/cgroup/memory.max'
+      if (fs.existsSync(path)) {
+        const val = fs.readFileSync(path, 'utf-8').trim()
+        if (val !== 'max') {
+          const parsed = parseInt(val, 10)
+          if (parsed && parsed < os.totalmem()) return parsed
+        }
+      }
+      return os.totalmem()
+    } catch {
+      return os.totalmem()
+    }
+  }
+
+  /**
+   * Measure event loop lag in ms.
+   * @returns {Promise<number>}
+   */
+  measureLag() {
+    return new Promise(resolve => {
+      const start = Date.now()
+      setImmediate(() => resolve(Date.now() - start))
+    })
+  }
+
+  /**
+   * Express middleware to count HTTP requests.
+   * Increments the `app_http_requests_total` counter.
+   */
+  countHttpRequestMiddleware = (req, res, next) => {
+    const start = Date.now()
+    res.on('finish', () => {
+      const route = req.route?.path || req.path || 'unknown'
+      const appId =
+        req.params?.appId || req.body?.appId || req.query?.appId || ''
+      const databaseId =
+        req.params?.databaseId ||
+        req.body?.databaseId ||
+        req.query?.databaseId ||
+        ''
+
+      this.counters?.app_http_requests_total?.triggerFn({
+        method: req.method,
+        route,
+        status_code: res.statusCode,
+        appId,
+        databaseId,
+        duration: Date.now() - start,
+        requestSize: req.headers['content-length']
+          ? parseInt(req.headers['content-length'], 10)
+          : 0,
+      })
+    })
+
+    next()
+  }
+
+  /**
+   * Push all gauges and counters to PushGateway and optionally log.
+   */
+  pushMetrics = async () => {
+    try {
+      for (const [name, updateFn] of Object.entries(this.gaugeUpdaters)) {
+        try {
+          const result = updateFn()
+          const val = result instanceof Promise ? await result : result
+          if (val !== undefined) this.gauges[name].set(this.defaultLabels, val)
+        } catch (err) {
+          console.error(
+            `${this.prefixLogs} Failed to update gauge ${name}:`,
+            err
+          )
+        }
+      }
+
+      await this.gateway.push({
+        jobName: this.appName,
+        groupings: { process_type: this.processType, instance: this.dynoId },
+      })
+
+      Object.values(this.counters).forEach(counter => counter.reset())
+
+      if (this.logValues) {
+        const metrics = await this.registry.getMetricsAsJSON()
+        console.log(
+          `${this.prefixLogs} Metrics:\n`,
+          JSON.stringify(metrics, null, 2)
+        )
+      }
+    } catch (err) {
+      console.error(`${this.prefixLogs} Failed to push metrics:`, err)
+    }
+  }
+
+  /**
+   * Start automatic periodic push of metrics.
+   * @param {number} [interval] Interval in seconds
+   */
+  startPush = (interval = this.intervalSec) => {
+    if (!this.enabled) {
+      console.warn(`${this.prefixLogs} Metrics disabled`)
+    }
+
+    setInterval(() => {
+      this.pushMetrics().catch(err => {
+        console.error(`${this.prefixLogs} Failed to push metrics:`, err)
+      })
+    }, interval * 1000)
+
+    console.warn(`${this.prefixLogs} Metrics collection started.`)
+  }
+}
+
+module.exports = { MetricsClient }

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "isolatedModules": false,
+    "lib": ["ESNext"],
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "./lib",
+    "strict": true,
+    "suppressImplicitAnyIndexErrors": true,
+    "target": "ESNext",
+    "resolveJsonModule": true,
+    "noEmit": true
+  },
+  "include": ["./src"],
+  "exclude": ["./node_modules"]
+}

package/tsconfig.types.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "noEmit": false,
+    "sourceMap": true
+  },
+  "exclude": ["**/__tests__/**", "**/*.test.js", "**/*.test.ts"]
+}