@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/tracing/context.js

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// The trace context (80 NIO-203): one AsyncLocalStorage holding { span, bag, server } — the
+// current span, the current baggage (an ordered, frozen list of [key, value] pairs) and the
+// SERVER span of the request being served (used by framework integrations). Created lazily:
+// with tracing disabled no AsyncLocalStorage exists (NIO-211), and the propagation API still
+// works on explicit contexts (NIO-248).
+//
+// The storage is process-wide (shared through a global registry) so that several copies of the
+// library loaded in one process see the same context.
+
+const REGISTRY = Symbol.for('@pmx/io:context')
+
+function registry () {
+  let r = globalThis[REGISTRY]
+  if (!r) {
+    r = { als: null, bridge: null }
+    Object.defineProperty(globalThis, REGISTRY, { value: r, enumerable: false, configurable: true })
+  }
+  return r
+}
+
+/** The AsyncLocalStorage, created on first use. */
+function storage () {
+  const r = registry()
+  if (!r.als) {
+    const { AsyncLocalStorage } = require('async_hooks')
+    r.als = new AsyncLocalStorage()
+  }
+  return r.als
+}
+
+function active () {
+  return registry().als !== null
+}
+
+/** The current store, or undefined (85 bridge mode: the OpenTelemetry active span wins). */
+function current () {
+  const r = registry()
+  const als = r.als
+  const s = als ? als.getStore() : undefined
+  return r.bridge ? r.bridge.current(s) : s
+}
+
+/** 85 bridge mode (lib/otel/bridge.js): pmx contexts are mirrored into OpenTelemetry's. */
+function setBridge (b) {
+  registry().bridge = b || null
+}
+
+function currentSpan () {
+  const s = current()
+  return s ? s.span : undefined
+}
+
+/** Run fn(...args) with `store` current (store may be undefined: no context). */
+function run (store, fn, thisArg, args) {
+  const r = registry()
+  if (r.bridge) return r.bridge.run(storage(), store, fn, thisArg, args)
+  return storage().run(store, () => fn.apply(thisArg, args || []))
+}
+
+/** Bind fn to the context current now (NIO-244). */
+function bind (fn) {
+  if (typeof fn !== 'function') return fn
+  const als = registry().als
+  if (!als) {
+    // tracing never enabled: there is no context to carry
+    return function wrapped () {
+      return fn.apply(this, arguments)
+    }
+  }
+  const store = als.getStore()
+  const b = registry().bridge
+  const inner = b ? b.bind(fn) : fn
+  return function wrapped () {
+    return als.run(store, () => inner.apply(this, arguments))
+  }
+}
+
+/** Replace the store for the rest of the current synchronous execution (inbound HTTP, NIO-220). */
+function enter (store) {
+  storage().enterWith(store)
+  const b = registry().bridge
+  if (b) b.enter(store)
+}
+
+const EMPTY_STORE = Object.freeze({ span: undefined, bag: Object.freeze([]), server: undefined })
+
+module.exports = { EMPTY_STORE, storage, active, current, currentSpan, run, bind, enter, setBridge }

package/lib/tracing/control.js

