@adalo/metrics 0.0.0-staging.1

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@adalo/metrics",
+  "version": "0.0.0-staging.1",
+  "description": "Reusable metrics utilities for Node.js and Laravel apps",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "babel src --out-dir lib --source-maps --extensions .js,.ts && yarn build:types",
+    "build:types": "tsc --project ./tsconfig.types.json",
+    "watch": "yarn build -- --watch",
+    "start": "yarn watch",
+    "test": "jest",
+    "test:watch": "yarn test --watch",
+    "test:all": "yarn format:check && yarn test",
+    "types:check": "tsc --project ./tsconfig.json",
+    "prettier": "prettier --write 'src/**'",
+    "prettier:check": "prettier --check 'src/**'",
+    "lint": "eslint --fix src --ext .js,.ts",
+    "lint:check": "eslint src --ext .js,.ts",
+    "format": "yarn prettier && yarn lint",
+    "format:check": "yarn prettier:check && yarn lint:check"
+  },
+  "author": "@AdaloHQ",
+  "license": "ISC",
+  "dependencies": {
+    "bee-queue": "^1.2.2",
+    "dotenv": "^8.2.0",
+    "mysql2": "^3.11.0",
+    "pg": "^8.16.3",
+    "prom-client": "^15.1.3",
+    "@types/pg": "^8.15.6"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.24.0",
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-typescript": "^7.24.0",
+    "@types/ioredis": "^5.0.0",
+    "@types/jest": "28.1.6",
+    "@types/node": "18.0.4",
+    "@types/redis": "2",
+    "@typescript-eslint/eslint-plugin": "5.30.6",
+    "@typescript-eslint/parser": "5.30.6",
+    "babel-jest": "28.1.3",
+    "eslint": "~8.4.1",
+    "eslint-config-airbnb-base": "~15.0.0",
+    "eslint-config-airbnb-typescript": "17.0.0",
+    "eslint-config-prettier": "~8.3.0",
+    "eslint-import-resolver-typescript": "2.7.1",
+    "eslint-plugin-import": "~2.25.3",
+    "jest": "28.1.3",
+    "prettier": "2.5.1",
+    "typescript": "4.7.4"
+  },
+  "resolutions": {
+    "@types/istanbul-lib-report": "^3.0.0"
+  },
+  "jest": {
+    "testMatch": [
+      "**/__tests__/**/*.[jt]s?(x)"
+    ]
+  },
+  "engines": {
+    "node": ">=13.0.0"
+  }
+}

package/scripts/README.md

@@ -0,0 +1,43 @@
+# This is utils for manage metrics
+
+
+## Type envs to handling require metrics 
+```js
+BUILD_APP_NAME=
+HOSTNAME=
+BUILD_DYNO_PROCESS_TYPE=
+METRICS_ENABLED=
+METRICS_LOG_VALUES=
+METRICS_PUSHGATEWAY_URL=
+METRICS_PUSHGATEWAY_SECRET=
+METRICS_INTERVAL_SEC=
+
+```
+
+
+## Clear metriks for service
+```
+node scripts/clearMetrics.js 
+```
+
+## Publish metrics to VM-agent (example)
+
+Publishes built-in gauges (CPU, memory, uptime, etc.) and an example custom gauge to VM-agent.
+
+1. Set env (or `.env`):
+   - `METRICS_PUSHGATEWAY_URL` – VM-agent import URL, e.g. `https://vm-agent.staging.infradalogs.adalo.com/api/v1/import/prometheus`
+   - `METRICS_PUSHGATEWAY_SECRET` – Base64 of `user:password` (same as VM-agent BASIC_USER / BASIC_PASSWORD)
+   - `METRICS_ENABLED=true`
+   - `METRICS_INTERVAL_SEC=15` (optional, default 15)
+
+2. Generate secret:
+   ```bash
+   echo -n 'user:password' | base64
+   ```
+
+3. Run:
+   ```bash
+   node scripts/publish-metrics-example.js
+   ```
+
+Metrics appear in VM-agent (and VictoriaMetrics) under names like `app_process_cpu_usage_percent`, `app_uptime_seconds`, `app_example_custom_total`, etc.

