@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/otel/env.js

@@ -0,0 +1,114 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// `OTEL_*` wiring for Mode S (85 OTX-052, the rules of OTX-201…205 without the receiver and the
+// pm_id key): `pmx-io-node run` with PMX_IO_OTEL_EXPORT=1 points an app's own OpenTelemetry SDK at
+// prodman's OTLP endpoint (`<PRODMAN_URL>/otlp`, protocol http/protobuf, header
+// `Authorization=Basic%20<base64(public:secret)>`), names the service after PM2_APP_NAME and adds
+// resource attributes — each only where the environment does not set it (OTX-208: nothing the
+// app sets is replaced; merges append). Opt-in because it places the bucket secret in the
+// environment of every child process (PYI-152 / B.15 otherwise avoid it). Loaded by the launcher
+// only when the opt-in is set.
+
+const ENDPOINTS = ['OTEL_EXPORTER_OTLP_ENDPOINT', 'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT', 'OTEL_EXPORTER_OTLP_LOGS_ENDPOINT', 'OTEL_EXPORTER_OTLP_METRICS_ENDPOINT']
+const PROTOCOLS = ['OTEL_EXPORTER_OTLP_PROTOCOL', 'OTEL_EXPORTER_OTLP_TRACES_PROTOCOL', 'OTEL_EXPORTER_OTLP_LOGS_PROTOCOL', 'OTEL_EXPORTER_OTLP_METRICS_PROTOCOL']
+const SIGNAL_HEADERS = ['OTEL_EXPORTER_OTLP_TRACES_HEADERS', 'OTEL_EXPORTER_OTLP_LOGS_HEADERS', 'OTEL_EXPORTER_OTLP_METRICS_HEADERS']
+
+const set = (env, k) => typeof env[k] === 'string' && env[k] !== ''
+
+/** Percent-encoding of the OTel environment specification (UTF-8, RFC 3986 unreserved kept). */
+function pct (v) {
+  return Array.from(Buffer.from(String(v), 'utf8')).map((b) => {
+    const c = String.fromCharCode(b)
+    return /[A-Za-z0-9\-._~]/.test(c) ? c : '%' + b.toString(16).toUpperCase().padStart(2, '0')
+  }).join('')
+}
+
+function names (list) {
+  const out = new Set()
+  for (const part of String(list || '').split(',')) {
+    const i = part.indexOf('=')
+    if (i > 0) out.add(decodeURIComponent(part.slice(0, i).trim()).toLowerCase())
+  }
+  return out
+}
+
+function appendPairs (current, pairs) {
+  const have = names(current)
+  const add = pairs.filter(([k, v]) => v !== undefined && v !== null && v !== '' && !have.has(k.toLowerCase())).map(([k, v]) => k + '=' + pct(v))
+  if (add.length === 0) return current || ''
+  return current ? current + ',' + add.join(',') : add.join(',')
+}
+
+/**
+ * Mutate `env` (the app's environment) per OTX-052. `info`: { url (normalised prodman URL),
+ * machine (the standalone server name, CTR-015), app (default PM2_APP_NAME), container:
+ * [[key, value]] }. Standalone has no pm_id: `service.instance.id` is the server name (as pmx-io).
+ * Returns the list of variables set or changed.
+ */
+function wire (env, info) {
+  const changed = []
+  const put = (k, v) => {
+    if (env[k] !== v) {
+      env[k] = v
+      changed.push(k)
+    }
+  }
+  if (!ENDPOINTS.some((k) => set(env, k))) {
+    put('OTEL_EXPORTER_OTLP_ENDPOINT', info.url.replace(/\/+$/, '') + '/otlp')
+    if (!PROTOCOLS.some((k) => set(env, k))) put('OTEL_EXPORTER_OTLP_PROTOCOL', 'http/protobuf')
+    const auth = 'Basic%20' + Buffer.from(`${env.PM2_PUBLIC_KEY || ''}:${env.PM2_SECRET_KEY || ''}`).toString('base64')
+    const withAuth = (v) => (names(v).has('authorization') ? v : (v ? v + ',' : '') + 'Authorization=' + auth)
+    put('OTEL_EXPORTER_OTLP_HEADERS', withAuth(env.OTEL_EXPORTER_OTLP_HEADERS || ''))
+    for (const k of SIGNAL_HEADERS) if (set(env, k)) put(k, withAuth(env[k]))
+  }
+  const app = info.app || env.PM2_APP_NAME
+  const machine = info.machine
+  // pmx 97 PAP-051/052: `pmx.application` always, `service.namespace` when not `default`
+  const application = info.application || 'default'
+  const ns = require('../application').serviceNamespace(application, null)
+  const resource = appendPairs(env.OTEL_RESOURCE_ATTRIBUTES || '', [
+    ['service.instance.id', machine],
+    ['pmx.app', app],
+    ['pmx.server', machine],
+    ['pmx.application', application]
+  ].concat(ns ? [['service.namespace', ns]] : []).concat(info.container || []))
+  if (resource !== (env.OTEL_RESOURCE_ATTRIBUTES || '')) put('OTEL_RESOURCE_ATTRIBUTES', resource)
+  if (!set(env, 'OTEL_SERVICE_NAME') && app && !names(env.OTEL_RESOURCE_ATTRIBUTES).has('service.name')) put('OTEL_SERVICE_NAME', app)
+  return changed
+}
+
+/**
+ * The container resource attributes of OTX-203 known without network calls (95 §2: the identity
+ * of CTR-014; the ECS task metadata endpoint is not queried at launch, so the aws.ecs.* keys and
+ * the zone are left out). `info` is a ContainerInfo (lib/standalone/container.js).
+ */
+function containerPairs (info, app, host) {
+  const out = []
+  try {
+    if (!info || !info.inContainer()) return out
+    const id = info.identity(app || null, host)
+    out.push(['container.id', id.id], ['container.name', id.name], ['container.image.name', id.image],
+      ['k8s.pod.name', info.podName()], ['k8s.namespace.name', id.namespace],
+      ['pmx.container.service', id.service], ['pmx.container.instance', id.instance])
+  } catch (_) {}
+  return out.filter(([, v]) => v !== undefined && v !== null && v !== '')
+}
+
+/**
+ * The launcher's OTX-052 step: resolve the standalone configuration as the app will (NIO-262,
+ * CTR-015 server name) and wire `env`; nothing when a key, the secret or the app name is missing
+ * (the standalone root then prints its missing-values line). Returns the variables changed.
+ */
+function wireLauncher (env) {
+  const container = require('../standalone/container')
+  const { resolveConfig } = require('../standalone/transport')
+  const info = container.ContainerInfo.detect(env, container.SysRoot.host(), process.platform === 'linux')
+  const cfg = resolveConfig(undefined, env, info)
+  if (cfg.missing.length || !cfg.serverName) return []
+  // PAP-052: the standalone resolution (no init value at launch: PMX_APPLICATION > default)
+  const application = require('../application').resolve(undefined, { managed: false, env })
+  return wire(env, { url: cfg.url, machine: cfg.serverName, app: cfg.appName, application, container: containerPairs(info, cfg.appName, container.hostname()) })
+}
+
+module.exports = { wire, wireLauncher, containerPairs, pct }