@@ -0,0 +1,124 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'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.
+// Sources reported in `tracing_effective`: prodman | config | env | default.
+
+const { envIoConf } = require('./options')
+
+const MODES = ['on', 'off', 'force']
+
+function isObj (v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof RegExp)
+}
+
+/** A cleaned prodman layer (only valid keys; `{}` = nothing set). */
+function cleanLayer (v) {
+  const out = {}
+  if (!isObj(v)) return out
+  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
+  return out
+}
+
+/** INJ-026: env PMX_IO_TRACING (JSON); `{}` when unset or invalid. */
+function layerFromEnv (env) {
+  const raw = (env || process.env).PMX_IO_TRACING
+  if (typeof raw !== 'string' || raw.trim() === '') return {}
+  try {
+    return cleanLayer(JSON.parse(raw))
+  } catch (_) {
+    return {}
+  }
+}
+
+/**
+ * PROTO-161/165 (pmx 97 PAP-044): the layer for app `name` of application `application` from a
+ * `tracing` settings block (standalone mode), per key: `components[A][N]` > `applications[A]` >
+ * `defaults`; `apps[N]` stands in for `components[A][N]` only for `default` and only when the
+ * block has no `components`.
+ */
+function layerFromBlock (block, name, application) {
+  if (!isObj(block)) return {}
+  const a = typeof application === 'string' && application ? application : 'default'
+  const has = (o, k) => isObj(o) && typeof k === 'string' && Object.prototype.hasOwnProperty.call(o, k)
+  const defaults = cleanLayer(block.defaults)
+  const app = has(block.applications, a) ? cleanLayer(block.applications[a]) : {}
+  let own = {}
+  if (isObj(block.components)) {
+    const c = has(block.components, a) ? block.components[a] : null
+    own = has(c, name) ? cleanLayer(c[name]) : {}
+  } else if (a === 'default') {
+    own = has(block.apps, name) ? cleanLayer(block.apps[name]) : {}
+  }
+  return Object.assign({}, defaults, app, own)
+}
+
+/** Keep process.env.PMX_IO_TRACING equal to the layer (descendants start with it, INJ-026). */
+function exportLayer (layer) {
+  try {
+    if (Object.keys(layer).length) process.env.PMX_IO_TRACING = JSON.stringify(layer)
+    else delete process.env.PMX_IO_TRACING
+  } catch (_) {}
+}
+
+/** Apply the layer to a resolved `tracing` object (mutated and returned). */
+function applyLayer (tracing, layer) {
+  if (layer.enabled !== undefined) tracing.enabled = layer.enabled
+  if (layer.sample_ratio !== undefined) tracing.sampleRatio = layer.sample_ratio
+  if (layer.db_comment !== undefined && tracing.db !== false && !(isObj(tracing.db) && tracing.db.enabled === false)) {
+    tracing.db = Object.assign({}, isObj(tracing.db) ? tracing.db : {}, { comment: layer.db_comment })
+  }
+  return tracing
+}
+
+function dbOff (db) {
+  return db === false || (isObj(db) && db.enabled === false)
+}
+
+/** Which source last set each key below the layer (NIO-201 order). */
+function sources (appValue, hasKey, env) {
+  env = env || process.env
+  const src = { enabled: 'default', sample_ratio: 'default', db_comment: 'default' }
+  const mark = (t, label) => {
+    if (t === true || t === false) {
+      src.enabled = label
+      return
+    }
+    if (!isObj(t)) return
+    src.enabled = label // an object without `enabled` counts as enabled: true
+    if (t.sampleRatio !== undefined) src.sample_ratio = label
+    if (dbOff(t.db) || (isObj(t.db) && t.db.comment !== undefined)) src.db_comment = label
+  }
+  const conf = envIoConf(env)
+  if (conf && conf.tracing !== undefined) mark(conf.tracing, 'config')
+  if (env.trace === 'true' || env.trace === 'false') src.enabled = 'env'
+  const sampler = String(env.OTEL_TRACES_SAMPLER || '').trim().toLowerCase()
+  const ratioRaw = env.PMX_TRACE_SAMPLE_RATIO !== undefined && env.PMX_TRACE_SAMPLE_RATIO !== ''
+    ? env.PMX_TRACE_SAMPLE_RATIO
+    : (sampler === 'traceidratio' || sampler === 'parentbased_traceidratio' ? env.OTEL_TRACES_SAMPLER_ARG : undefined)
+  if (ratioRaw !== undefined && String(ratioRaw).trim() !== '' && Number.isFinite(Number(String(ratioRaw).trim()))) src.sample_ratio = 'env'
+  const dbc = typeof env.PMX_DB_COMMENT === 'string' ? env.PMX_DB_COMMENT.trim() : ''
+  if (dbc && !(conf && conf.tracing && isObj(conf.tracing) && dbOff(conf.tracing.db))) src.db_comment = 'env'
+  if (hasKey) mark(appValue, 'config')
+  return src
+}
+
+/** The `tracing_effective` report (PROTO-163) for the resolved `tracing` object. */
+function report (tracing, src, layer) {
+  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 {
+    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') }
+  }
+}
+
+module.exports = { cleanLayer, layerFromEnv, layerFromBlock, exportLayer, applyLayer, sources, report }

package/lib/tracing/exporter.js

