@aidra/pmx-io 9.18.0 → 9.20.0

package/lib/pmx.js

@@ -14,6 +14,7 @@ const { NotifyFeature } = require('./features/notify')
 const { initDefaultMetrics } = require('./features/metrics')
 const { resolveTracing } = require('./tracing/options')
 const control = require('./tracing/control')
+const callmap = require('./callmap')
 // loaded on first use: the propagation API is not needed before the app's first line (NIO-024)
 let w3cModule = null
 const w3c = new Proxy({}, { get: (_, k) => (w3cModule || (w3cModule = require('./tracing/w3c')))[k] })
@@ -43,7 +44,7 @@ const PUBLIC_METHODS = [
 
 const REPORTED = Symbol.for('@pmx/io:reported')
 // G.5: the app → daemon envelopes a relay may forward (anything else from a relay is ignored)
-const RELAYED_TYPES = ['process:exception', 'human:event', 'trace-span', 'trace-spans']
+const RELAYED_TYPES = ['process:exception', 'human:event', 'trace-span', 'trace-spans', 'service:calls']
 
 function profilingEnabled (p) {
   if (p === false) return false
@@ -117,6 +118,9 @@ class PMX {
     // 80 NIO-298: the prodman layer (undefined until the first init reads PMX_IO_TRACING)
     this._tracingLayer = undefined
     this._appTracing = { value: undefined, has: false }
+    // 83 CMP-001: the app's init({ serviceMap }) and the resolved { value, source }
+    this._appServiceMap = undefined
+    this._serviceMap = { value: false, source: 'default' }
     this._defaultMetrics = null
     for (const m of PUBLIC_METHODS) this[m] = this[m].bind(this)
     this.Entrypoint = makeEntrypoint(this)
@@ -238,6 +242,7 @@ class PMX {
     if (this._initialized) this._teardown(true)
     const hasTracing = config !== null && typeof config === 'object' && Object.prototype.hasOwnProperty.call(config, 'tracing')
     const appTracing = hasTracing ? config.tracing : undefined
+    this._appServiceMap = config !== null && typeof config === 'object' ? config.serviceMap : undefined
     config = normalizeConfig(config)
     // NIO-080/NIO-201: environment sources, then the app's `tracing` key (kept when absent)
     config.tracing = resolveTracing(appTracing, hasTracing)
@@ -314,6 +319,8 @@ class PMX {
       if (process.versions.bun) require('./bun').install()
     }
     if (config.tracing && config.tracing.enabled === true) this._startTracing(config)
+    // 83: the call map, with tracing on or off
+    this._applyServiceMap()
 
     // 6. full configuration
     this._initialized = true
@@ -370,11 +377,46 @@ class PMX {
     }
   }
 
+  /** 83 CMP-001/CMP-003: switch the call map on or off as the layer, the config and the env say. */
+  _applyServiceMap () {
+    const r = callmap.resolve(this._tracingLayer, this._appServiceMap)
+    this._serviceMap = r
+    const inbound = require('./inbound')
+    const outbound = require('./outbound')
+    const modules = require('./modules')
+    const t = this._transport
+    if (r.value === true) {
+      callmap.setEnabled(true, (data) => {
+        if (this._transport) this._transport.send('service:calls', data)
+      })
+      inbound.setConsumer('callmap', callmap)
+      outbound.setConsumer('callmap', callmap)
+      modules.enableCallMap()
+      if (process.versions.bun) require('./bun').install()
+      // standalone: the partial minute goes before agent:shutdown (NIO-268)
+      if (t && typeof t.beforeShutdown === 'function') {
+        if (!this._callMapFlush) this._callMapFlush = () => callmap.flush(true)
+        t.beforeShutdown(this._callMapFlush)
+      }
+    } else {
+      inbound.setConsumer('callmap', null)
+      outbound.setConsumer('callmap', null)
+      modules.disableCallMap()
+      callmap.setEnabled(false)
+    }
+  }
+
+  /** True while the call map is on (preload.mjs registers the module hooks then, CMP-003). */
+  _serviceMapEnabled () {
+    return Boolean(this._initialized && callmap.state.on)
+  }
+
   /** 80 NIO-298: replace the prodman layer and apply it at once (no restart). */
   _setTracingLayer (layer) {
     this._tracingLayer = control.cleanLayer(layer)
     control.exportLayer(this._tracingLayer)
     if (!this._initialized || this._isRelay()) return
+    this._applyServiceMap()
     const t = control.applyLayer(resolveTracing(this._appTracing.value, this._appTracing.has), this._tracingLayer)
     this._config.tracing = t
     const want = t.enabled === true
@@ -415,7 +457,7 @@ class PMX {
   _reportTracing () {
     if (!this._transport || !this._config || this._isRelay()) return
     const src = control.sources(this._appTracing.value, this._appTracing.has)
-    this._transport.send('axm:option:configuration', { tracing_effective: control.report(this._config.tracing, src, this._tracingLayer || {}) })
+    this._transport.send('axm:option:configuration', { tracing_effective: control.report(this._config.tracing, src, this._tracingLayer || {}, this._serviceMap) })
   }
 
   _reportDependencies (generation) {
@@ -465,6 +507,17 @@ class PMX {
     safe(() => this._notify && this._notify.destroy())
     safe(() => this._actions && this._actions.destroy())
     safe(() => require('./inbound').setConsumer('errors', null))
+    if (!keepTransport) {
+      // destroy(): the call map's records are sent now and recording stops (a re-init keeps them;
+      // init applies the switch again at once)
+      safe(() => {
+        require('./inbound').setConsumer('callmap', null)
+        require('./outbound').setConsumer('callmap', null)
+        require('./modules').disableCallMap()
+        callmap.stop()
+      })
+    }
+    safe(() => this._callMapFlush && this._transport && typeof this._transport.offBeforeShutdown === 'function' && this._transport.offBeforeShutdown(this._callMapFlush))
     // the standalone root keeps its prodman connection across re-inits (destroyed by destroy())
     if (this._mode !== 'standalone') safe(() => this._transport && this._transport.destroy())
     this._tracing = this._defaultMetrics = this._metrics = this._profiling = null

package/lib/relay/transport.js

@@ -14,7 +14,7 @@ const net = require('net')
 const { RELAY_KEY, socketPath, helloLine } = require('./hub')
 const debug = require('../debug')('axm:relay')
 
-const FORWARDED = ['process:exception', 'human:event', 'trace-span']
+const FORWARDED = ['process:exception', 'human:event', 'trace-span', 'service:calls']
 const MAX_QUEUE = 1000
 
 function wrapMessage (type, data, extraMeta) {

package/lib/standalone/transport.js

@@ -630,6 +630,7 @@ class ProdmanTransport {
       }
       case 'trace-span':
       case 'trace-spans':
+      case 'service:calls': // 83 CMP-021
       case 'axm:reply':
       case 'profilings':
       case 'application:dependencies':
@@ -654,6 +655,16 @@ class ProdmanTransport {
     this._listeners.push(fn)
   }
 
+  /** `fn()` runs when shutdown starts, before agent:shutdown is queued (once per registration). */
+  beforeShutdown (fn) {
+    if (!this._beforeShutdown) this._beforeShutdown = []
+    if (!this._beforeShutdown.includes(fn)) this._beforeShutdown.push(fn)
+  }
+
+  offBeforeShutdown (fn) {
+    if (this._beforeShutdown) this._beforeShutdown = this._beforeShutdown.filter((f) => f !== fn)
+  }
+
   offMessage (fn) {
     this._listeners = this._listeners.filter((f) => f !== fn)
   }
@@ -951,6 +962,12 @@ class ProdmanTransport {
     try {
       this._flushLogs(true)
     } catch (_) {}
+    // the instance's last data (83 CMP-020: the call map's partial minute) before agent:shutdown
+    for (const fn of (this._beforeShutdown || []).slice()) {
+      try {
+        fn()
+      } catch (_) {}
+    }
     this.packet('agent:shutdown', this._shutdownPayload, null, false)
     return this.flush(flushMs === undefined ? 1000 : flushMs).then(() => {
       this.close(1000, 'Shutting down')

package/lib/tracing/control.js

@@ -2,8 +2,8 @@
 'use strict'
 
 // Tracing control from prodman (80 NIO-298, INJ-026; 40 §8.6; prodman 02 §6.19 PROTO-160…163).
-// The *prodman layer* holds up to three wire keys — `enabled`, `sample_ratio`, `db_comment` — and
-// beats every other source (the app's init(config) included); below it the NIO-201 order is kept.
+// The *prodman layer* holds up to four wire keys — `enabled`, `sample_ratio`, `db_comment` and
+// `service_map` (the call map, 83 CMP-001) — and beats every other source (the app's init(config) included); below it the NIO-201 order is kept.
 // Sources reported in `tracing_effective`: prodman | config | env | default.
 
 const { envIoConf } = require('./options')
@@ -21,6 +21,7 @@ function cleanLayer (v) {
   if (typeof v.enabled === 'boolean') out.enabled = v.enabled
   if (typeof v.sample_ratio === 'number' && Number.isFinite(v.sample_ratio)) out.sample_ratio = Math.min(1, Math.max(0, v.sample_ratio))
   if (typeof v.db_comment === 'string' && MODES.includes(v.db_comment)) out.db_comment = v.db_comment
+  if (typeof v.service_map === 'boolean') out.service_map = v.service_map
   return out
 }
 
@@ -107,18 +108,23 @@ function sources (appValue, hasKey, env) {
   return src
 }
 
-/** The `tracing_effective` report (PROTO-163) for the resolved `tracing` object. */
-function report (tracing, src, layer) {
+/**
+ * The `tracing_effective` report (PROTO-163) for the resolved `tracing` object; `serviceMap`
+ * ({ value, source }, 83 CMP-001) is added as `service_map` when given.
+ */
+function report (tracing, src, layer, serviceMap) {
   const { normMode } = require('../itg/dbcomment')
   const ratio = Number(tracing.sampleRatio)
   const off = dbOff(tracing.db)
   const s = (k) => (layer[k] !== undefined && !(k === 'db_comment' && off) ? 'prodman' : src[k])
-  return {
+  const out = {
     v: 1,
     enabled: { value: tracing.enabled === true, source: s('enabled') },
     sample_ratio: { value: tracing.sampleRatio !== undefined && Number.isFinite(ratio) ? Math.min(1, Math.max(0, ratio)) : 1, source: s('sample_ratio') },
     db_comment: { value: off ? 'off' : normMode(isObj(tracing.db) ? tracing.db.comment : undefined), source: s('db_comment') }
   }
+  if (serviceMap) out.service_map = { value: serviceMap.value === true, source: serviceMap.source }
+  return out
 }
 
 module.exports = { cleanLayer, layerFromEnv, layerFromBlock, exportLayer, applyLayer, sources, report }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidra/pmx-io",
-  "version": "9.18.0",
+  "version": "9.20.0",
   "description": "In-process instrumentation for Node.js and Bun apps run by pmx, or reporting to prodman on their own (@pm2/io compatible)",
   "license": "UNLICENSED",
   "repository": {

package/preload.mjs

@@ -3,7 +3,8 @@
 // ES module preload, injected with `--import` only when ESM instrumentation (tracing) is
 // enabled (02 D-05, 80 INJ-010). It shares state with preload.cjs (which Node runs first),
 // activates on its own when used alone, and registers the module customization hooks that wrap
-// ES-module libraries when tracing is on (NIO-085, NIO-210). It never registers a hook otherwise.
+// ES-module libraries when tracing or the call map is on (NIO-085, NIO-210, 83 CMP-003). It never
+// registers a hook otherwise.
 
 import { createRequire } from 'node:module'