@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/features/metrics.js

@@ -0,0 +1,409 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Default metrics (80 A.4, NIO-050..NIO-062): event loop, V8 heap, HTTP/HTTPS, network,
+// runtime (GC, rusage) and file descriptors. Names, ids, units and value types are exact.
+
+const fs = require('fs')
+const { Histogram, Meter } = require('../metrics/types')
+const { round2 } = require('../util')
+const hooks = require('../hooks')
+const debug = require('../debug')('axm:features:metrics')
+
+function every (ms, fn) {
+  const t = setInterval(fn, ms)
+  if (t.unref) t.unref()
+  return t
+}
+
+function after (ms, fn) {
+  const t = setTimeout(fn, ms)
+  if (t.unref) t.unref()
+  return t
+}
+
+function str2 (n) {
+  return typeof n === 'number' && Number.isFinite(n) ? n.toFixed(2) : undefined
+}
+
+// ---------------------------------------------------------------------------
+// Event loop: active handles/requests (A.4.1), latency (A.4.2, NIO-052)
+
+function activeCounters () {
+  if (typeof process._getActiveHandles === 'function' && typeof process._getActiveRequests === 'function') {
+    return {
+      handles: () => process._getActiveHandles().length,
+      requests: () => process._getActiveRequests().length
+    }
+  }
+  if (typeof process.getActiveResourcesInfo === 'function') {
+    const isReq = (t) => /Req|Request|Wrap$/.test(t) && t !== 'TTYWrap'
+    return {
+      handles: () => process.getActiveResourcesInfo().filter((t) => t !== 'Timeout' && t !== 'Immediate' && !isReq(t)).length,
+      requests: () => process.getActiveResourcesInfo().filter(isReq).length
+    }
+  }
+  return null
+}
+
+function initEventLoop (ctx, cfg) {
+  let active = true
+  let delay = true
+  if (cfg === false) return
+  if (cfg !== null && typeof cfg === 'object') {
+    active = cfg.eventLoopActive === true
+    delay = cfg.eventLoopDelay !== false
+  }
+
+  if (active) {
+    const counters = activeCounters()
+    if (counters) {
+      let handles
+      let requests
+      const sample = () => {
+        try {
+          handles = counters.handles()
+          requests = counters.requests()
+        } catch (_) {}
+      }
+      sample()
+      ctx.timers.push(every(1000, sample))
+      ctx.service.register({ name: 'Active handles', id: 'internal/libuv/handles', handler: () => handles })
+      ctx.service.register({ name: 'Active requests', id: 'internal/libuv/requests', handler: () => requests })
+    }
+  }
+
+  if (delay) {
+    const hist = new Histogram({ measurement: 'median' })
+    let last = process.hrtime()
+    ctx.timers.push(every(1000, () => {
+      const d = process.hrtime(last)
+      last = process.hrtime()
+      hist.update(d[0] * 1e3 + d[1] / 1e6 - 1000)
+    }))
+    const pct = (p) => () => (hist.getCount() === 0 ? undefined : str2(hist.percentiles([p])[p]))
+    ctx.service.register({ name: 'Event Loop Latency', id: 'internal/libuv/latency/p50', unit: 'ms', handler: pct(0.5) })
+    ctx.service.register({ name: 'Event Loop Latency p95', id: 'internal/libuv/latency/p95', unit: 'ms', handler: pct(0.95) })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// V8 heap (A.4.3)
+
+function initV8 (ctx, cfg) {
+  if (cfg === false) return
+  let v8
+  try {
+    v8 = require('v8')
+    if (typeof v8.getHeapStatistics !== 'function') return
+    v8.getHeapStatistics()
+  } catch (_) {
+    return
+  }
+  const on = (key) => !(cfg !== null && typeof cfg === 'object' && cfg[key] === false)
+  let stats = null
+  const sample = () => {
+    try {
+      stats = v8.getHeapStatistics()
+    } catch (_) {}
+  }
+  sample()
+  ctx.timers.push(every(800, sample))
+  const MiB = 1048576
+  if (on('total_heap_size')) {
+    ctx.service.register({ name: 'Heap Size', id: 'internal/v8/heap/total', unit: 'MiB', handler: () => stats && str2(stats.total_heap_size / MiB) })
+  }
+  if (on('used_heap_size')) {
+    ctx.service.register({ name: 'Used Heap Size', id: 'internal/v8/heap/used', unit: 'MiB', handler: () => stats && str2(stats.used_heap_size / MiB) })
+  }
+  if (on('heap_used_percent')) {
+    ctx.service.register({
+      name: 'Heap Usage',
+      id: 'internal/v8/heap/usage',
+      unit: '%',
+      handler: () => stats && stats.total_heap_size > 0 ? round2(stats.used_heap_size / stats.total_heap_size * 100) : undefined
+    })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP / HTTPS servers (A.4.4, NIO-053)
+
+function initHttp (ctx, cfg) {
+  if (cfg === false) return false
+  const per = {}
+  for (const protocol of ['http', 'https']) {
+    const label = protocol.toUpperCase()
+    const meter = new Meter()
+    const hist = new Histogram({ measurement: 'median' })
+    per[protocol] = { meter, hist }
+    ctx.stoppables.push(meter)
+    ctx.service.instrument(`internal/${protocol}/builtin/reqs`, 'meter', meter)
+    ctx.service.instrument(`internal/${protocol}/builtin/latency`, 'histogram', hist)
+    ctx.service.register({ name: label, id: `internal/${protocol}/builtin/reqs`, unit: 'req/min', implementation: meter, handler: () => (meter.isUsed() ? meter.val() : undefined) })
+    ctx.service.register({
+      name: `${label} Mean Latency`,
+      id: `internal/${protocol}/builtin/latency/p50`,
+      unit: 'ms',
+      handler: () => (hist.getCount() === 0 ? undefined : hist.percentiles([0.5])[0.5])
+    })
+    ctx.service.register({
+      name: `${label} P95 Latency`,
+      id: `internal/${protocol}/builtin/latency/p95`,
+      unit: 'ms',
+      handler: () => (hist.getCount() === 0 ? undefined : hist.percentiles([0.95])[0.95])
+    })
+  }
+  const inbound = require('../inbound')
+  inbound.setConsumer('metrics', {
+    request (protocol, req, res) {
+      const m = per[protocol]
+      if (!m) return
+      m.meter.mark()
+      if (!res || typeof res.once !== 'function') return
+      const start = Date.now()
+      res.once('finish', () => m.hist.update(Date.now() - start))
+    },
+    // Bun.serve (NIO-101): returns the function to call when the response is returned
+    start (protocol) {
+      const m = per[protocol]
+      if (!m) return null
+      m.meter.mark()
+      const start = Date.now()
+      return () => m.hist.update(Date.now() - start)
+    }
+  })
+  if (process.versions.bun) require('../bun').install()
+  ctx.cleanups.push(() => inbound.setConsumer('metrics', null))
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Outbound HTTP (NIO-055)
+
+function initHttpOutbound (ctx, cfg) {
+  if (cfg === false) return
+  const meter = new Meter()
+  const hist = new Histogram({ measurement: 'median' })
+  ctx.stoppables.push(meter)
+  ctx.service.register({ name: 'HTTP Outbound', id: 'internal/http/outbound/reqs', unit: 'req/s', implementation: meter, handler: () => (meter.isUsed() ? meter.val() : undefined) })
+  ctx.service.register({
+    name: 'HTTP Outbound Mean Latency',
+    id: 'internal/http/outbound/latency/p50',
+    unit: 'ms',
+    handler: () => (hist.getCount() === 0 ? undefined : round2(hist.percentiles([0.5])[0.5]))
+  })
+  ctx.service.register({
+    name: 'HTTP Outbound P95 Latency',
+    id: 'internal/http/outbound/latency/p95',
+    unit: 'ms',
+    handler: () => (hist.getCount() === 0 ? undefined : round2(hist.percentiles([0.95])[0.95]))
+  })
+  ctx.service.instrument('internal/http/outbound/reqs', 'meter', meter)
+  ctx.service.instrument('internal/http/outbound/latency', 'histogram', hist)
+  const outbound = require('../outbound')
+  outbound.setConsumer('metrics', (ms) => {
+    meter.mark()
+    hist.update(ms)
+  })
+  ctx.cleanups.push(() => outbound.setConsumer('metrics', null))
+}
+
+// ---------------------------------------------------------------------------
+// Network (A.4.5, opt-in)
+
+function initNetwork (ctx, cfg) {
+  let upload = false
+  let download = false
+  if (cfg === true) {
+    upload = download = true
+  } else if (cfg !== null && typeof cfg === 'object') {
+    upload = cfg.upload === true
+    download = cfg.download === true
+  }
+  if (!upload && !download) return
+  const kb = (meter) => () => (meter.isUsed() ? Math.floor(meter.rawVal() / 1024 * 1000) / 1000 : undefined)
+  let inMeter, outMeter
+  if (download) {
+    inMeter = new Meter()
+    ctx.stoppables.push(inMeter)
+    ctx.service.register({ name: 'Network In', id: 'internal/network/in', unit: 'kb/s', implementation: inMeter, handler: kb(inMeter) })
+  }
+  if (upload) {
+    outMeter = new Meter()
+    ctx.stoppables.push(outMeter)
+    ctx.service.register({ name: 'Network Out', id: 'internal/network/out', unit: 'kb/s', implementation: outMeter, handler: kb(outMeter) })
+  }
+  ctx.timers.push(after(500, () => {
+    if (ctx.destroyed) return
+    hooks.installNet()
+    if (inMeter) hooks.setHandler('socketRead', (n) => inMeter.mark(n))
+    if (outMeter) hooks.setHandler('socketWrite', (n) => outMeter.mark(n))
+  }))
+  ctx.cleanups.push(() => {
+    hooks.setHandler('socketRead', null)
+    hooks.setHandler('socketWrite', null)
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Runtime: GC pauses and rusage deltas without a native addon (NIO-060..062)
+
+function initRuntime (ctx, cfg) {
+  if (cfg === false) return
+  const on = (key) => cfg === true || cfg === undefined || cfg === null || typeof cfg !== 'object' || cfg[key] === true
+  const register = (name, id, unit, handler) => ctx.service.register({ name, id, unit, handler })
+  const pctHandler = (hist, p) => () => (hist.getCount() === 0 ? undefined : hist.percentiles([p])[p])
+
+  if (on('gcNewPause') || on('gcOldPause')) {
+    try {
+      const { PerformanceObserver, constants } = require('perf_hooks')
+      const MINOR = (constants && constants.NODE_PERFORMANCE_GC_MINOR) || 1
+      const MAJOR = (constants && constants.NODE_PERFORMANCE_GC_MAJOR) || 4
+      const newHist = new Histogram({ measurement: 'median' })
+      const oldHist = new Histogram({ measurement: 'median' })
+      const obs = new PerformanceObserver((list) => {
+        for (const e of list.getEntries()) {
+          const kind = e.detail && e.detail.kind !== undefined ? e.detail.kind : e.kind
+          if (kind === MINOR) newHist.update(e.duration)
+          else if (kind === MAJOR) oldHist.update(e.duration)
+        }
+      })
+      obs.observe({ entryTypes: ['gc'] })
+      ctx.cleanups.push(() => obs.disconnect())
+      if (on('gcNewPause')) {
+        register('GC New Space Pause', 'internal/v8/gc/new/pause/p50', 'ms', pctHandler(newHist, 0.5))
+        register('GC New Space Pause p95', 'internal/v8/gc/new/pause/p95', 'ms', pctHandler(newHist, 0.95))
+      }
+      if (on('gcOldPause')) {
+        register('GC Old Space Pause', 'internal/v8/gc/old/pause/p50', 'ms', pctHandler(oldHist, 0.5))
+        register('GC Old Space Pause p95', 'internal/v8/gc/old/pause/p95', 'ms', pctHandler(oldHist, 0.95))
+      }
+    } catch (err) {
+      debug('gc observation unavailable: %s', err && err.message)
+    }
+  }
+
+  const wantCs = on('contextSwitchs')
+  const wantPf = on('pageFaults')
+  if ((wantCs || wantPf) && typeof process.resourceUsage === 'function') {
+    // the first resource-usage sample (~3 ms) waits until the app's main module has started
+    // (NIO-024); the first metric push is 990 ms away anyway
+    const t = setImmediate(() => {
+      if (!ctx.destroyed) initRusage(ctx, wantCs, wantPf, register)
+    })
+    if (t.unref) t.unref()
+    ctx.cleanups.push(() => clearImmediate(t))
+  }
+}
+
+function initRusage (ctx, wantCs, wantPf, register) {
+  const hists = {
+    vol: new Histogram({ measurement: 'mean' }),
+    invol: new Histogram({ measurement: 'mean' }),
+    minor: new Histogram({ measurement: 'mean' }),
+    major: new Histogram({ measurement: 'mean' })
+  }
+  let prev
+  try {
+    prev = process.resourceUsage()
+  } catch (_) {
+    return
+  }
+  ctx.timers.push(every(1000, () => {
+    let cur
+    try {
+      cur = process.resourceUsage()
+    } catch (_) {
+      return
+    }
+    hists.vol.update(cur.voluntaryContextSwitches - prev.voluntaryContextSwitches)
+    hists.invol.update(cur.involuntaryContextSwitches - prev.involuntaryContextSwitches)
+    hists.minor.update(cur.minorPageFault - prev.minorPageFault)
+    hists.major.update(cur.majorPageFault - prev.majorPageFault)
+    prev = cur
+  }))
+  const mean = (h) => () => (h.getCount() === 0 ? undefined : round2(h.getMean()))
+  if (wantCs) {
+    register('Volontary CPU Context Switch', 'internal/uv/cpu/contextswitch/volontary', undefined, mean(hists.vol))
+    register('Involuntary CPU Context Switch', 'internal/uv/cpu/contextswitch/involontary', undefined, mean(hists.invol))
+  }
+  if (wantPf) {
+    register('Minor Page Fault', 'internal/uv/memory/pagefault/minor', undefined, mean(hists.minor))
+    register('Major Page Fault', 'internal/uv/memory/pagefault/major', undefined, mean(hists.major))
+  }
+}
+
+// ---------------------------------------------------------------------------
+// File descriptors (NIO-054)
+
+function initFds (ctx, cfg) {
+  if (cfg === false) return
+  let dir = null
+  for (const d of ['/proc/self/fd', '/dev/fd']) {
+    try {
+      fs.readdirSync(d)
+      dir = d
+      break
+    } catch (_) {}
+  }
+  if (!dir) return
+  let count
+  const sample = () => {
+    try {
+      // The listing itself opens one descriptor, which is subtracted.
+      count = fs.readdirSync(dir).length - 1
+    } catch (_) {}
+  }
+  sample()
+  ctx.timers.push(every(5000, sample))
+  ctx.service.register({ name: 'File Descriptors', id: 'internal/process/fds', handler: () => count })
+}
+
+/**
+ * Initialise the default metrics. Returns a handle with destroy() and whether
+ * HTTP measurement is on (for the `latency` option message).
+ */
+function initDefaultMetrics (service, metricsCfg, opts) {
+  const relay = Boolean(opts && opts.relay)
+  const cfg = metricsCfg !== null && typeof metricsCfg === 'object' ? metricsCfg : {}
+  const ctx = { service, timers: [], stoppables: [], cleanups: [], destroyed: false }
+  const guard = (name, fn) => {
+    try {
+      return fn()
+    } catch (err) {
+      debug('metric group %s failed: %s', name, err && err.message)
+    }
+  }
+  // relays contribute request metrics only; process-level metrics stay the root's (NIO-291/292)
+  if (!relay) {
+    const processGroups = () => {
+      if (ctx.destroyed) return
+      guard('eventLoop', () => initEventLoop(ctx, cfg.eventLoop))
+      guard('v8', () => initV8(ctx, cfg.v8))
+      guard('runtime', () => initRuntime(ctx, cfg.runtime))
+      guard('fds', () => initFds(ctx, cfg.fds))
+      guard('network', () => initNetwork(ctx, cfg.network))
+    }
+    // `later` (the instance's deferred steps): not needed before the app's first line (NIO-024)
+    if (opts && typeof opts.later === 'function') opts.later(processGroups)
+    else processGroups()
+  }
+  const http = guard('http', () => initHttp(ctx, cfg.http)) === true
+  guard('httpOutbound', () => initHttpOutbound(ctx, cfg.httpOutbound))
+  return {
+    http,
+    destroy () {
+      ctx.destroyed = true
+      for (const t of ctx.timers) clearTimeout(t)
+      for (const m of ctx.stoppables) m._stop()
+      for (const fn of ctx.cleanups) {
+        try {
+          fn()
+        } catch (_) {}
+      }
+    }
+  }
+}
+
+module.exports = { initDefaultMetrics }