@@ -0,0 +1,115 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Span export (80 NIO-208, Part G.4; 40 §7.11 / §7.11.2): one `trace-span` message per span, or
+// batched `trace-spans` messages when the receiver supports them (the daemon advertised it in
+// PMX_IO_CAPS; in standalone mode prodman advertised `trace_spans_batch`). A batch is sent when it
+// holds 100 spans, when adding a span would make its JSON exceed 512 KiB (that span starts the
+// next batch), 500 ms after its first span entered it (unref'd timer), at exit and at destroy().
+
+const debug = require('../debug')('axm:tracing')
+
+const MAX_SPANS = 100
+const MAX_BYTES = 512 * 1024
+const DELAY_MS = 500
+// {"type":"trace-spans","data":{"spans":[ … ]}}
+const ENVELOPE_BYTES = Buffer.byteLength('{"type":"trace-spans","data":{"spans":[]}}')
+
+class SpanSink {
+  /**
+   * @param {object} transport `send(type, data, cb)`, optional `batchSupported()`
+   * @param {{batch?: boolean, onDrop?: Function}} options
+   */
+  constructor (transport, options) {
+    options = options || {}
+    this._transport = transport
+    this._batch = options.batch === true
+    this._onDrop = options.onDrop || null
+    this._spans = []
+    this._bytes = ENVELOPE_BYTES
+    this._timer = null
+    this._closed = false
+    this._onExit = () => this.flush()
+    process.on('exit', this._onExit)
+  }
+
+  _batching () {
+    if (this._batch) return true
+    const t = this._transport
+    return Boolean(t && typeof t.batchSupported === 'function' && t.batchSupported())
+  }
+
+  _dropped (n) {
+    if (this._onDrop && n > 0) {
+      try {
+        this._onDrop(n)
+      } catch (_) {}
+    }
+  }
+
+  _send (type, data, n) {
+    try {
+      const ok = this._transport.send(type, data, (err) => {
+        if (err) this._dropped(n)
+      })
+      if (ok === false && typeof this._transport.lastSendDropped === 'function' && this._transport.lastSendDropped()) this._dropped(n)
+    } catch (err) {
+      debug('span send failed: %s', err && err.message)
+      this._dropped(n)
+    }
+  }
+
+  add (span) {
+    if (this._closed) return
+    if (!this._batching()) {
+      this._send('trace-span', span, 1)
+      return
+    }
+    let size
+    try {
+      size = Buffer.byteLength(JSON.stringify(span))
+    } catch (_) {
+      this._dropped(1)
+      return
+    }
+    const extra = size + (this._spans.length ? 1 : 0)
+    if (this._spans.length && this._bytes + extra > MAX_BYTES) this.flush()
+    this._spans.push(span)
+    this._bytes += size + (this._spans.length > 1 ? 1 : 0)
+    if (this._spans.length >= MAX_SPANS || this._bytes > MAX_BYTES) {
+      this.flush()
+      return
+    }
+    if (!this._timer) {
+      this._timer = setTimeout(() => {
+        this._timer = null
+        this.flush()
+      }, DELAY_MS)
+      if (this._timer.unref) this._timer.unref()
+    }
+  }
+
+  flush () {
+    if (this._timer) {
+      clearTimeout(this._timer)
+      this._timer = null
+    }
+    if (this._spans.length === 0) return
+    const spans = this._spans
+    this._spans = []
+    this._bytes = ENVELOPE_BYTES
+    this._send('trace-spans', { spans }, spans.length)
+  }
+
+  pending () {
+    return this._spans.length
+  }
+
+  destroy () {
+    this.flush()
+    this._closed = true
+    process.removeListener('exit', this._onExit)
+  }
+}
+
+module.exports = { SpanSink, MAX_SPANS, MAX_BYTES, DELAY_MS }

package/lib/tracing/index.js