package/scripts/clearMetrics.js

@@ -0,0 +1,6 @@
+const { BaseMetricsClient } = require('../src')
+require('dotenv').config()
+
+new BaseMetricsClient({
+  removeOldMetrics: true,
+})

package/src/health/databaseChecker.js

@@ -0,0 +1,183 @@
+const { Pool } = require('pg')
+const mysql = require('mysql2/promise')
+
+const DB_TYPE_POSTGRES = 'postgres'
+const DB_TYPE_MYSQL = 'mysql'
+
+/**
+ * @returns {bigint}
+ */
+function nowNs() {
+  return process.hrtime.bigint()
+}
+
+/**
+ * @param {bigint} deltaNs
+ * @returns {number}
+ */
+function nsToMs(deltaNs) {
+  return Number(deltaNs) / 1_000_000
+}
+
+/**
+ * @param {string} url
+ * @returns {string} postgres | mysql
+ */
+function getDatabaseType(url) {
+  if (!url || typeof url !== 'string') return DB_TYPE_POSTGRES
+  const lower = url.toLowerCase()
+  if (lower.startsWith('mysql://') || lower.startsWith('mysql2://')) {
+    return DB_TYPE_MYSQL
+  }
+  if (lower.startsWith('mariadb://')) {
+    return DB_TYPE_MYSQL
+  }
+  return DB_TYPE_POSTGRES
+}
+
+/**
+ * @param {string} url
+ * @param {string} [type]
+ * @returns {{ host: string, port: number, user: string, password: string, database: string } | null}
+ */
+function parseConnectionUrl(url, type) {
+  try {
+    const parsed = new URL(url)
+    const defaultPort = type === DB_TYPE_MYSQL ? 3306 : 5432
+    const defaultDb = type === DB_TYPE_MYSQL ? 'mysql' : 'postgres'
+    return {
+      host: parsed.hostname || 'localhost',
+      port: parseInt(parsed.port || String(defaultPort), 10),
+      user: parsed.username || '',
+      password: parsed.password || '',
+      database: (parsed.pathname || '/').replace(/^\//, '') || defaultDb,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {string} env
+ * @param {string} url
+ * @param {number} connectionTimeoutMs
+ * @returns {{ pool: any, type: string }}
+ */
+function createDatabasePool(env, url, connectionTimeoutMs) {
+  const type = getDatabaseType(url)
+
+  if (type === DB_TYPE_MYSQL) {
+    const config = parseConnectionUrl(url, DB_TYPE_MYSQL)
+    if (!config) {
+      throw new Error(`Invalid MySQL URL for ${env}`)
+    }
+    const pool = mysql.createPool({
+      host: config.host,
+      port: config.port,
+      user: config.user,
+      password: config.password,
+      database: config.database,
+      connectionLimit: 1,
+      connectTimeout: connectionTimeoutMs,
+      waitForConnections: false,
+    })
+    return { pool, type: DB_TYPE_MYSQL }
+  }
+
+  const pool = new Pool({
+    connectionString: url,
+    max: 1,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: connectionTimeoutMs,
+  })
+  return { pool, type: DB_TYPE_POSTGRES }
+}
+
+/**
+ * @param {any} pool
+ * @param {string} type
+ * @returns {Promise<{ connectMs: number }>}
+ */
+async function runHealthCheck(pool, type) {
+  if (type === DB_TYPE_MYSQL) {
+    let connectMs = 0.0
+
+    /** @type {any} */
+    let conn
+    try {
+      const startConnect = nowNs()
+      conn = await pool.getConnection()
+      connectMs = nsToMs(nowNs() - startConnect)
+
+      await conn.query('SELECT 1')
+      return { connectMs }
+    } catch (err) {
+      err.healthCheckTimings = {
+        connectMs,
+      }
+      throw err
+    } finally {
+      if (conn) {
+        try {
+          // Destroy the connection so next check measures a real connect.
+          // mysql2 pooled connections support destroy() to remove it from the pool.
+          if (typeof conn.destroy === 'function') conn.destroy()
+          else if (typeof conn.end === 'function') await conn.end()
+          else if (typeof conn.release === 'function') conn.release()
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  let connectMs = 0.0
+
+  /** @type {import('pg').PoolClient | null} */
+  let client = null
+  try {
+    const startConnect = nowNs()
+    client = await pool.connect()
+    connectMs = nsToMs(nowNs() - startConnect)
+
+    await client.query('SELECT 1')
+    return { connectMs }
+  } catch (err) {
+    err.healthCheckTimings = {
+      connectMs,
+    }
+    throw err
+  } finally {
+    if (client) {
+      try {
+        // Force the pool to drop the client so next check measures a real connect.
+        // In node-postgres, passing a truthy value removes the client from the pool.
+        client.release(true)
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+/**
+ * @param {any} pool
+ * @returns {Promise<void>}
+ */
+async function closePool(pool) {
+  try {
+    await pool.end()
+  } catch {
+    // ignore
+  }
+}
+
+module.exports = {
+  getDatabaseType,
+  parseConnectionUrl,
+  createDatabasePool,
+  runHealthCheck,
+  closePool,
+  DB_TYPE_POSTGRES,
+  DB_TYPE_MYSQL,
+}

package/src/health/healthCheckCache.js

@@ -0,0 +1,216 @@
+const {
+  getRedisClientType,
+  REDIS_V4,
+  IOREDIS,
+  REDIS_V3,
+} = require('../redisUtils')
+
+/**
+ * HealthCheckCache provides a shared cache layer for health check results.
+ * It uses Redis if available for cross-process sharing, with graceful fallback
+ * to in-memory cache if Redis is not configured or unavailable.
+ */
+class HealthCheckCache {
+  /**
+   * @param {Object} options
+   * @param {any} [options.redisClient]
+   * @param {string} [options.cacheKey] - Redis key (e.g. 'health:database:status')
+   * @param {string} [options.appName] - Used when cacheKey not set: healthcheck:${appName}
+   * @param {number} [options.staleThresholdMs]
+   */
+  constructor(options = {}) {
+    this.redisClient = options.redisClient || null
+    this.appName =
+      options.appName || process.env.BUILD_APP_NAME || 'unknown-app'
+    this.staleThresholdMs = options.staleThresholdMs ?? 180_000
+    this.cacheKey = options.cacheKey || `healthcheck:${this.appName}`
+
+    /** In-memory fallback cache */
+    this._memoryCache = null
+    this._memoryCacheTimestamp = null
+
+    if (this.redisClient) {
+      this._redisClientType = getRedisClientType(this.redisClient)
+      this._redisAvailable = true
+    } else {
+      this._redisAvailable = false
+      console.warn(
+        `[HealthCheckCache] Redis not configured for ${this.appName}, using in-memory cache only (not shared across processes)`
+      )
+    }
+  }
+
+  /**
+   * Checks if Redis is available and working.
+   * @returns {Promise<boolean>}
+   * @private
+   */
+  async _checkRedisAvailable() {
+    if (!this.redisClient || !this._redisAvailable) {
+      return false
+    }
+
+    try {
+      let pong
+      if (this._redisClientType === REDIS_V3) {
+        pong = await new Promise((resolve, reject) => {
+          this.redisClient.ping((err, result) => {
+            if (err) reject(err)
+            else resolve(result)
+          })
+        })
+      } else if (
+        this._redisClientType === REDIS_V4 ||
+        this._redisClientType === IOREDIS
+      ) {
+        pong = await this.redisClient.ping()
+      } else {
+        return false
+      }
+      return pong === 'PONG'
+    } catch (err) {
+      if (this._redisAvailable) {
+        console.warn(
+          `[HealthCheckCache] Redis became unavailable: ${err.message}`
+        )
+        this._redisAvailable = false
+      }
+      return false
+    }
+  }
+
+  /**
+   * Gets cached health check result from Redis (if available) or in-memory cache.
+   * Throws error if Redis is configured but read fails (so caller can return proper error format).
+   * @returns {Promise<Object | null>} Cached result or null
+   * @throws {Error} If Redis is configured but read fails
+   */
+  async get() {
+    if (this.redisClient) {
+      try {
+        let cachedStr
+        if (this._redisClientType === REDIS_V3) {
+          cachedStr = await new Promise((resolve, reject) => {
+            this.redisClient.get(this.cacheKey, (err, result) => {
+              if (err) reject(err)
+              else resolve(result)
+            })
+          })
+        } else if (
+          this._redisClientType === REDIS_V4 ||
+          this._redisClientType === IOREDIS
+        ) {
+          cachedStr = await this.redisClient.get(this.cacheKey)
+        }
+
+        if (cachedStr) {
+          try {
+            const cached = JSON.parse(cachedStr)
+            if (cached.result && cached.timestamp) {
+              this._memoryCache = cached.result
+              this._memoryCacheTimestamp = cached.timestamp
+              return cached.result
+            }
+          } catch (parseErr) {
+            console.warn(
+              `[HealthCheckCache] Failed to parse Redis cache:`,
+              parseErr.message
+            )
+          }
+        }
+        return null
+      } catch (redisErr) {
+        this._redisAvailable = false
+        throw new Error(`Redis cache read failed: ${redisErr.message}`)
+      }
+    }
+
+    if (this._memoryCache && this._memoryCacheTimestamp) {
+      return this._memoryCache
+    }
+
+    return null
+  }
+
+  /**
+   * Sets cached health check result in Redis (if available) and in-memory.
+   * @param {Object} result - Health check result to cache
+   * @returns {Promise<void>}
+   */
+  async set(result) {
+    const cacheData = {
+      result,
+      timestamp: Date.now(),
+    }
+
+    this._memoryCache = result
+    this._memoryCacheTimestamp = cacheData.timestamp
+
+    if (await this._checkRedisAvailable()) {
+      try {
+        const cacheStr = JSON.stringify(cacheData)
+        const ttlSeconds = Math.ceil(this.staleThresholdMs / 1000) + 60
+
+        if (this._redisClientType === REDIS_V3) {
+          await new Promise((resolve, reject) => {
+            this.redisClient.setex(this.cacheKey, ttlSeconds, cacheStr, err => {
+              if (err) reject(err)
+              else resolve()
+            })
+          })
+        } else if (this._redisClientType === REDIS_V4) {
+          await this.redisClient.set(this.cacheKey, cacheStr, {
+            EX: ttlSeconds,
+          })
+        } else if (this._redisClientType === IOREDIS) {
+          await this.redisClient.setex(this.cacheKey, ttlSeconds, cacheStr)
+        }
+      } catch (redisErr) {
+        console.warn(
+          `[HealthCheckCache] Redis write failed (in-memory cache updated):`,
+          redisErr.message
+        )
+        this._redisAvailable = false
+      }
+    }
+  }
+
+  /**
+   * Clears the cache (both Redis and in-memory).
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this._memoryCache = null
+    this._memoryCacheTimestamp = null
+
+    if (await this._checkRedisAvailable()) {
+      try {
+        if (this._redisClientType === REDIS_V3) {
+          await new Promise((resolve, reject) => {
+            this.redisClient.del(this.cacheKey, err => {
+              if (err) reject(err)
+              else resolve()
+            })
+          })
+        } else if (
+          this._redisClientType === REDIS_V4 ||
+          this._redisClientType === IOREDIS
+        ) {
+          await this.redisClient.del(this.cacheKey)
+        }
+      } catch (redisErr) {
+        console.warn(`[HealthCheckCache] Redis clear failed:`, redisErr.message)
+      }
+    }
+  }
+
+  /**
+   * Checks if Redis is configured and available.
+   * @returns {boolean}
+   */
+  isRedisAvailable() {
+    return this._redisAvailable && this.redisClient !== null
+  }
+}
+
+module.exports = { HealthCheckCache }