@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/metrics/service.js

@@ -0,0 +1,286 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Metric registry and the 990 ms `axm:monitor` push (80 A.3.6).
+
+const { Gauge, Counter, Meter, Histogram } = require('./types')
+const { METRIC_PUSH_INTERVAL } = require('../constants')
+
+const RELAY_INTERVAL = 1000
+const { round2 } = require('../util')
+const debug = require('../debug')('axm:services:metrics')
+
+function normalizeOpts (opts) {
+  if (typeof opts === 'string') return { name: opts }
+  if (opts === null || typeof opts !== 'object') return { name: opts }
+  return opts
+}
+
+function isReportable (v) {
+  if (typeof v === 'string' || typeof v === 'boolean') return true
+  return typeof v === 'number' && Number.isFinite(v)
+}
+
+class MetricService {
+  constructor (transport) {
+    this._transport = transport
+    this._metrics = new Map()
+    this._instruments = new Map() // relay key → { key, kind, impl, opts } (80 Part G.5)
+    this._relay = null
+    this._timer = null
+  }
+
+  start () {
+    if (this._timer) return
+    this._timer = setInterval(() => (this._relay ? this.flushContributions() : this.push()), this._relay ? RELAY_INTERVAL : METRIC_PUSH_INTERVAL)
+    if (this._timer.unref) this._timer.unref()
+  }
+
+  /**
+   * Relay mode (80 NIO-263, NIO-291, NIO-293): instead of `axm:monitor`, contributions of the
+   * relay-capable instruments are sent every 1000 ms with `send(list)`.
+   */
+  setRelay (send) {
+    this._relay = send
+    for (const i of this._instruments.values()) if (i.impl) i.impl._track = true
+    if (this._timer) {
+      clearInterval(this._timer)
+      this._timer = null
+      this.start()
+    }
+  }
+
+  /** Declare a relay-capable instrument (built-in key, or a custom metric's name). */
+  instrument (key, kind, impl, opts) {
+    if (typeof key !== 'string') return
+    if (this._relay && impl) impl._track = true
+    this._instruments.set(key, { key, kind, impl, opts: opts || {} })
+  }
+
+  contributions () {
+    const out = []
+    for (const i of this._instruments.values()) {
+      let c
+      try {
+        c = i.kind === 'gauge' && typeof i.impl === 'function' ? i.impl() : i.impl._drain()
+      } catch (_) {
+        c = undefined
+      }
+      if (c === undefined || c === null || (typeof c === 'number' && !Number.isFinite(c))) continue
+      out.push({ k: i.key, t: i.kind, o: i.opts, c })
+    }
+    return out
+  }
+
+  flushContributions () {
+    if (!this._relay) return
+    const c = this.contributions()
+    if (c.length) {
+      try {
+        this._relay(c)
+      } catch (_) {}
+    }
+  }
+
+  /** Root side: apply one relay contribution `{k, t, o, c}`. */
+  applyContribution (item) {
+    if (!item || typeof item.k !== 'string') return
+    let i = this._instruments.get(item.k)
+    if (!i) {
+      if (item.k.startsWith('internal/')) return
+      const o = Object.assign({}, item.o && typeof item.o === 'object' ? item.o : {}, { name: item.k })
+      switch (item.t) {
+        case 'counter': this.counter(o); break
+        case 'meter': this.meter(o); break
+        case 'histogram': this.histogram(o); break
+        case 'gauge': this.gauge(o); break
+        default: return
+      }
+      i = this._instruments.get(item.k)
+      if (!i) return
+    }
+    if (!i.impl || typeof i.impl._apply !== 'function') return
+    try {
+      i.impl._apply(item.c)
+    } catch (_) {}
+  }
+
+  /**
+   * Register (or replace) a metric.
+   * @param {{name: string, id?: string, unit?: string, historic?: boolean, handler: Function, implementation?: any}} def
+   */
+  register (def) {
+    if (typeof def.name !== 'string') {
+      console.error('Invalid metric name declared: ' + def.name)
+      return false
+    }
+    if (def.id !== undefined && typeof def.id !== 'string') {
+      console.error('Invalid metric type declared: ' + def.id)
+      return false
+    }
+    if (typeof def.handler !== 'function') {
+      console.error('Invalid metric handler declared for ' + def.name)
+      return false
+    }
+    const old = this._metrics.get(def.name)
+    if (old && old.implementation && typeof old.implementation._stop === 'function' && old.implementation !== def.implementation) {
+      old.implementation._stop()
+    }
+    this._metrics.set(def.name, {
+      name: def.name,
+      id: def.id,
+      unit: def.unit,
+      historic: def.historic === undefined ? true : Boolean(def.historic),
+      handler: def.handler,
+      implementation: def.implementation
+    })
+    return true
+  }
+
+  unregister (name) {
+    const m = this._metrics.get(name)
+    if (!m) return
+    if (m.implementation && typeof m.implementation._stop === 'function') m.implementation._stop()
+    this._metrics.delete(name)
+  }
+
+  has (name) {
+    return this._metrics.has(name)
+  }
+
+  /** Evaluate every metric into the `axm:monitor` payload shape. */
+  collect () {
+    const data = {}
+    for (const m of this._metrics.values()) {
+      let value
+      try {
+        value = m.handler()
+      } catch (err) {
+        debug('metric %s handler threw: %s', m.name, err && err.message)
+        continue
+      }
+      if (!isReportable(value)) continue
+      const entry = { value }
+      if (m.unit !== undefined && m.unit !== null) entry.unit = m.unit
+      if (m.id !== undefined && m.id !== null) entry.type = m.id
+      entry.historic = m.historic
+      data[m.name] = entry
+    }
+    return data
+  }
+
+  push () {
+    this._transport.send('axm:monitor', this.collect())
+  }
+
+  // ---- creators (80 A.3.1 – A.3.5) ----
+
+  _common (opts) {
+    return { name: opts.name, id: opts.id, unit: opts.unit, historic: opts.historic }
+  }
+
+  _relayOpts (opts) {
+    const o = {}
+    for (const k of ['name', 'unit', 'id', 'historic', 'measurement', 'samples', 'timeframe']) if (opts[k] !== undefined) o[k] = opts[k]
+    return o
+  }
+
+  gauge (opts) {
+    opts = normalizeOpts(opts)
+    if (typeof opts.value === 'function') {
+      const fn = opts.value
+      if (this.register(Object.assign(this._common(opts), { handler: fn }))) this.instrument(opts.name, 'gauge', fn, this._relayOpts(opts))
+      return undefined
+    }
+    const g = new Gauge()
+    const ok = this.register(Object.assign(this._common(opts), {
+      implementation: g,
+      handler: () => (g.isUsed() ? g.val() : undefined)
+    }))
+    if (ok) this.instrument(opts.name, 'gauge', g, this._relayOpts(opts))
+    return ok ? g : undefined
+  }
+
+  counter (opts) {
+    opts = normalizeOpts(opts)
+    const c = new Counter(opts)
+    const ok = this.register(Object.assign(this._common(opts), {
+      implementation: c,
+      handler: () => (c.isUsed() ? c.val() : undefined)
+    }))
+    if (ok) this.instrument(opts.name, 'counter', c, this._relayOpts(opts))
+    return ok ? c : undefined
+  }
+
+  meter (opts) {
+    opts = normalizeOpts(opts)
+    if (typeof opts.name !== 'string') {
+      console.error('Invalid metric name declared: ' + opts.name)
+      return undefined
+    }
+    const m = new Meter(opts)
+    this.register(Object.assign(this._common(opts), {
+      implementation: m,
+      handler: () => (m.isUsed() ? m.val() : undefined)
+    }))
+    this.instrument(opts.name, 'meter', m, this._relayOpts(opts))
+    return m
+  }
+
+  histogram (opts) {
+    opts = normalizeOpts(opts)
+    const h = new Histogram(opts)
+    const ok = this.register(Object.assign(this._common(opts), {
+      implementation: h,
+      handler: () => {
+        if (!h.isUsed()) return undefined
+        const v = h.val()
+        return typeof v === 'number' ? round2(v) : v
+      }
+    }))
+    if (ok) this.instrument(opts.name, 'histogram', h, this._relayOpts(opts))
+    return ok ? h : undefined
+  }
+
+  metrics (list) {
+    if (list === null || list === undefined) {
+      console.error('Received empty metric to create')
+      console.trace()
+      return []
+    }
+    const arr = Array.isArray(list) ? list : [list]
+    return arr.map((def) => {
+      if (!def || typeof def.name !== 'string') {
+        console.error('Trying to create a metrics without a name')
+        console.trace()
+        return {}
+      }
+      switch (def.type) {
+        case 'counter': return this.counter(def)
+        case 'histogram': return this.histogram(def)
+        case 'meter': return this.meter(def)
+        case 'gauge':
+        case 'metric':
+        case undefined:
+        case null:
+          return this.gauge(def)
+        default:
+          console.error('Invalid metric type ' + def.type + ' for metric ' + def.name)
+          console.trace()
+          return {}
+      }
+    })
+  }
+
+  destroy () {
+    if (this._timer) clearInterval(this._timer)
+    this._timer = null
+    for (const m of this._metrics.values()) {
+      if (m.implementation && typeof m.implementation._stop === 'function') m.implementation._stop()
+    }
+    this._metrics.clear()
+    this._instruments.clear()
+  }
+}
+
+module.exports = { MetricService, normalizeOpts }

