@adalo/metrics 0.0.0-staging.1

package/src/metrics/metricsRedisClient.js

@@ -0,0 +1,417 @@
+const { BaseMetricsClient } = require('./baseMetricsClient')
+const {
+  getRedisClientType,
+  REDIS_V4,
+  IOREDIS,
+  REDIS_V3,
+} = require('../redisUtils')
+
+const redisConnectionStableFields = ['name', 'flags', 'cmd']
+const redisConnectionFields = ['name', 'flags', 'tot-mem', 'cmd']
+
+/**
+ * RedisMetricsClient extends BaseMetricsClient to collect
+ * Redis metrics periodically and push them to Prometheus Pushgateway.
+ *
+ * @extends BaseMetricsClient
+ */
+class RedisMetricsClient extends BaseMetricsClient {
+  /**
+   * @param {Object} options
+   * @param {any} options.redisClient - Redis client instance (required)
+   * @param {string} [options.appName] - Application name (from BaseMetricsClient)
+   * @param {string} [options.dynoId] - Dyno/instance ID (from BaseMetricsClient)
+   * @param {string} [options.processType] - Process type (from BaseMetricsClient)
+   * @param {boolean} [options.enabled] - Enable metrics collection (from BaseMetricsClient)
+   * @param {boolean} [options.logValues] - Log metrics values (from BaseMetricsClient)
+   * @param {string} [options.pushgatewayUrl] - PushGateway URL (from BaseMetricsClient)
+   * @param {string} [options.pushgatewaySecret] - PushGateway secret token (from BaseMetricsClient)
+   * @param {number} [options.intervalSec] - Interval in seconds for pushing metrics (from BaseMetricsClient)
+   * @param {boolean} [options.removeOldMetrics] - Remove old metrics by service (from BaseMetricsClient)
+   * @param {function} [options.startupValidation] - Function to validate startup (from BaseMetricsClient)
+   * @param {boolean} [options.disablePushgateway] - Disable pushing to Pushgateway (use HTTP scraping instead)
+   */
+  constructor({ redisClient, ...metricsConfig } = {}) {
+    if (redisClient == null) {
+      throw new Error('RedisMetricsClient requires redisClient')
+    }
+
+    const intervalSec =
+      metricsConfig.intervalSec ||
+      parseInt(process.env.METRICS_QUEUE_INTERVAL_SEC || '', 10) ||
+      5
+
+    super({
+      ...metricsConfig,
+      processType: metricsConfig.processType || 'queue-metrics',
+      intervalSec,
+    })
+
+    /** Redis client used for metrics */
+    this.redisClient = redisClient
+    this.redisClientType = getRedisClientType(redisClient)
+
+    /** Label names for Redis metrics: app + process_type only (no dyno_id). */
+    this._redisLabelNames = ['app', 'process_type']
+
+    /** Counter for Redis connection metrics */
+    this.redisConnectionsGauge = this.createGauge({
+      name: 'app_redis_connections_count',
+      help: 'Redis client connections',
+      labelNames: [...this._redisLabelNames, ...redisConnectionStableFields],
+    })
+
+    this.redisConnectionsMemoryGauge = this.createGauge({
+      name: 'app_redis_connections_memory_usage_count',
+      help: 'Redis client connections',
+      labelNames: [...this._redisLabelNames, ...redisConnectionStableFields],
+    })
+
+    /** Gauge for Redis memory usage */
+    this.redisMemoryGauge = this.createGauge({
+      name: 'app_redis_memory_bytes',
+      help: 'Redis memory usage in bytes',
+      labelNames: [...this._redisLabelNames, 'memory_type'],
+    })
+
+    /** Gauge for Redis operation stats */
+    this.redisStatsGauge = this.createGauge({
+      name: 'app_redis_stats_total',
+      help: 'Redis operation statistics',
+      labelNames: [...this._redisLabelNames, 'operation'],
+    })
+
+    // Track emitted connection label combinations so we can:
+    // - emit a one-shot 0 for series that disappear (overwrite last non-zero sample)
+    // - then stop emitting them on subsequent scrapes
+    //
+    // This is mainly needed because we label connections by `cmd`,
+    // and Redis `CLIENT LIST` `cmd` is volatile.
+    this._redisConnSeenKeys = new Set()
+    this._redisConnZeroedKeys = new Set()
+
+    this._setCleanupHandlers()
+  }
+
+  getRedisConnections = async () => {
+    if (!this.redisClient) throw new Error('Redis client not provided')
+
+    // node-redis v3 (uses callback)
+    if (this.redisClientType === REDIS_V3) {
+      return new Promise((resolve, reject) => {
+        this.redisClient.send_command('CLIENT', ['LIST'], (err, result) => {
+          if (err) {
+            reject(new Error(`Failed to get CLIENT LIST: ${err.message}`))
+          } else resolve(result)
+        })
+      })
+    }
+
+    // node-redis v4
+    if (this.redisClientType === REDIS_V4) {
+      try {
+        return this.redisClient.sendCommand(['CLIENT', 'LIST'])
+      } catch (err) {
+        throw new Error(`Failed to get CLIENT LIST: ${err.message}`)
+      }
+    }
+
+    if (this.redisClientType === IOREDIS) {
+      try {
+        return this.redisClient.client('LIST')
+      } catch (err) {
+        throw new Error(`Failed to get CLIENT LIST: ${err.message}`)
+      }
+    }
+
+    throw new Error('Unsupported Redis client type')
+  }
+
+  getRedisInfo = async section => {
+    if (!this.redisClient) throw new Error('Redis client not provided')
+
+    // node-redis v3 (uses callback)
+    if (this.redisClientType === REDIS_V3) {
+      return new Promise((resolve, reject) => {
+        this.redisClient.info(section, (err, result) => {
+          if (err) reject(err)
+          else resolve(result)
+        })
+      })
+    }
+
+    // node-redis v4 or ioredis (info returns Promise)
+    if (this.redisClientType === REDIS_V4 || this.redisClientType === IOREDIS) {
+      try {
+        return this.redisClient.info(section)
+      } catch (err) {
+        throw new Error(`Failed to get Redis INFO: ${err.message}`)
+      }
+    }
+
+    throw new Error('Unsupported Redis client type')
+  }
+
+  parseRedisConnections = clientsStr => {
+    return clientsStr
+      .split('\n')
+      .filter(line => line.trim() !== '')
+      .map(line => {
+        const parts = line.split(' ')
+        const client = {}
+        parts.forEach(p => {
+          const eqIdx = p.indexOf('=')
+          if (eqIdx === -1) return
+          const k = p.slice(0, eqIdx)
+          const v = p.slice(eqIdx + 1)
+          if (redisConnectionFields.includes(k)) {
+            client[k] = v
+          }
+        })
+        return client
+      })
+  }
+
+  /**
+   * Collect basic Redis INFO metrics: clients, memory, stats
+   * @returns {Promise<void>}
+   */
+  collectRedisMetrics = async () => {
+    try {
+      const [memoryInfoStr, statsInfoStr, connectionsInfoStr] =
+        await Promise.all([
+          this.getRedisInfo('memory'),
+          this.getRedisInfo('stats'),
+          this.getRedisConnections(),
+        ])
+
+      const labels = { app: this.appName, process_type: this.processType }
+
+      const connections = this.parseRedisConnections(connectionsInfoStr)
+
+      if (this.logValues) {
+        // "IN" data: raw client list from Redis
+        console.log(
+          '[queue-metrics] Redis CLIENT LIST (raw):\n',
+          connectionsInfoStr
+        )
+        console.log(
+          '[queue-metrics] Redis CLIENT LIST (raw) length:',
+          connectionsInfoStr.length
+        )
+
+        // "OUT" data: parsed fields used for metrics
+        console.log(
+          '[queue-metrics] Redis CLIENT LIST (parsed) count:',
+          connections.length
+        )
+        console.log(
+          '[queue-metrics] Redis CLIENT LIST (parsed sample, first 10):',
+          JSON.stringify(connections.slice(0, 10), null, 2)
+        )
+
+        const missing = { name: 0, flags: 0, cmd: 0, 'tot-mem': 0 }
+        connections.forEach(c => {
+          if (!c.name) missing.name += 1
+          if (!c.flags) missing.flags += 1
+          if (!c.cmd) missing.cmd += 1
+          if (!c['tot-mem']) missing['tot-mem'] += 1
+        })
+        console.log(
+          '[queue-metrics] Redis CLIENT LIST (parsed) missing fields:',
+          missing
+        )
+      }
+
+      const grouped = {}
+      connections.forEach(conn => {
+        const { name, flags, 'tot-mem': totMem, cmd } = conn
+
+        // build grouping key (includes default gauge labels later)
+        const key = JSON.stringify({ name, flags, cmd })
+
+        if (!grouped[key]) {
+          grouped[key] = {
+            labels: { name, flags, cmd },
+            count: 0,
+            memory: 0,
+          }
+        }
+
+        grouped[key].count += 1
+        const mem = parseInt(totMem, 10)
+        grouped[key].memory += Number.isFinite(mem) ? mem : 0
+      })
+
+      // Ensure sets exist even if older instance is hot-reloaded.
+      if (!this._redisConnSeenKeys) this._redisConnSeenKeys = new Set()
+      if (!this._redisConnZeroedKeys) this._redisConnZeroedKeys = new Set()
+
+      const currentKeys = new Set(Object.keys(grouped))
+      for (const k of currentKeys) {
+        this._redisConnSeenKeys.add(k)
+        if (this._redisConnZeroedKeys.has(k)) {
+          this._redisConnZeroedKeys.delete(k)
+        }
+      }
+
+      // Reset gauges each scrape so we only export:
+      // - current snapshot series
+      // - one-shot zeros for recently disappeared series
+      this.redisConnectionsGauge.reset()
+      this.redisConnectionsMemoryGauge.reset()
+
+      // Emit one-shot zeros for series that disappeared since last seen.
+      for (const k of this._redisConnSeenKeys) {
+        if (currentKeys.has(k)) continue
+        if (this._redisConnZeroedKeys.has(k)) continue
+        try {
+          const valueLabels = JSON.parse(k)
+          this.redisConnectionsGauge.set({ ...labels, ...valueLabels }, 0)
+          this.redisConnectionsMemoryGauge.set({ ...labels, ...valueLabels }, 0)
+          this._redisConnZeroedKeys.add(k)
+        } catch {
+          // ignore malformed key
+        }
+      }
+
+      if (this.logValues) {
+        const groups = Object.values(grouped)
+        const groupedTotal = groups.reduce((sum, g) => sum + (g.count || 0), 0)
+        console.log(
+          '[queue-metrics] Redis connections grouped buckets:',
+          groups.length
+        )
+        console.log(
+          '[queue-metrics] Redis connections grouped total:',
+          groupedTotal
+        )
+        console.log(
+          '[queue-metrics] Redis connections seen keys:',
+          this._redisConnSeenKeys.size
+        )
+        console.log(
+          '[queue-metrics] Redis connections zeroed keys:',
+          this._redisConnZeroedKeys.size
+        )
+        console.log(
+          '[queue-metrics] Redis connections grouped sample (first 10):',
+          JSON.stringify(groups.slice(0, 10), null, 2)
+        )
+      }
+
+      Object.values(grouped).forEach(
+        ({ labels: valueLabels, count, memory }) => {
+          this.redisConnectionsGauge.set({ ...labels, ...valueLabels }, count)
+          this.redisConnectionsMemoryGauge.set(
+            { ...labels, ...valueLabels },
+            memory
+          )
+        }
+      )
+
+      const parseRedisInfo = infoStr =>
+        Object.fromEntries(
+          infoStr
+            .split('\r\n')
+            .filter(line => line && !line.startsWith('#'))
+            .map(line => line.split(':', 2))
+            .filter(parts => parts.length === 2 && parts[0] && parts[1])
+        )
+
+      const memory = parseRedisInfo(memoryInfoStr)
+      const stats = parseRedisInfo(statsInfoStr)
+
+      if (memory.used_memory) {
+        this.redisMemoryGauge.set(
+          { ...labels, memory_type: 'used' },
+          parseInt(memory.used_memory, 10) || 0
+        )
+      }
+      if (memory.maxmemory) {
+        this.redisMemoryGauge.set(
+          { ...labels, memory_type: 'max' },
+          parseInt(memory.maxmemory, 10) || 0
+        )
+      }
+
+      if (stats.instantaneous_ops_per_sec) {
+        this.redisStatsGauge.set(
+          { ...labels, operation: 'ops_per_sec' },
+          parseInt(stats.instantaneous_ops_per_sec, 10) || 0
+        )
+      }
+    } catch (error) {
+      console.warn(
+        `[queue-metrics] Failed to collect Redis metrics:`,
+        error.message
+      )
+    }
+  }
+
+  /**
+   * Collect metrics for all Redis and push to Prometheus Pushgateway
+   * @returns {Promise<void>}
+   */
+  pushRedisMetrics = async () => {
+    try {
+      await this.collectRedisMetrics()
+      await this.gatewayPush()
+      this.clearAllCounters()
+
+      if (this.metricsLogValues) {
+        const metricObjects = await this.registry.getMetricsAsJSON()
+        console.info(
+          `[queue-metrics] Collected metrics for Redis`,
+          JSON.stringify(metricObjects, null, 2)
+        )
+      }
+    } catch (error) {
+      console.error(
+        `[queue-metrics] Failed to collect Redis metrics: ${error.message}`
+      )
+      throw error
+    }
+  }
+
+  /**
+   * Start periodic collection.
+   * @param {number} [intervalSec=this.intervalSec] - Interval in seconds
+   */
+  startPush = (intervalSec = this.intervalSec) => {
+    this._startPush(intervalSec, () => {
+      this.pushRedisMetrics().catch(err => {
+        console.error(`[queue-metrics] Failed to push Redis metrics:`, err)
+      })
+    })
+  }
+
+  /**
+   * Cleanup Redis client and exit process.
+   * @returns {Promise<void>}
+   */
+  cleanup = async () => {
+    try {
+      if (!this.redisClient) return
+
+      if (
+        this.redisClientType === REDIS_V3 ||
+        this.redisClientType === REDIS_V4
+      ) {
+        await this.redisClient.quit()
+      } else if (this.redisClientType === IOREDIS) {
+        await this.redisClient.disconnect()
+      }
+    } catch (err) {
+      console.error('[queue-metrics] Error closing Redis client:', err)
+    }
+    process.exit(0)
+  }
+
+  _setCleanupHandlers = () => {
+    process.on('SIGINT', this.cleanup)
+    process.on('SIGTERM', this.cleanup)
+  }
+}
+
+module.exports = { RedisMetricsClient }

