@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/tracing/logs.js

@@ -0,0 +1,176 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Log correlation (80 B.14, NIO-255..NIO-258): pino, winston and bunyan records written while a
+// span is current carry `trace_id` and `span_id` (values the app supplied are never
+// overwritten); console lines are prefixed only on request (`logCorrelation: { console: true }`).
+// The libraries are patched when the app loads them (modules.js); the patches look up the
+// current span at log time and do nothing while correlation is off.
+
+const ctx = require('./context')
+
+const state = { tracer: null, console: false, consoleRestore: null }
+
+function current () {
+  if (!state.tracer) return null
+  const span = ctx.currentSpan()
+  if (!span || typeof span.traceId !== 'string' || typeof span.spanId !== 'string') return null
+  return span
+}
+
+function copyStatics (to, from) {
+  for (const k of Object.getOwnPropertyNames(from)) {
+    if (k === 'length' || k === 'name' || k === 'prototype' || k === 'arguments' || k === 'caller') continue
+    try {
+      Object.defineProperty(to, k, Object.getOwnPropertyDescriptor(from, k))
+    } catch (_) {}
+  }
+  for (const s of Object.getOwnPropertySymbols(from)) {
+    try {
+      Object.defineProperty(to, s, Object.getOwnPropertyDescriptor(from, s))
+    } catch (_) {}
+  }
+  try {
+    Object.defineProperty(to, 'length', { value: from.length })
+    Object.defineProperty(to, 'name', { value: from.name })
+  } catch (_) {}
+}
+
+// ---------------------------------------------------------------------------------------------
+// pino (NIO-255): a mixin merged with the app's own
+
+function pinoOptions (opts) {
+  const o = Object.assign({}, opts)
+  const appMixin = typeof o.mixin === 'function' ? o.mixin : null
+  o.mixin = function pmxIoMixin (mergeObject, level, logger) {
+    const app = appMixin ? appMixin.apply(this, arguments) : undefined
+    const span = current()
+    if (!span) return app || {}
+    const out = { trace_id: span.traceId, span_id: span.spanId }
+    if (mergeObject && typeof mergeObject === 'object') {
+      if (mergeObject.trace_id !== undefined) delete out.trace_id
+      if (mergeObject.span_id !== undefined) delete out.span_id
+    }
+    return app && typeof app === 'object' ? Object.assign(out, app) : out
+  }
+  return o
+}
+
+function patchPino (pino) {
+  if (typeof pino !== 'function') return undefined
+  const orig = pino
+  const wrapped = function pino () {
+    const args = Array.prototype.slice.call(arguments)
+    const first = args[0]
+    if (first === undefined || first === null) args[0] = pinoOptions({})
+    else if (typeof first === 'string') args[0] = pinoOptions({ name: first })
+    else if (typeof first === 'object' && typeof first.write === 'function') args.unshift(pinoOptions({}))
+    else if (typeof first === 'object') args[0] = pinoOptions(first)
+    return orig.apply(this, args)
+  }
+  copyStatics(wrapped, orig)
+  wrapped.pino = wrapped
+  wrapped.default = wrapped
+  return wrapped
+}
+
+// ---------------------------------------------------------------------------------------------
+// winston (NIO-256): a format placed before the app's formats
+
+function patchWinston (winston) {
+  if (!winston || typeof winston.createLogger !== 'function' || !winston.format) return undefined
+  const orig = winston.createLogger
+  const correlate = winston.format((info) => {
+    const span = current()
+    if (span) {
+      if (info.trace_id === undefined) info.trace_id = span.traceId
+      if (info.span_id === undefined) info.span_id = span.spanId
+    }
+    return info
+  })
+  const createLogger = function createLogger (opts) {
+    const o = Object.assign({}, opts)
+    const appFormat = o.format || winston.format.json()
+    o.format = winston.format.combine(correlate(), appFormat)
+    return orig.call(this, o)
+  }
+  copyStatics(createLogger, orig)
+  const d = Object.getOwnPropertyDescriptor(winston, 'createLogger')
+  if (d && (d.writable || d.configurable)) {
+    Object.defineProperty(winston, 'createLogger', { value: createLogger, writable: true, enumerable: d.enumerable, configurable: true })
+  }
+  return undefined
+}
+
+// ---------------------------------------------------------------------------------------------
+// bunyan (NIO-257): records gain the fields before they are emitted
+
+function patchBunyan (bunyan) {
+  const Logger = bunyan && bunyan.prototype && typeof bunyan.prototype._emit === 'function' ? bunyan : bunyan && bunyan.Logger
+  const proto = Logger && Logger.prototype
+  if (!proto || typeof proto._emit !== 'function' || proto._emit.__pmxWrapped) return undefined
+  const orig = proto._emit
+  const _emit = function _emit (rec) {
+    const span = current()
+    if (span && rec && typeof rec === 'object') {
+      if (rec.trace_id === undefined) rec.trace_id = span.traceId
+      if (rec.span_id === undefined) rec.span_id = span.spanId
+    }
+    return orig.apply(this, arguments)
+  }
+  Object.defineProperty(_emit, '__pmxWrapped', { value: true })
+  proto._emit = _emit
+  return undefined
+}
+
+// ---------------------------------------------------------------------------------------------
+// console (NIO-258, opt-in)
+
+function enableConsole () {
+  if (state.consoleRestore) return
+  const saved = {}
+  for (const m of ['log', 'info', 'warn', 'error', 'debug']) {
+    const orig = console[m]
+    if (typeof orig !== 'function') continue
+    saved[m] = orig
+    console[m] = function () {
+      const span = state.console ? current() : null
+      if (!span) return orig.apply(this, arguments)
+      const prefix = `trace_id=${span.traceId} span_id=${span.spanId}`
+      const args = Array.prototype.slice.call(arguments)
+      if (typeof args[0] === 'string') args[0] = prefix + ' ' + args[0]
+      else args.unshift(prefix)
+      return orig.apply(this, args)
+    }
+  }
+  state.consoleRestore = () => {
+    for (const m of Object.keys(saved)) console[m] = saved[m]
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+
+function integrations () {
+  return [
+    { pkg: 'pino', for: 'tracing', files: { 'pino.js': patchPino } },
+    { pkg: 'winston', for: 'tracing', files: { 'lib/winston.js': patchWinston } },
+    { pkg: 'bunyan', for: 'tracing', files: { 'lib/bunyan.js': patchBunyan } }
+  ]
+}
+
+function enable (tracer) {
+  state.tracer = tracer
+  state.console = tracer.consoleCorrelation === true
+  if (state.console) enableConsole()
+}
+
+function disable () {
+  state.tracer = null
+  state.console = false
+  if (state.consoleRestore) {
+    state.consoleRestore()
+    state.consoleRestore = null
+  }
+}
+
+module.exports = { integrations, enable, disable, patchPino, patchWinston, patchBunyan }

package/lib/tracing/options.js

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Tracing options, their sources and their order (80 NIO-080, NIO-200, NIO-201; PYI-090a):
+// defaults → env `io` (conf.tracing) → env `trace` (only `enabled`) → env PMX_TRACE_SAMPLE_RATIO,
+// else OTEL_TRACES_SAMPLER_ARG for the trace-id-ratio samplers (only `sampleRatio`) → the app's
+// init(config); env PMX_DB_COMMENT (env stage) sets `db.comment` (96 SVM-500). Objects combine
+// key by key (`db`, `messaging`, `logCorrelation` too); an object that does not name `enabled`
+// counts as `enabled: true`.
+
+const debug = require('../debug')('axm:tracing')
+
+const NESTED = ['db', 'messaging', 'logCorrelation']
+
+function isObj (v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof RegExp)
+}
+
+/** Apply one source to `out` (mutated). */
+function applySource (out, src) {
+  if (src === true || src === false) {
+    out.enabled = src
+    return out
+  }
+  if (!isObj(src)) return out
+  if (!Object.prototype.hasOwnProperty.call(src, 'enabled')) out.enabled = true
+  for (const k of Object.keys(src)) {
+    const v = src[k]
+    if (v === undefined) continue
+    if (NESTED.includes(k) && isObj(v) && isObj(out[k])) {
+      out[k] = Object.assign({}, out[k], v)
+    } else if (NESTED.includes(k) && isObj(v)) {
+      out[k] = Object.assign({}, v)
+    } else {
+      out[k] = v
+    }
+  }
+  if (out.enabled !== true) out.enabled = out.enabled === true
+  return out
+}
+
+function envIoConf (env) {
+  if (typeof env.io !== 'string') return undefined
+  try {
+    const parsed = JSON.parse(env.io)
+    return parsed && isObj(parsed.conf) ? parsed.conf : undefined
+  } catch (err) {
+    debug('env io is not valid JSON: %s', err && err.message)
+    return undefined
+  }
+}
+
+function envRatio (env) {
+  let raw = env.PMX_TRACE_SAMPLE_RATIO
+  if (raw === undefined || raw === '') {
+    const sampler = String(env.OTEL_TRACES_SAMPLER || '').trim().toLowerCase()
+    if (sampler === 'traceidratio' || sampler === 'parentbased_traceidratio') raw = env.OTEL_TRACES_SAMPLER_ARG
+  }
+  if (raw === undefined || raw === '') return undefined
+  const n = Number(String(raw).trim())
+  if (String(raw).trim() === '' || !Number.isFinite(n)) {
+    debug('ignoring non-numeric sample ratio %s', raw)
+    return undefined
+  }
+  return n
+}
+
+/** The environment's contribution (everything before the app's init). */
+function fromEnv (env) {
+  env = env || process.env
+  const out = { enabled: false }
+  const conf = envIoConf(env)
+  if (conf && conf.tracing !== undefined) applySource(out, conf.tracing)
+  if (env.trace === 'true') out.enabled = true
+  else if (env.trace === 'false') out.enabled = false
+  const ratio = envRatio(env)
+  if (ratio !== undefined) out.sampleRatio = ratio
+  // 96 SVM-500: PMX_DB_COMMENT=on|off|force (key by key into `db`; `db: false` stays off)
+  const dbc = typeof env.PMX_DB_COMMENT === 'string' ? env.PMX_DB_COMMENT.trim() : ''
+  if (dbc && out.db !== false) out.db = Object.assign({}, isObj(out.db) ? out.db : {}, { comment: dbc })
+  return out
+}
+
+/**
+ * The effective `tracing` object for an init(config): `hasKey` = the app's config names
+ * `tracing` (NIO-080: without the key, the environment's settings are kept).
+ */
+function resolveTracing (appValue, hasKey, env) {
+  const out = fromEnv(env)
+  if (hasKey) applySource(out, appValue)
+  return out
+}
+
+/** `children` (NIO-290): config key, else env io conf, default true; PMX_IO_CHILDREN=0 → false. */
+function childrenEnabled (config, env) {
+  env = env || process.env
+  if (env.PMX_IO_CHILDREN === '0' || env.PMX_IO_CHILDREN === 'false') return false
+  if (config && config.children === false) return false
+  if (config && config.children === true) return true
+  const conf = envIoConf(env)
+  if (conf && conf.children === false) return false
+  return true
+}
+
+module.exports = { resolveTracing, fromEnv, applySource, childrenEnabled, envIoConf }

package/lib/tracing/paths.js

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Route-less SERVER span names (80 Part G.2): each path segment that looks like an identifier
+// becomes `:id`; the result is cut to 200 characters.
+
+const DIGITS = /^[0-9]+$/
+const UUID = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/
+const HEX16PLUS = /^[0-9A-Fa-f]{16,}$/
+const LONG_TOKEN = /^[A-Za-z0-9_-]{20,}$/
+const HAS_DIGIT = /[0-9]/
+
+function isId (seg) {
+  if (DIGITS.test(seg) || UUID.test(seg) || HEX16PLUS.test(seg)) return true
+  if (LONG_TOKEN.test(seg) && HAS_DIGIT.test(seg)) return true
+  return seg.indexOf('@') !== -1
+}
+
+/** The request path without query string, normalised (G.2). */
+function normalizePath (target) {
+  let path = String(target || '/')
+  const q = path.indexOf('?')
+  if (q !== -1) path = path.slice(0, q)
+  const out = path.split('/').map((seg) => (seg !== '' && isId(seg) ? ':id' : seg)).join('/')
+  return out.length > 200 ? out.slice(0, 200) : out
+}
+
+function rawPath (target) {
+  const t = String(target || '/')
+  const q = t.indexOf('?')
+  return q === -1 ? t : t.slice(0, q)
+}
+
+module.exports = { normalizePath, rawPath, isId }