package/lib/metrics/types.js

@@ -0,0 +1,342 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Metric implementations (80 A.3): Gauge, Counter, Meter (EWMA), Histogram with an
+// exponentially decaying reservoir (forward-decay priority sampling).
+
+const { round2 } = require('../util')
+
+const RESERVOIR_SIZE = 1028
+const RESERVOIR_ALPHA = 0.015 // per second
+const RESCALE_INTERVAL_MS = 60 * 60 * 1000
+
+class Gauge {
+  constructor (value) {
+    this._value = value === undefined ? 0 : value
+    this._used = false
+  }
+
+  set (value) {
+    this._value = value
+    this._used = true
+  }
+
+  val () {
+    return this._value
+  }
+
+  isUsed () {
+    return this._used
+  }
+
+  /** Relay contribution (80 Part G.5): the last value. */
+  _drain () {
+    return this._used ? this._value : undefined
+  }
+
+  _apply (c) {
+    this.set(c)
+  }
+}
+
+class Counter {
+  constructor (opts) {
+    opts = opts || {}
+    this._count = typeof opts.count === 'number' ? opts.count : 0
+    this._used = false
+  }
+
+  inc (n) {
+    this._count += n || 1
+    this._used = true
+  }
+
+  dec (n) {
+    this._count -= n || 1
+    this._used = true
+  }
+
+  reset (count) {
+    this._count = count || 0
+  }
+
+  /** Relay contribution: the net change since the previous drain. */
+  _drain () {
+    const base = this._relayBase || 0
+    this._relayBase = this._count
+    const d = this._count - base
+    return d !== 0 ? d : undefined
+  }
+
+  _apply (c) {
+    if (typeof c === 'number' && Number.isFinite(c)) {
+      this._count += c
+      this._used = true
+    }
+  }
+
+  val () {
+    return this._count
+  }
+
+  isUsed () {
+    return this._used
+  }
+}
+
+/**
+ * Exponentially weighted moving average rate (80 A.3.3).
+ * rate is in events per millisecond; val() = events per `samples` seconds.
+ */
+class Meter {
+  constructor (opts) {
+    opts = opts || {}
+    this._samples = Number(opts.samples || opts.seconds || 1)
+    this._timeframe = Number(opts.timeframe || 60)
+    this._tickInterval = Number(opts.tickInterval || 5000)
+    this._alpha = 1 - Math.exp(-this._tickInterval / (this._timeframe * 1000))
+    this._pending = 0
+    this._rate = 0
+    this._used = false
+    this._timer = setInterval(() => this._tick(), this._tickInterval)
+    if (this._timer.unref) this._timer.unref()
+  }
+
+  _tick () {
+    const instant = this._pending / this._tickInterval
+    this._pending = 0
+    this._rate += this._alpha * (instant - this._rate)
+  }
+
+  mark (n) {
+    this._pending += n || 1
+    this._used = true
+    if (this._track) this._relayMarks = (this._relayMarks || 0) + (n || 1)
+  }
+
+  /** Relay contribution: the number of marks since the previous drain. */
+  _drain () {
+    const m = this._relayMarks || 0
+    this._relayMarks = 0
+    return m > 0 ? m : undefined
+  }
+
+  _apply (c) {
+    if (typeof c === 'number' && c > 0) this.mark(c)
+  }
+
+  /** Unrounded rate in events per `samples` seconds. */
+  rawVal () {
+    return this._rate * this._samples * 1000
+  }
+
+  val () {
+    return round2(this.rawVal())
+  }
+
+  isUsed () {
+    return this._used
+  }
+
+  _stop () {
+    clearInterval(this._timer)
+  }
+}
+
+class ExponentiallyDecayingReservoir {
+  constructor (size, alpha) {
+    this._size = size || RESERVOIR_SIZE
+    this._alpha = alpha || RESERVOIR_ALPHA
+    this.clear()
+  }
+
+  clear () {
+    this._samples = [] // { priority, value }
+    this._landmark = Date.now()
+    this._nextRescale = this._landmark + RESCALE_INTERVAL_MS
+  }
+
+  _rescale (now) {
+    const factor = Math.exp(-this._alpha * (now - this._landmark) / 1000)
+    for (const s of this._samples) s.priority *= factor
+    this._landmark = now
+    this._nextRescale = now + RESCALE_INTERVAL_MS
+  }
+
+  update (value, now) {
+    now = now === undefined ? Date.now() : now
+    if (now >= this._nextRescale) this._rescale(now)
+    const weight = Math.exp(this._alpha * (now - this._landmark) / 1000)
+    const u = 1 - Math.random() // (0, 1]
+    const priority = weight / u
+    if (this._samples.length < this._size) {
+      this._samples.push({ priority, value })
+      return
+    }
+    let minIdx = 0
+    for (let i = 1; i < this._samples.length; i++) {
+      if (this._samples[i].priority < this._samples[minIdx].priority) minIdx = i
+    }
+    if (priority > this._samples[minIdx].priority) {
+      this._samples[minIdx] = { priority, value }
+    }
+  }
+
+  size () {
+    return this._samples.length
+  }
+
+  sortedValues () {
+    return this._samples.map((s) => s.value).sort((a, b) => a - b)
+  }
+}
+
+/** Percentile rule of 80 A.3.4 over ascending values. */
+function percentile (sorted, p) {
+  const n = sorted.length
+  if (n === 0) return null
+  const pos = p * (n + 1)
+  if (pos < 1) return sorted[0]
+  if (pos >= n) return sorted[n - 1]
+  const lower = sorted[Math.floor(pos) - 1]
+  const upper = sorted[Math.ceil(pos) - 1]
+  return lower + (pos - Math.floor(pos)) * (upper - lower)
+}
+
+const MEASUREMENTS = ['min', 'max', 'sum', 'count', 'variance', 'mean', 'stddev', 'median', 'p75', 'p95', 'p99', 'p999', 'ema']
+
+class Histogram {
+  constructor (opts) {
+    opts = opts || {}
+    this._measurement = MEASUREMENTS.includes(opts.measurement) ? opts.measurement : 'mean'
+    this._reservoir = new ExponentiallyDecayingReservoir()
+    this._min = null
+    this._max = null
+    this._sum = 0
+    this._count = 0
+    this._mean = 0 // Welford running mean
+    this._m2 = 0
+    this._ema = 0
+    this._used = false
+  }
+
+  update (value) {
+    value = Number(value)
+    if (Number.isNaN(value)) return
+    this._used = true
+    this._count++
+    this._sum += value
+    if (this._min === null || value < this._min) this._min = value
+    if (this._max === null || value > this._max) this._max = value
+    const delta = value - this._mean
+    this._mean += delta / this._count
+    this._m2 += delta * (value - this._mean)
+    const alpha = 2 / (1 + this._count)
+    this._ema = this._count === 1 ? value : this._ema + alpha * (value - this._ema)
+    this._reservoir.update(value)
+    if (this._track) {
+      if (!this._relayValues) this._relayValues = []
+      if (this._relayValues.length < 2000) this._relayValues.push(value)
+    }
+  }
+
+  /** Relay contribution: the values recorded since the previous drain (at most 2 000). */
+  _drain () {
+    const v = this._relayValues
+    this._relayValues = null
+    return v && v.length ? v : undefined
+  }
+
+  _apply (c) {
+    if (!Array.isArray(c)) return
+    for (const v of c.slice(0, 2000)) this.update(v)
+  }
+
+  getMin () { return this._min }
+  getMax () { return this._max }
+  getSum () { return this._sum }
+  getCount () { return this._count }
+  getEma () { return this._ema }
+  getMean () { return this._count === 0 ? 0 : this._sum / this._count }
+  getVariance () { return this._count <= 1 ? null : this._m2 / (this._count - 1) }
+
+  percentiles (fractions) {
+    const sorted = this._reservoir.sortedValues()
+    const out = {}
+    for (const p of fractions || []) out[p] = percentile(sorted, p)
+    return out
+  }
+
+  fullResults () {
+    const pc = this.percentiles([0.5, 0.75, 0.95, 0.99, 0.999])
+    return {
+      min: this._min,
+      max: this._max,
+      sum: this._sum,
+      variance: this.getVariance(),
+      mean: this.getMean(),
+      count: this._count,
+      median: pc[0.5],
+      p75: pc[0.75],
+      p95: pc[0.95],
+      p99: pc[0.99],
+      p999: pc[0.999],
+      ema: this._ema
+    }
+  }
+
+  _compute (measurement) {
+    switch (measurement) {
+      case 'min': return this._min
+      case 'max': return this._max
+      case 'sum': return this._sum
+      case 'count': return this._count
+      case 'variance': return this.getVariance()
+      case 'mean': return this.getMean()
+      case 'stddev': {
+        const v = this.getVariance()
+        return v === null ? null : Math.sqrt(v)
+      }
+      case 'ema': return this._ema
+      case 'median': return this.percentiles([0.5])[0.5]
+      case 'p75': return this.percentiles([0.75])[0.75]
+      case 'p95': return this.percentiles([0.95])[0.95]
+      case 'p99': return this.percentiles([0.99])[0.99]
+      case 'p999': return this.percentiles([0.999])[0.999]
+      default: return this.getMean()
+    }
+  }
+
+  val () {
+    return this._compute(this._measurement)
+  }
+
+  isUsed () {
+    return this._used
+  }
+}
+
+const MetricType = Object.freeze({
+  meter: 'meter',
+  histogram: 'histogram',
+  counter: 'counter',
+  gauge: 'gauge',
+  metric: 'metric'
+})
+
+const MetricMeasurements = Object.freeze(MEASUREMENTS.reduce((acc, m) => {
+  acc[m] = m
+  return acc
+}, {}))
+
+module.exports = {
+  Gauge,
+  Counter,
+  Meter,
+  Histogram,
+  ExponentiallyDecayingReservoir,
+  percentile,
+  MetricType,
+  MetricMeasurements,
+  MEASUREMENTS
+}