@adalo/metrics 0.0.0-staging.1

package/src/metrics/baseMetricsClient.js

@@ -0,0 +1,494 @@
+const client = require('prom-client')
+const https = require('https')
+const http = require('http')
+const { URL } = require('url')
+
+/**
+ * BaseMetricsClient provides common functionality for all metrics clients.
+ * Handles registry setup, push to remote (VM-agent), default labels, and common operations.
+ * Always pushes registry to the configured URL (POST Prometheus text format + Basic auth). No Pushgateway.
+ */
+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] Push URL (VM-agent import endpoint, e.g. .../api/v1/import/prometheus). /metrics is for GET (scrape), not POST (push).
+   * @param {string} [config.pushgatewaySecret] Basic auth secret (Base64 of user:password)
+   * @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.
+   * @param {boolean} [config.disablePushgateway] Disable pushing to Pushgateway (use HTTP scraping instead)
+   */
+  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.disablePushgateway =
+      config.disablePushgateway ??
+      process.env.METRICS_DISABLE_PUSHGATEWAY === 'true'
+    this.removeOldMetrics =
+      config.removeOldMetrics ??
+      process.env.METRICS_REMOVE_OLD_METRICS === 'true'
+
+    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,
+    }
+
+    // Always push to configured URL (VM-agent). No Pushgateway.
+    this.gateway = null
+    this.gauges = {}
+    this.counters = {}
+    this.countersFunctions = {}
+
+    /** @type {Object<string, function(): number | Promise<number>>} */
+    this.gaugeUpdaters = {}
+
+    this._clearOldWorkers(config.removeOldMetrics)
+    this._setCleanupHandlers()
+
+    this.keepProcessAliveWhenDisabled = true
+  }
+
+  /**
+   * 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) {
+            continue
+          }
+          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
+          )
+        }
+      }
+
+      if (!this.disablePushgateway) {
+        await this.gatewayPush()
+      }
+      // this.clearAllCounters() //TODO: or uncommit or delete (based on grafana expectation)
+
+      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`)
+      if (this.keepProcessAliveWhenDisabled && !this._idleInterval) {
+        this._idleInterval = setInterval(() => {}, 60 * 60 * 1000)
+      }
+      return
+    }
+
+    if (this._idleInterval) {
+      clearInterval(this._idleInterval)
+      this._idleInterval = null
+    }
+
+    if (this.startupValidation && !this.startupValidation()) {
+      return
+    }
+
+    const runPush = () => {
+      if (customPushMetics && typeof customPushMetics === 'function') {
+        return Promise.resolve(customPushMetics())
+      }
+      return this.pushMetrics()
+    }
+
+    if (customPushMetics && typeof customPushMetics === 'function') {
+      setInterval(() => customPushMetics(), interval * 1000)
+    } else {
+      setInterval(() => {
+        runPush().catch(err => {
+          console.error(`${this.prefixLogs} Failed to push metrics:`, err)
+        })
+      }, interval * 1000)
+    }
+
+    // First push immediately so metrics appear without waiting for the first interval
+    runPush().catch(err => {
+      console.error(`${this.prefixLogs} Failed to push metrics (initial):`, err)
+    })
+
+    let pushOrigin = 'none'
+    try {
+      if (this.pushgatewayUrl && this.pushgatewayUrl.trim()) {
+        pushOrigin = new URL(this.pushgatewayUrl.trim()).origin
+      }
+    } catch {
+      pushOrigin = 'invalid URL'
+    }
+    console.warn(
+      `${this.prefixLogs} Metrics collection started. (interval: ${this.intervalSec}s, push: ${pushOrigin})`
+    )
+  }
+
+  pushMetrics = async () => {
+    return this._pushMetrics()
+  }
+
+  /**
+   * 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 => {
+    // No Pushgateway; VM-agent does not support per-instance delete. Skip.
+  }
+
+  /**
+   * On shutdown: optionally delete this instance's metrics from VictoriaMetrics (by app, dyno_id, process_type).
+   * @returns {Promise<void>}
+   */
+  gatewayDelete = async () => {
+    if (
+      this.removeOldMetrics &&
+      this.pushgatewayUrl &&
+      this.pushgatewayUrl.trim()
+    ) {
+      await this._deleteFromVMByLabels().catch(err => {
+        console.warn(
+          `${this.prefixLogs} Deletion from VM on shutdown failed:`,
+          err.message
+        )
+      })
+    }
+  }
+
+  /**
+   * Call VictoriaMetrics delete_series API to remove all series matching this instance's labels (app, dyno_id, process_type).
+   * @private
+   */
+  _deleteFromVMByLabels = () => {
+    const esc = s => String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+    const selector = `{app="${esc(this.appName)}",dyno_id="${esc(
+      this.dynoId
+    )}",process_type="${esc(this.processType)}"}`
+    let origin
+    try {
+      const u = new URL((this.pushgatewayUrl || '').trim())
+      origin = u.origin
+    } catch {
+      return Promise.reject(new Error('Invalid push URL'))
+    }
+    const path = `/api/v1/admin/tsdb/delete_series?match[]=${encodeURIComponent(
+      selector
+    )}`
+    return new Promise((resolve, reject) => {
+      const u = new URL(origin)
+      const req = (u.protocol === 'https:' ? https : http).request(
+        {
+          hostname: u.hostname,
+          port: u.port || (u.protocol === 'https:' ? 443 : 80),
+          path,
+          method: 'POST',
+          headers: {
+            'Content-Length': '0',
+            Authorization: this.authToken
+              ? `Basic ${this.authToken}`
+              : undefined,
+          },
+          agent:
+            u.protocol === 'https:'
+              ? new https.Agent({ keepAlive: false })
+              : undefined,
+        },
+        res => {
+          if (res.statusCode >= 200 && res.statusCode < 300) resolve()
+          else {
+            let data = ''
+            res.on('data', chunk => {
+              data += chunk
+            })
+            res.on('end', () =>
+              reject(new Error(`Delete failed: ${res.statusCode} ${data}`))
+            )
+          }
+        }
+      )
+      req.on('error', reject)
+      req.end()
+    })
+  }
+
+  /**
+   * Push registry to configured URL (VM-agent). POST Prometheus text format + Basic auth.
+   *
+   * @param {object} [params] Unused; kept for API compatibility.
+   * @returns {Promise<void>}
+   */
+  gatewayPush = async (params = {}) => {
+    if (this.disablePushgateway) {
+      console.warn(
+        `${this.prefixLogs} Metrics push skipped: METRICS_DISABLE_PUSHGATEWAY is set`
+      )
+      return Promise.resolve()
+    }
+    if (!this.pushgatewayUrl || !this.pushgatewayUrl.trim()) {
+      console.warn(
+        `${this.prefixLogs} Metrics push skipped: METRICS_PUSHGATEWAY_URL is not set`
+      )
+      return Promise.resolve()
+    }
+    return this._pushToVMAgent()
+  }
+
+  /**
+   * POST registry (Prometheus text format) to VM-agent. VM-agent accepts push at /api/v1/import/prometheus; /metrics is GET (scrape) only.
+   * @private
+   */
+  _pushToVMAgent = () => {
+    let pushUrl = (this.pushgatewayUrl || '').trim()
+    try {
+      const u = new URL(pushUrl)
+      if (!u.pathname || u.pathname === '/' || u.pathname === '/metrics') {
+        pushUrl = `${u.origin}/api/v1/import/prometheus${u.search}`
+      }
+    } catch {
+      // leave pushUrl as-is
+    }
+    return new Promise((resolve, reject) => {
+      const u = new URL(pushUrl)
+      const req = (u.protocol === 'https:' ? https : http).request(
+        {
+          hostname: u.hostname,
+          port: u.port || (u.protocol === 'https:' ? 443 : 80),
+          path: u.pathname + u.search,
+          method: 'POST',
+          headers: {
+            'Content-Type': client.register.contentType,
+            Authorization: this.authToken
+              ? `Basic ${this.authToken}`
+              : undefined,
+          },
+          agent:
+            u.protocol === 'https:'
+              ? new https.Agent({ keepAlive: true })
+              : undefined,
+        },
+        res => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve()
+          } else {
+            let data = ''
+            res.on('data', chunk => {
+              data += chunk
+            })
+            res.on('end', () =>
+              reject(new Error(`Push failed: ${res.statusCode} ${data}`))
+            )
+          }
+        }
+      )
+      req.on('error', reject)
+      this._registry
+        .metrics()
+        .then(metrics => {
+          req.setHeader('Content-Length', Buffer.byteLength(metrics, 'utf8'))
+          req.end(metrics, 'utf8')
+        })
+        .catch(reject)
+    })
+  }
+
+  /**
+   * 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
+  }
+
+  async getMetricsAsString() {
+    return this._registry.metrics()
+  }
+
+  metricsMiddleware() {
+    return async (req, res) => {
+      try {
+        const metrics = await this.getMetricsAsString()
+        res.set('Content-Type', client.register.contentType)
+        res.end(metrics)
+      } catch (err) {
+        console.error(`${this.prefixLogs} Failed to get metrics:`, err)
+        res.status(500).end('Failed to collect metrics')
+      }
+    }
+  }
+}
+
+module.exports = { BaseMetricsClient }