package/lib/outbound.js

@@ -0,0 +1,362 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Outbound HTTP (80 NIO-055, NIO-222), shared by the `HTTP Outbound*` metrics and the CLIENT
+// spans. Every request goes through exactly one layer:
+//  * http/https (ClientRequest): diagnostics channels. Header injection needs
+//    `http.client.request.created` (Node ≥ 22.12 / ≥ 23.2, Bun), published while the headers can
+//    still be set; on older Node, when CLIENT spans are wanted, http.request/get and
+//    https.request/get are wrapped instead, each when it is loaded (see below).
+//  * the global fetch: Node's undici diagnostics channels (`undici:request:*`, headers added with
+//    the request's addHeader); Bun: globalThis.fetch is wrapped.
+// Requests made by @aidra/pmx-io itself never use these APIs (raw sockets, transport/ws.js).
+
+const hooks = require('./hooks')
+const debug = require('./debug')('axm:tracing')
+
+const OUT = Symbol.for('@pmx/io:outbound-state')
+const consumers = { metrics: null, tracing: null }
+// resolved on first use: reading globalThis.performance loads the perf_hooks internals (NIO-024)
+let perf = null
+function pnow () {
+  if (perf === null) perf = globalThis.performance || require('perf_hooks').performance
+  return perf.now()
+}
+const BUN = typeof process.versions.bun === 'string'
+
+function nodeVersion () {
+  const [a, b] = String(process.versions.node || '0.0').split('.').map(Number)
+  return { major: a || 0, minor: b || 0 }
+}
+
+/** `http.client.request.created` is published (Node ≥ 22.12 on 22, ≥ 23.2; Bun). */
+function hasCreatedChannel () {
+  if (BUN) return true
+  const v = nodeVersion()
+  return (v.major === 22 && v.minor >= 12) || (v.major === 23 && v.minor >= 2) || v.major >= 24
+}
+
+function hasErrorChannel () {
+  return BUN || nodeVersion().major >= 20
+}
+
+// ---------------------------------------------------------------------------------------------
+// shared start/end
+
+function startState (canInject, info, inject) {
+  const st = { t0: pnow(), span: null, ended: false }
+  const t = consumers.tracing
+  if (t && canInject) {
+    try {
+      const i = info()
+      if (i) {
+        st.span = t.clientSpan(i.method, i.url, i.host, i.port, i.request)
+        if (st.span) inject(t.headersFor(st.span))
+      }
+    } catch (err) {
+      debug('outbound span failed: %s', err && err.message)
+    }
+  }
+  return st
+}
+
+function endState (st, status, err) {
+  if (!st || st.ended) return
+  st.ended = true
+  const m = consumers.metrics
+  if (m) {
+    try {
+      m(pnow() - st.t0)
+    } catch (_) {}
+  }
+  if (st.span && consumers.tracing) {
+    try {
+      consumers.tracing.endClient(st.span, status, err)
+    } catch (_) {}
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// http/https ClientRequest
+
+function clientInfo (req) {
+  const protocol = req.protocol || 'http:'
+  let hostHeader
+  try {
+    hostHeader = req.getHeader('host')
+  } catch (_) {}
+  let host = req.host || 'localhost'
+  let port
+  if (typeof hostHeader === 'string' && hostHeader) {
+    const m = /^(\[[^\]]+\]|[^:]+)(?::(\d+))?$/.exec(hostHeader)
+    if (m) {
+      host = m[1].replace(/^\[|\]$/g, '')
+      if (m[2]) port = Number(m[2])
+    }
+  }
+  if (!port) port = protocol === 'https:' ? 443 : 80
+  const authority = typeof hostHeader === 'string' && hostHeader ? hostHeader : host
+  return { method: req.method || 'GET', url: `${protocol}//${authority}${req.path || '/'}`, host, port, request: req }
+}
+
+function setOn (req, st) {
+  try {
+    Object.defineProperty(req, OUT, { value: st, enumerable: false, configurable: true, writable: true })
+  } catch (_) {}
+}
+
+function onClientCreated (req, canInject) {
+  if (!req || req[OUT]) return
+  const st = startState(canInject, () => clientInfo(req), (headers) => {
+    for (const [name, value] of headers) {
+      try {
+        if (req.getHeader(name) === undefined) req.setHeader(name, value)
+      } catch (_) { /* headers already sent (array form) */ }
+    }
+  })
+  setOn(req, st)
+  if (!hasErrorChannel() && typeof req.once === 'function') {
+    // Node 18: no error channel; 'close' always comes (never add an 'error' listener)
+    req.once('close', () => {
+      if (!st.ended) setImmediate(() => endState(st, undefined, new Error('request closed')))
+    })
+  }
+}
+
+let dcInstalled = false
+function installDc () {
+  if (dcInstalled) return
+  dcInstalled = true
+  let dc
+  try {
+    dc = require('diagnostics_channel')
+  } catch (_) {
+    return
+  }
+  const created = hasCreatedChannel()
+  if (created) dc.subscribe('http.client.request.created', ({ request }) => onClientCreated(request, true))
+  dc.subscribe('http.client.request.start', ({ request }) => onClientCreated(request, false))
+  dc.subscribe('http.client.response.finish', ({ request, response }) => {
+    endState(request && request[OUT], response && response.statusCode)
+  })
+  if (hasErrorChannel()) {
+    dc.subscribe('http.client.request.error', ({ request, error }) => endState(request && request[OUT], undefined, error))
+  }
+  if (!BUN) installUndici(dc)
+}
+
+// ---------------------------------------------------------------------------------------------
+// Node < 22.12: wrap http/https request/get for CLIENT spans (header injection)
+//
+// Loading http and https at activation costs start-up (https loads tls and crypto, NIO-024), so
+// each module is wrapped when it is loaded: on its first CommonJS require (before the caller
+// receives it, so `const { request } = require('http')` gets the wrapper), and otherwise —
+// an ES-module `import` of node:http, which require does not see — when a span starts
+// (`spanStarting`, called by the tracer); module.syncBuiltinESMExports() then updates the live
+// named imports. CLIENT spans exist only inside a span, so no request that could get one is
+// made before its module is wrapped, except through a named import bound before the first span
+// (updated by syncBuiltinESMExports) — covered.
+
+const clientWrap = { wanted: false, done: new Set(), seen: 0, requireHooked: false }
+
+function wrapClientModule (name) {
+  if (clientWrap.done.has(name)) return
+  clientWrap.done.add(name)
+  const r = hooks.registry()
+  const key = 'httpClient:' + name
+  if (r.installed[key]) return
+  r.installed[key] = true
+  const mod = require(name)
+  const origRequest = mod.request
+  const request = function request () {
+    const req = origRequest.apply(this, arguments)
+    try {
+      onClientCreated(req, true)
+    } catch (_) {}
+    return req
+  }
+  const get = function get () {
+    const req = request.apply(this, arguments)
+    req.end()
+    return req
+  }
+  copyMeta(request, origRequest)
+  copyMeta(get, mod.get)
+  mod.request = request
+  mod.get = get
+  try {
+    require('module').syncBuiltinESMExports()
+  } catch (_) {}
+}
+
+function loadedBuiltin (name) {
+  const list = process.moduleLoadList
+  return !Array.isArray(list) || list.includes('NativeModule ' + name)
+}
+
+/** Wrap whichever of http/https are loaded by now (cheap when nothing changed). */
+function wrapLoadedClients () {
+  if (!clientWrap.wanted || clientWrap.done.size === 2) return
+  const list = process.moduleLoadList
+  if (Array.isArray(list) && list.length === clientWrap.seen) return
+  clientWrap.seen = Array.isArray(list) ? list.length : 0
+  for (const name of ['http', 'https']) if (loadedBuiltin(name)) wrapClientModule(name)
+}
+
+function wantClientWrap () {
+  if (clientWrap.wanted || hasCreatedChannel()) return
+  clientWrap.wanted = true
+  wrapLoadedClients()
+  if (clientWrap.done.size === 2 || clientWrap.requireHooked) return
+  clientWrap.requireHooked = true
+  try {
+    const proto = require('./util').cjsModule().prototype
+    const orig = proto.require
+    const req = function require (id) {
+      const exports = orig.apply(this, arguments)
+      if (clientWrap.done.size < 2 && typeof id === 'string' && (id === 'http' || id === 'https' || id === 'node:http' || id === 'node:https')) {
+        try {
+          wrapClientModule(id.replace('node:', ''))
+        } catch (_) {}
+      }
+      return exports
+    }
+    copyMeta(req, orig)
+    proto.require = req
+  } catch (err) {
+    debug('require observer failed: %s', err && err.message)
+  }
+}
+
+/** Called by the tracer when a span starts (NIO-222 on Node < 22.12). */
+function spanStarting () {
+  if (clientWrap.wanted && clientWrap.done.size < 2) wrapLoadedClients()
+}
+
+function copyMeta (fn, orig) {
+  try {
+    Object.defineProperty(fn, 'length', { value: orig.length })
+    Object.defineProperty(fn, 'name', { value: orig.name })
+  } catch (_) {}
+}
+
+// ---------------------------------------------------------------------------------------------
+// fetch: Node (undici diagnostics channels)
+
+const undiciStates = new WeakMap()
+
+function installUndici (dc) {
+  dc.subscribe('undici:request:create', ({ request }) => {
+    if (!request || undiciStates.has(request)) return
+    const tr = consumers.tracing
+    const covered = Boolean(tr && typeof tr.fetchCovered === 'function' && tr.fetchCovered())
+    const st = startState(!covered, () => {
+      const origin = String(request.origin || '')
+      let host = 'localhost'
+      let port
+      let protocol = 'http:'
+      try {
+        const u = new URL(origin)
+        host = u.hostname.replace(/^\[|\]$/g, '')
+        protocol = u.protocol
+        port = u.port ? Number(u.port) : (u.protocol === 'https:' ? 443 : 80)
+      } catch (_) {}
+      return { method: request.method || 'GET', url: origin + (request.path || '/'), host, port, request, protocol }
+    }, (headers) => {
+      for (const [name, value] of headers) {
+        if (!undiciHas(request, name)) request.addHeader(name, value)
+      }
+    })
+    undiciStates.set(request, st)
+  })
+  dc.subscribe('undici:request:headers', ({ request, response }) => {
+    const st = undiciStates.get(request)
+    if (st) st.status = response && response.statusCode
+  })
+  dc.subscribe('undici:request:trailers', ({ request }) => {
+    const st = undiciStates.get(request)
+    if (st) endState(st, st.status)
+  })
+  dc.subscribe('undici:request:error', ({ request, error }) => {
+    const st = undiciStates.get(request)
+    if (st) endState(st, st.status, error)
+  })
+}
+
+function undiciHas (request, name) {
+  const h = request.headers
+  if (Array.isArray(h)) {
+    for (let i = 0; i < h.length; i += 2) {
+      if (String(h[i]).toLowerCase() === name) return true
+    }
+    return false
+  }
+  if (typeof h === 'string') return new RegExp('(^|\\r\\n)' + name + ':', 'i').test(h)
+  return false
+}
+
+// ---------------------------------------------------------------------------------------------
+// fetch: Bun (globalThis.fetch wrapper)
+
+let bunFetchWrapped = false
+function wrapBunFetch () {
+  if (bunFetchWrapped || !BUN || typeof globalThis.fetch !== 'function') return
+  bunFetchWrapped = true
+  const orig = globalThis.fetch
+  const fetch = function fetch (input, init) {
+    let st
+    let args = arguments
+    try {
+      st = startState(true, () => {
+        const isReq = typeof Request === 'function' && input instanceof Request
+        const url = new URL(isReq ? input.url : String(input))
+        const method = String((init && init.method) || (isReq ? input.method : 'GET')).toUpperCase()
+        return { method, url: url.href, host: url.hostname, port: url.port ? Number(url.port) : (url.protocol === 'https:' ? 443 : 80), request: input }
+      }, (headers) => {
+        const isReq = typeof Request === 'function' && input instanceof Request
+        const h = new Headers((init && init.headers) || (isReq ? input.headers : undefined))
+        let changed = false
+        for (const [name, value] of headers) {
+          if (!h.has(name)) {
+            h.set(name, value)
+            changed = true
+          }
+        }
+        if (changed) args = [input, Object.assign({}, init || {}, { headers: h })]
+      })
+    } catch (_) {}
+    const p = orig.apply(this, args)
+    if (!st || !p || typeof p.then !== 'function') return p
+    return p.then((res) => {
+      endState(st, res && res.status)
+      return res
+    }, (err) => {
+      endState(st, undefined, err)
+      throw err
+    })
+  }
+  for (const k of Object.getOwnPropertyNames(orig)) {
+    if (k === 'length' || k === 'name' || k === 'prototype') continue
+    try {
+      Object.defineProperty(fetch, k, Object.getOwnPropertyDescriptor(orig, k))
+    } catch (_) {}
+  }
+  copyMeta(fetch, orig)
+  globalThis.fetch = fetch
+}
+
+// ---------------------------------------------------------------------------------------------
+
+function refresh () {
+  if (!consumers.metrics && !consumers.tracing) return
+  installDc()
+  if (BUN) wrapBunFetch()
+  if (consumers.tracing && consumers.tracing.outbound && !hasCreatedChannel()) wantClientWrap()
+}
+
+function setConsumer (name, value) {
+  consumers[name] = value || null
+  refresh()
+}
+
+module.exports = { setConsumer, consumers, OUT, clientInfo, hasCreatedChannel, spanStarting, clientWrap }