package/src/redisUtils.js

@@ -0,0 +1,155 @@
+const REDIS_V4 = 'REDIS_V4'
+const REDIS_V3 = 'REDIS_V3'
+const IOREDIS = 'IOREDIS'
+
+const dyno = process.env.BUILD_DYNO_PROCESS_TYPE || 'undefined-dyno'
+const defaultAppName = process.env.BUILD_APP_NAME
+
+/**
+ * Get the default Redis client name.
+ *
+ * @param {Object} options - Options for generating Redis name.
+ * @param {string} [options.name='undefined-name'] - Fallback name if none is provided.
+ * @param {string} [options.appName] - Application name. Defaults to `defaultAppName` if not set.
+ * @param {string} [options.processName] - Process name. Defaults to `dyno` if not set.
+ * @returns {string} The generated Redis client name.
+ */
+const getRedisName = ({ name = 'undefined-name', appName, processName }) => {
+  return `${appName || defaultAppName || 'undefined-app'}:${
+    processName || dyno
+  }:${name}`
+}
+
+/**
+ * Creates a configured setClientName function for node-redis v3.
+ *
+ * @param {string} [appName='undefined-app'] - Fallback app name if BUILD_APP_NAME is not set.
+ * @returns {(client: any, name: string) => void}
+ */
+const createSetClientNameForRedisV3 = (appName = 'undefined-app') => {
+  return (client, name) => {
+    if (process.env.NODE_ENV !== 'test') {
+      client.on('connect', () => {
+        client.send_command(
+          'CLIENT',
+          [
+            'SETNAME',
+            getRedisName({ name, appName: defaultAppName || appName }),
+          ],
+          err => {
+            if (err) {
+              console.error(`Failed to set client name for ${name}:`, err)
+            } else {
+              console.log(`Connected to Redis for pid:${process.pid} (${name})`)
+            }
+          }
+        )
+      })
+    }
+  }
+}
+
+/**
+ * Creates a function to set Redis client name for ioredis.
+ *
+ * @param {string} [appName='undefined-app']
+ * @returns {(client: any, name: string) => void}
+ */
+const createSetClientNameForIoredis = (appName = 'undefined-app') => {
+  return (client, name) => {
+    if (process.env.NODE_ENV !== 'test') {
+      client.once('connect', () => {
+        client
+          .call('CLIENT', [
+            'SETNAME',
+            getRedisName({ name, appName: defaultAppName || appName }),
+          ])
+          .then(() => {
+            console.log(`Connected to Redis for pid:${process.pid} (${name})`)
+          })
+          .catch(err => {
+            console.error(`Failed to set client name for ${name}:`, err)
+          })
+      })
+    }
+  }
+}
+
+/**
+ * Creates a function to set Redis client name for node-redis v4.
+ *
+ * @param {string} [appName='undefined-app']
+ * @returns {(client: any, name: string) => void}
+ */
+const createSetClientNameForRedisV4 = (appName = 'undefined-app') => {
+  return (client, name) => {
+    if (process.env.NODE_ENV !== 'test') {
+      client.on('ready', async () => {
+        try {
+          await client.sendCommand([
+            'CLIENT',
+            'SETNAME',
+            getRedisName({ name, appName: defaultAppName || appName }),
+          ])
+          console.log(`Connected to Redis for pid:${process.pid} (${name})`)
+        } catch (err) {
+          console.error(`Failed to set client name for ${name}:`, err)
+        }
+      })
+    }
+  }
+}
+
+/**
+ * Check if a Redis client is an ioredis instance
+ *
+ * @param {any} client - Redis client instance
+ * @returns {boolean} True if the client is ioredis
+ */
+const isIORedis = client => {
+  return (
+    client &&
+    typeof client.sendCommand === 'function' &&
+    typeof client.disconnect === 'function' &&
+    client.options !== undefined
+  )
+}
+
+/**
+ * Get Redis client type
+ *
+ * @param {any} client - Redis client instance
+ * @returns {string} One of IOREDIS, REDIS_V3, REDIS_V4
+ */
+const getRedisClientType = client => {
+  if (typeof client?.send_command === 'function') {
+    console.log('Detected node-redis redis_v3')
+    return REDIS_V3
+  }
+  if (
+    typeof client?.info === 'function' &&
+    typeof client?.sendCommand === 'function' &&
+    typeof client?.setex !== 'function'
+  ) {
+    console.log('Detected node-redis redis_v4')
+    return REDIS_V4
+  }
+  if (isIORedis(client)) {
+    console.log('Detected node-redis ioredis')
+    return IOREDIS
+  }
+
+  throw new Error(`Failed to get Redis client type`)
+}
+
+module.exports = {
+  createSetClientNameForRedisV3,
+  createSetClientNameForRedisV4,
+  createSetClientNameForIoredis,
+  isIORedis,
+  getRedisClientType,
+  REDIS_V4,
+  REDIS_V3,
+  IOREDIS,
+  getRedisName,
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "isolatedModules": false,
+    "lib": ["ESNext", "DOM"],
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "./lib",
+    "strict": true,
+    "suppressImplicitAnyIndexErrors": true,
+    "target": "ESNext",
+    "resolveJsonModule": true,
+    "typeRoots": ["./node_modules/@types"]
+  },
+  "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"]
+}