@adalo/metrics 0.1.114 → 0.1.116

package/src/baseMetricsClient.js

@@ -0,0 +1,410 @@
+const client = require('prom-client')
+const https = require('https')
+
+/**
+ * BaseMetricsClient provides common functionality for all metrics clients.
+ * Handles registry setup, pushgateway, default labels, and common operations.
+ */
+class BaseMetricsClient {
+  /**
+   * @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.pushgatewaySecret] PushGateway secret token
+   * @param {number} [config.intervalSec] Interval in seconds for pushing metrics
+   * @param {boolean} [config.removeOldMetrics] Enable to clear metrics by service name
+   * @param {function} [config.startupValidation] Add to validate on start push.
+   */
+  constructor(config = {}) {
+    this.appName = config.appName || process.env.BUILD_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.authToken =
+      config.pushgatewaySecret || process.env.METRICS_PUSHGATEWAY_SECRET || ''
+    this.intervalSec =
+      config.intervalSec ||
+      parseInt(process.env.METRICS_INTERVAL_SEC || '', 10) ||
+      15
+    this.startupValidation = config.startupValidation
+
+    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,
+    }
+
+    this.gateway = new client.Pushgateway(
+      this.pushgatewayUrl,
+      {
+        headers: { Authorization: `Basic ${this.authToken}` },
+        agent: new https.Agent({ keepAlive: true }),
+      },
+      this._registry
+    )
+    this.gauges = {}
+    this.counters = {}
+    this.countersFunctions = {}
+
+    /** @type {Object<string, function(): number | Promise<number>>} */
+    this.gaugeUpdaters = {}
+
+    this._clearOldWorkers(config.removeOldMetrics)
+    this._setCleanupHandlers()
+  }
+
+  /**
+   * Create a gauge metric.
+   * @param {Object} options - Gauge configuration
+   * @param {string} options.name - Name of the gauge
+   * @param {string} options.help - Help text describing the gauge
+   * @param {function(): number|Promise<number>} [options.updateFn] - Optional function returning the gauge value
+   * @param {string[]} [options.labelNames] - Optional custom label names
+   * @returns {import('prom-client').Gauge} The created Prometheus 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 (updateFn && typeof updateFn === 'function') {
+      this.gaugeUpdaters[name] = updateFn
+    }
+
+    return g
+  }
+
+  /**
+   * Create a Prometheus Counter metric.
+   *
+   * @param {Object} params - Counter configuration
+   * @param {string} params.name - Metric name
+   * @param {string} params.help - Metric description
+   * @param {string[]} [params.labelNames] - Optional list of label names. Defaults to this.defaultLabels keys.
+   *
+   * @returns {(labels?: Object, incrementValue?: number) => void}
+   *          A function to increment the counter.
+   *          Usage: (labels?, incrementValue?)
+   */
+  createCounter({ name, help, labelNames = Object.keys(this.defaultLabels) }) {
+    if (this.counters[name]) return this.countersFunctions[name]
+
+    const c = new client.Counter({
+      name,
+      help,
+      labelNames,
+      registers: [this._registry],
+    })
+    this.counters[name] = c
+
+    this.countersFunctions = {
+      ...this.countersFunctions,
+      [name]: (data = {}, value = 1) => {
+        c.inc({ ...this.defaultLabels, ...data }, value)
+      },
+    }
+
+    return this.countersFunctions[name]
+  }
+
+  /**
+   * Clear all collected counters
+   */
+  clearAllCounters = () => {
+    if (this.metricsLogValues) {
+      console.log('Counters to clear: ', Object.keys(this.counters))
+    }
+    Object.values(this.counters).forEach(counter => counter.reset())
+  }
+
+  /**
+   * Push all gauges and counters to PushGateway and optionally log.
+   */
+  pushMetrics = async () => {
+    try {
+      for (const [name, updateFn] of Object.entries(this.gaugeUpdaters)) {
+        try {
+          if (!updateFn) {
+            return
+          }
+          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.gatewayPush()
+      this.clearAllCounters()
+
+      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)
+    }
+  }
+
+  _startPush = (interval = this.intervalSec, customPushMetics = undefined) => {
+    if (!this.enabled) {
+      console.warn(`${this.prefixLogs} Metrics disabled`)
+      return
+    }
+
+    if (this.startupValidation && !this.startupValidation()) {
+      return
+    }
+
+    if (customPushMetics && typeof customPushMetics === 'function') {
+      setInterval(() => customPushMetics(), interval * 1000)
+    } else {
+      setInterval(() => {
+        this.pushMetrics().catch(err => {
+          console.error(`${this.prefixLogs} Failed to push metrics:`, err)
+        })
+      }, interval * 1000)
+    }
+
+    console.warn(
+      `${this.prefixLogs} Metrics collection started. (interval: ${this.intervalSec}s)`
+    )
+  }
+
+  /**
+   * Start periodic metrics collection and push.
+   *
+   * This method wraps the internal `_startPush` method.
+   * If a `customPushMetrics` function is provided, it will be executed
+   * at the given interval instead of the default `pushMetrics` behavior.
+   *
+   * @param {number} [interval=this.intervalSec] - Interval in seconds between pushes.
+   * @param {() => void | Promise<void>} [customPushMetrics] - Optional custom push function. If provided, Prometheus push is skipped.
+   */
+  startPush = (interval, customPushMetics = undefined) => {
+    this._startPush(interval, customPushMetics)
+  }
+
+  /**
+   * Cleanup metrics and exit process.
+   * @returns {Promise<void>}
+   */
+  cleanup = async () => {
+    if (this.enabled) {
+      await this.gatewayDelete()
+    }
+    process.exit(0)
+  }
+
+  /**
+   * Remove old/stale dyno/instance metrics from PushGateway.
+   *
+   * Compares existing PushGateway metrics for this job and deletes any instances
+   * that do not match the current dynoId.
+   *
+   * @param {boolean} removeOldMetrics If true, performs cleanup; otherwise does nothing
+   * @returns {Promise<void>}
+   * @private
+   */
+  _clearOldWorkers = async removeOldMetrics => {
+    if (!removeOldMetrics) return
+
+    try {
+      const url = `${this.pushgatewayUrl}/metrics`
+      const res = await fetch(url, {
+        headers: {
+          Authorization: `Basic ${this.authToken}`,
+          Accept: 'text/plain',
+        },
+      })
+
+      if (!res.ok) {
+        console.error(
+          `${this.prefixLogs} Failed to fetch metrics: ${res.status}`
+        )
+        return
+      }
+
+      const text = await res.text()
+
+      const metricRegex = /([a-zA-Z_:][a-zA-Z0-9_:]*)\{([^}]*)\}/gm
+      const labelRegex = /(\w+)="([^"]*)"/g
+
+      const uniqueLabelSets = new Set()
+
+      let match
+      // eslint-disable-next-line no-cond-assign
+      while ((match = metricRegex.exec(text)) !== null) {
+        const rawLabels = match[2]
+        let lr
+        const labels = {}
+
+        // eslint-disable-next-line no-cond-assign
+        while ((lr = labelRegex.exec(rawLabels)) !== null) {
+          // eslint-disable-next-line prefer-destructuring
+          labels[lr[1]] = lr[2]
+        }
+
+        if (
+          labels.job === this.appName &&
+          labels.process_type === this.processType
+        ) {
+          uniqueLabelSets.add(JSON.stringify(labels))
+        }
+      }
+
+      if (uniqueLabelSets.size === 0) {
+        console.log(
+          `${this.prefixLogs} No metrics found for job ${this.appName}`
+        )
+        return
+      }
+
+      const oldLabelSets = [...uniqueLabelSets]
+        .map(s => JSON.parse(s))
+        .filter(
+          labels =>
+            labels.instance &&
+            labels.instance !== this.dynoId &&
+            labels.process_type === this.processType
+        )
+
+      if (oldLabelSets.length === 0) {
+        console.log(`${this.prefixLogs} No old dynos to delete.`)
+        return
+      }
+
+      for (const labels of oldLabelSets) {
+        try {
+          await this.gatewayDelete({ jobName: this.appName, groupings: labels })
+          console.log(
+            `${this.prefixLogs} Deleted metrics for dyno: ${
+              labels.instance
+            }, labels: ${Object.keys(labels)} `
+          )
+        } catch (err) {
+          console.error(
+            `${this.prefixLogs} Failed to delete metrics for ${labels.instance}:`,
+            err
+          )
+        }
+      }
+
+      console.log(
+        `${this.prefixLogs} Cleared all old instances for job ${this.appName}`
+      )
+    } catch (err) {
+      console.error(`${this.prefixLogs} Error deleting old metrics:`, err)
+    }
+  }
+
+  /**
+   * Delete metrics for this job/instance from PushGateway.
+   *
+   * @param {Object} [params]
+   * @param {string} [params.jobName] Job name (defaults to appName)
+   * @param {Object} [params.groupings] Grouping labels
+   * @param {string} [params.groupings.process_type] Process type label
+   * @param {string} [params.groupings.instance] Instance/dyno ID
+   * @returns {Promise<void>}
+   */
+  gatewayDelete = async (params = {}) => {
+    return this.gateway.delete({
+      jobName: params.jobName || this.appName,
+      groupings: params.groupings || {
+        process_type: this.processType,
+        instance: this.dynoId,
+      },
+    })
+  }
+
+  /**
+   * Push metrics to PushGateway.
+   *
+   * @param {object} [params]
+   * @param {string} [params.jobName]
+   * @param {object} [params.groupings]
+   * @returns {Promise<void>}
+   */
+  gatewayPush = async (params = {}) => {
+    const groupings = {
+      process_type: this.processType,
+      instance: this.dynoId,
+      ...(params.groupings || {}),
+    }
+    return this.gateway.push({
+      jobName: params.jobName || this.appName,
+      groupings,
+    })
+  }
+
+  /**
+   * Merge the default metric labels (`app`, `dyno_id`, `process_type`)
+   * with custom label names.
+   *
+   * @param {string[]} labels Additional label names
+   * @returns {string[]} Combined label names
+   */
+  withDefaultLabels = (labels = []) => {
+    return [...Object.keys(this.defaultLabels), ...labels]
+  }
+
+  getDefaultLabels = (labels = []) => {
+    return this.defaultLabels
+  }
+
+  _setCleanupHandlers = () => {
+    process.on('SIGINT', this.cleanup)
+    process.on('SIGTERM', this.cleanup)
+  }
+
+  // GETTERS
+
+  get metricsEnabled() {
+    return this.enabled
+  }
+
+  get metricsLogValues() {
+    return this.logValues
+  }
+
+  get registry() {
+    return this._registry
+  }
+}
+
+module.exports = { BaseMetricsClient }

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './baseMetricsClient'
 export * from './metricsClient'
 export * from './metricsRedisClient'
 export * from './metricsQueueRedisClient'