@@ -0,0 +1,242 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// The tracing feature (80 B.8): wires the native tracer to the transport (span sink), to inbound
+// and outbound HTTP, to the framework integrations and to log correlation. Loaded only when
+// tracing is enabled (NIO-211).
+
+const { Tracer, Span } = require('./tracer')
+const { SpanSink } = require('./exporter')
+const w3c = require('./w3c')
+const inbound = require('../inbound')
+const outbound = require('../outbound')
+const debug = require('../debug')('axm:tracing')
+
+const { EMPTY_STORE } = require('./context')
+
+const DRAIN_GRACE_MS = 30000
+const DRAIN_POLL_MS = 50
+
+class TracingFeature {
+  /**
+   * @param {object} transport
+   * @param {{metrics?: object, batch?: boolean}} env
+   */
+  constructor (transport, env) {
+    env = env || {}
+    this._transport = transport
+    this._metrics = env.metrics || null
+    this._batch = env.batch === true
+    this._tracer = null
+    this._sink = null
+    this._enabled = false
+    this._dropped = 0
+    this._droppedRegistered = false
+    this.outbound = true
+  }
+
+  init (config, opts) {
+    this._sink = new SpanSink(this._transport, { batch: this._batch, onDrop: (n) => this._onDrop(n) })
+    const onStart = outbound.hasCreatedChannel() ? null : outbound.spanStarting
+    const apm = config && config.apmOptions
+    this._tracer = new Tracer(opts, this._sink, {
+      config,
+      onDrop: (n) => this._onDrop(n),
+      onStart,
+      // 85 bridge mode (lib/otel/bridge.js): reports and settings
+      bridge: {
+        report: (o) => this._transport.send('axm:option:configuration', o),
+        tracing: true,
+        bridge: config && config.otel && typeof config.otel === 'object' ? config.otel.bridge : undefined,
+        prodmanUrl: (apm && typeof apm.endpoint === 'string' && apm.endpoint) || process.env.PMX_IO_PRODMAN_URL || process.env.PRODMAN_URL || undefined,
+        debugOut: process.env.PMX_IO_DEBUG_OTEL === '1' ? (line) => process.stderr.write(line + '\n') : null
+      }
+    })
+    this.outbound = this._tracer.outbound
+    // the AsyncLocalStorage is created by the first span or request that needs it (context.js)
+    inbound.setConsumer('tracing', this)
+    outbound.setConsumer('tracing', this)
+    try {
+      require('../modules').enableTracing(this)
+    } catch (err) {
+      debug('library instrumentation failed: %s', err && err.message)
+    }
+    if (this._tracer.logCorrelation) {
+      try {
+        require('./logs').enable(this._tracer)
+      } catch (err) {
+        debug('log correlation failed: %s', err && err.message)
+      }
+    }
+    this._enabled = true
+    this._transport.send('axm:option:configuration', { otel_tracing: true })
+    // OTX-003 (a) / OTX-004: detection at activation; native mode is reported once
+    if (!this._tracer.checkBridge()) this._transport.send('axm:option:configuration', { otel: { mode: 'native' } })
+    const main = String(process.argv[1] || '')
+    if (/[\\/]\.output[\\/]server[\\/]index\.mjs$/.test(main)) {
+      // a Nitro/Nuxt production bundle inlines h3: no route is visible (NIO-221, Part G.2)
+      debug('Nitro bundle %s: h3 is inlined and not instrumentable; SERVER spans use normalised paths', main)
+    }
+    const t = setImmediate(() => {
+      const st = globalThis[Symbol.for('@pmx/io:preload-state')]
+      if (this._enabled && !(st && st.esmHooked) && !TracingFeature._esmNoted) {
+        TracingFeature._esmNoted = true
+        debug('ESM libraries are not instrumented: tracing was not enabled at start')
+      }
+    })
+    if (t.unref) t.unref()
+    return true
+  }
+
+  get tracer () {
+    return this._tracer
+  }
+
+  isEnabled () {
+    return this._enabled
+  }
+
+  getTracer () {
+    return this._tracer
+  }
+
+  _onDrop (n) {
+    this._dropped += n
+    if (!this._droppedRegistered && this._metrics) {
+      this._droppedRegistered = true
+      try {
+        // NIO-056: shown only while tracing is enabled and only after the first drop
+        this._metrics.register({ name: 'Trace Spans Dropped', id: 'internal/trace/dropped', handler: () => this._dropped })
+      } catch (_) {}
+    }
+  }
+
+  // -- inbound (inbound.js) -------------------------------------------------------------------
+
+  startServer (st) {
+    const req = st.req
+    const host = (req.headers && req.headers.host) || 'localhost'
+    const span = this._tracer.serverSpan({
+      method: req.method,
+      target: req.url || '/',
+      scheme: st.protocol,
+      host,
+      userAgent: req.headers && req.headers['user-agent'],
+      headers: req.headers,
+      lowercaseHeaders: true,
+      request: req
+    })
+    if (!span) {
+      st.store = EMPTY_STORE
+      return
+    }
+    st.span = span
+    inbound.attach(span, st)
+    st.store = { span, bag: span.bag, server: span }
+  }
+
+  endServer (st, status, aborted) { // eslint-disable-line no-unused-vars
+    this.finishServerSpan(st.span, status, st.route, st.error)
+  }
+
+  /** Shared with Bun.serve: tag status and route, mark errors, end. */
+  finishServerSpan (span, status, route, error) {
+    if (!span || span.ended) return
+    if (status !== undefined) span.setAttribute('http.status_code', String(status))
+    if (route) {
+      span.setAttribute('http.route', route)
+      span.updateName(span.attributes['http.method'] + ' ' + route)
+    }
+    if (error) span.recordException(error)
+    if (status >= 500 && span.status !== 'ERROR') span.setStatus('ERROR')
+    span.end()
+  }
+
+  // -- outbound (outbound.js) -----------------------------------------------------------------
+
+  clientSpan (method, url, host, port, request) {
+    return this._tracer.clientSpan(method, url, host, port, request)
+  }
+
+  headersFor (span) {
+    const b = this._tracer.bridge
+    if (b) {
+      const pairs = b.headersFor(span)
+      if (pairs) return pairs
+    }
+    return w3c.headersFor(span.context, span.bag)
+  }
+
+  /** OTX-020: fetch requests are covered by OpenTelemetry's undici instrumentation. */
+  fetchCovered () {
+    const b = this._tracer.bridge
+    return Boolean(b && b.undiciCovered())
+  }
+
+  endClient (span, status, err) {
+    if (!(span instanceof Span) || span.ended) return
+    if (status !== undefined && status !== null) span.setAttribute('http.status_code', String(status))
+    if (err) span.recordException(err)
+    else if (status >= 500) span.setStatus('ERROR')
+    span.end()
+  }
+
+  flush () {
+    if (this._sink) this._sink.flush()
+  }
+
+  /**
+   * NIO-298: switch tracing off without losing in-flight spans — new spans are no longer
+   * recorded, spans already started finish and are exported, then (all ended, or after
+   * `graceMs`) the feature is destroyed and `done` is called. `resume()` cancels it.
+   */
+  drain (done, graceMs) {
+    const tracer = this._tracer
+    if (!this._enabled || !tracer) {
+      this.destroy()
+      if (done) done()
+      return
+    }
+    tracer.stopping = true
+    const until = Date.now() + (graceMs === undefined ? DRAIN_GRACE_MS : graceMs)
+    const tick = () => {
+      this._drainTimer = null
+      if (!tracer.stopping) return
+      if (tracer._open > 0 && Date.now() < until) {
+        this._drainTimer = setTimeout(tick, DRAIN_POLL_MS)
+        if (this._drainTimer.unref) this._drainTimer.unref()
+        return
+      }
+      this.destroy()
+      if (done) done()
+    }
+    tick()
+  }
+
+  /** cancels a drain that has not finished (tracing switched on again) */
+  resume () {
+    if (this._drainTimer) clearTimeout(this._drainTimer)
+    this._drainTimer = null
+    if (this._tracer) this._tracer.stopping = false
+    return this._enabled
+  }
+
+  destroy () {
+    if (this._drainTimer) clearTimeout(this._drainTimer)
+    this._drainTimer = null
+    if (!this._enabled) return
+    this._enabled = false
+    inbound.setConsumer('tracing', null)
+    outbound.setConsumer('tracing', null)
+    try {
+      require('../modules').disableTracing()
+    } catch (_) {}
+    try {
+      require('./logs').disable()
+    } catch (_) {}
+    if (this._sink) this._sink.destroy()
+    this._transport.send('axm:option:configuration', { otel_tracing: false })
+  }
+}
+
+module.exports = { TracingFeature, EMPTY_STORE }