@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/pmx.js

@@ -0,0 +1,757 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// The process-wide instrumentation instance: the @pm2/io-compatible public API
+// (80 A.11, NIO-033, NIO-040..042) and its lifecycle (A.1, A.2, A.8, A.9).
+
+const fs = require('fs')
+const { normalizeConfig, decorate, DEFAULT_WIDGET } = require('./config')
+const { MetricService, normalizeOpts } = require('./metrics/service')
+const { MetricType, MetricMeasurements, Gauge, Counter, Meter, Histogram } = require('./metrics/types')
+const { ActionService } = require('./actions')
+const { IPCTransport } = require('./transport/ipc')
+const { NotifyFeature } = require('./features/notify')
+const { initDefaultMetrics } = require('./features/metrics')
+const { resolveTracing } = require('./tracing/options')
+const control = require('./tracing/control')
+// 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] })
+const context = require('./tracing/context')
+const { readPackageJsonSync, findPackageJson, isPlainObject, jsonCopy } = require('./util')
+const { VERSION } = require('./constants')
+const debug = require('./debug')('axm:main')
+
+const STANDALONE_KEYS = ['PM2_PUBLIC_KEY', 'PM2_SECRET_KEY', 'PM2_APP_NAME']
+
+const printed = new Set()
+function printOnce (line) {
+  if (printed.has(line)) return
+  printed.add(line)
+  try {
+    process.stderr.write(line + '\n')
+  } catch (_) {}
+}
+
+const PUBLIC_METHODS = [
+  'init', 'destroy', 'getConfig', 'notifyError', 'notify', 'metric', 'gauge', 'counter', 'meter',
+  'histogram', 'metrics', 'probe', 'transpose', 'action', 'scopedAction', 'emit', 'onExit',
+  'getTracer', 'initModule', 'expressErrorHandler', 'koaErrorHandler', 'configureModule',
+  // trace context propagation (80 B.12)
+  'inject', 'extract', 'getBaggage', 'withBaggage', 'wrap', 'traceContext', 'consumerSpan'
+]
+
+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']
+
+function profilingEnabled (p) {
+  if (p === false) return false
+  if (p && typeof p === 'object' && p.implementation === 'none') return false
+  return true
+}
+
+function makeEntrypoint (io) {
+  return class Entrypoint {
+    constructor () {
+      io.init(this.conf())
+      this.io = io
+      this.onStart((err) => {
+        if (err) {
+          console.error(err)
+          process.exit(1)
+          return
+        }
+        this.sensors()
+        this.events()
+        this.actuators()
+        io.onExit((code, signal) => this.onStop(err, () => io.destroy(), code, signal))
+        io._sendRaw('ready')
+      })
+    }
+
+    onStart (cb) { // eslint-disable-line no-unused-vars
+      throw new Error('Entrypoint onStart() not specified')
+    }
+
+    onStop (err, cb, code, signal) { // eslint-disable-line no-unused-vars
+      return cb()
+    }
+
+    sensors () {}
+    events () {}
+    actuators () {}
+    conf () { return undefined }
+  }
+}
+
+class PMX {
+  get SpanContext () {
+    return w3c.SpanContext
+  }
+
+  get NEW_TRACE () {
+    return w3c.NEW_TRACE
+  }
+
+  constructor (options) {
+    options = options || {}
+    // Set by the preload: the process runs under pmx, so the IPC transport is always used.
+    this._managed = options.managed === true
+    // 'managed' (daemon root over IPC), 'relay' (hub relay), 'thread' (worker-thread relay),
+    // 'standalone' (standalone root), or null (not decided: IPC when under PM2, else inert or
+    // standalone per 80 NIO-260)
+    this._mode = options.managed === true ? 'managed' : (options.mode || null)
+    this._caps = Array.isArray(options.caps) ? options.caps : []
+    this._relayFactory = options.relayFactory || null
+    this._standalone = options.standalone || null
+    this._initialized = false
+    this._generation = 0
+    this._config = undefined
+    this._transport = null
+    this._metrics = null
+    this._actions = null
+    this._notify = null
+    this._profiling = null
+    this._tracing = null
+    // 80 NIO-298: the prodman layer (undefined until the first init reads PMX_IO_TRACING)
+    this._tracingLayer = undefined
+    this._appTracing = { value: undefined, has: false }
+    this._defaultMetrics = null
+    for (const m of PUBLIC_METHODS) this[m] = this[m].bind(this)
+    this.Entrypoint = makeEntrypoint(this)
+    this.MetricType = MetricType
+    this.MetricMeasurements = MetricMeasurements
+    this.Gauge = Gauge
+    this.Counter = Counter
+    this.Meter = Meter
+    this.Histogram = Histogram
+    this.version = VERSION
+  }
+
+  // ---------------------------------------------------------------- lifecycle
+
+  _createTransport (config) {
+    switch (this._mode) {
+      case 'managed':
+        return new IPCTransport()
+      case 'relay':
+        return this._relayFactory()
+      case 'thread': {
+        const { ThreadRelayTransport } = require('./relay/transport')
+        return new ThreadRelayTransport()
+      }
+      case 'standalone': {
+        // init({ standalone: true, apmOptions }) after activation (e.g. by the launcher)
+        const t = this._standalone.transport
+        if (config.apmOptions && typeof config.apmOptions === 'object') {
+          try {
+            const { resolveConfig } = require('./standalone/transport')
+            const cfg = resolveConfig(config.apmOptions, process.env, t.info, t.cfg)
+            if (!cfg.missing.length) t.reconfigure(cfg)
+          } catch (_) {}
+        }
+        this._standalone.instance = this
+        return t
+      }
+      default:
+    }
+    const underPM2 = process.env.pm_id !== undefined && typeof process.send === 'function'
+    if (underPM2) return new IPCTransport()
+    const present = STANDALONE_KEYS.filter((k) => process.env[k])
+    const wantStandalone = config.standalone === true || present.length === STANDALONE_KEYS.length || process.env.PMX_IO_STANDALONE === '1'
+    if (!wantStandalone && present.length > 0) {
+      const missing = STANDALONE_KEYS.filter((k) => !process.env[k])
+      printOnce(`[@pm2/io] not reporting to prodman: ${missing.join(', ')} not set (standalone mode needs PM2_PUBLIC_KEY, PM2_SECRET_KEY and PM2_APP_NAME)`)
+    }
+    if (wantStandalone) {
+      try {
+        const t = require('./standalone/activate').fromInit(this, config)
+        if (t) return t
+      } catch (err) {
+        debug('standalone activation failed: %s', err && err.message)
+      }
+    }
+    return new IPCTransport()
+  }
+
+  /** Root side of the relay protocol (hub connections and worker threads; 80 Part G.5). */
+  _onRelayMessage (msg) {
+    if (!msg || typeof msg !== 'object' || !this._initialized) return
+    const kind = msg.__pmx_relay__
+    if (kind === 'msg') {
+      const m = msg.m
+      if (!m || typeof m.type !== 'string' || !RELAYED_TYPES.includes(m.type)) return
+      if (m.type === 'trace-spans' && m.data && Array.isArray(m.data.spans) && this._tracing && this._tracing._sink) {
+        for (const span of m.data.spans) this._tracing._sink.add(span)
+      } else if (m.type === 'trace-span' && this._tracing && this._tracing._sink) this._tracing._sink.add(m.data)
+      else this._transport.send(m.type, m.data)
+    } else if (kind === 'metrics') {
+      if (Array.isArray(msg.c) && this._metrics) for (const item of msg.c) this._metrics.applyContribution(item)
+    } else if (kind === 'log') {
+      if (this._transport && typeof this._transport.onLogChunk === 'function' && typeof msg.d === 'string') {
+        this._transport.onLogChunk(msg.s === 'err' ? 'err' : 'out', msg.d)
+      }
+    }
+  }
+
+  _isRelay () {
+    return this._mode === 'relay' || this._mode === 'thread'
+  }
+
+  /** NIO-223: the reporter of exceptions frameworks turn into ≥ 500 responses. */
+  _errorsConsumer () {
+    return {
+      report: (st, status) => {
+        const err = st.error
+        if (!err || (typeof err === 'object' && err[REPORTED])) return
+        const req = st.req || {}
+        const info = st.info || {}
+        let path = req.path
+        let query = info.query
+        const url = req.url
+        if (typeof url === 'string') {
+          const q = url.indexOf('?')
+          if (path === undefined) path = q === -1 ? url : url.slice(0, q)
+          if (query === undefined && q !== -1) {
+            query = {}
+            try {
+              for (const [k, v] of new URLSearchParams(url.slice(q + 1))) query[k] = v
+            } catch (_) {}
+          }
+        }
+        const metadata = {
+          http: { url, method: req.method, path, route: st.route, query: query === undefined ? {} : query, params: info.params === undefined ? {} : info.params },
+          custom: { user: info.user }
+        }
+        const span = st.span
+        if (span && typeof span.traceId === 'string') {
+          metadata.trace_id = span.traceId
+          metadata.span_id = span.spanId
+        }
+        this._notify.notifyError(err, metadata, { status })
+      }
+    }
+  }
+
+  init (config) {
+    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
+    config = normalizeConfig(config)
+    // NIO-080/NIO-201: environment sources, then the app's `tracing` key (kept when absent)
+    config.tracing = resolveTracing(appTracing, hasTracing)
+    this._appTracing = { value: appTracing, has: hasTracing }
+    // 80 NIO-298 / INJ-026: the prodman layer beats every other source
+    if (this._tracingLayer === undefined) this._tracingLayer = control.layerFromEnv()
+    control.applyLayer(config.tracing, this._tracingLayer)
+    this._config = config
+    const generation = ++this._generation
+
+    // 1. transport
+    const transport = this._createTransport(config)
+    // pmx 97 PAP-050: under a pmx daemon the daemon decides; standalone, init > env > default
+    const managed = this._mode === 'managed' || (this._mode !== 'standalone' && process.env.pm_id !== undefined)
+    require('./application').resolve(config.application, { managed, warn: printOnce })
+    if (typeof transport.setApplication === 'function') transport.setApplication()
+    transport.init()
+    this._transport = transport
+    if (transport.tracingLayer && typeof transport.tracingLayer === 'object') {
+      // standalone: the layer from the last handshake / prodman:settings (PROTO-161)
+      this._tracingLayer = transport.tracingLayer
+      config.tracing = control.applyLayer(resolveTracing(appTracing, hasTracing), this._tracingLayer)
+    }
+    control.exportLayer(this._tracingLayer)
+
+    const relay = this._isRelay()
+    // Work the app's first line does not need and that sends nothing the 40 §5.2 sequence puts
+    // before the app's code (80 NIO-024) runs 100 ms later: the process-level default metrics
+    // and the dependency report. Skipped when init()/destroy() came first.
+    const later = []
+    // 2. inspector session (connected on first use)
+    const profiling = !relay && profilingEnabled(config.profiling)
+    this._profiling = null
+
+    // 3. actions, metrics (990 ms push)
+    this._notify = new NotifyFeature(transport)
+    this._actions = new ActionService(transport, (err) => this.notifyError(err))
+    this._metrics = new MetricService(transport)
+    if (relay && typeof transport.sendContributions === 'function') {
+      this._metrics.setRelay((list) => transport.sendContributions(list))
+      if (!this._onExitFlush) {
+        // the last second of a relay's metrics (contributions are otherwise sent every 1000 ms)
+        this._onExitFlush = () => {
+          try {
+            if (this._metrics) this._metrics.flushContributions()
+          } catch (_) {}
+        }
+        process.on('exit', this._onExitFlush)
+      }
+    }
+    this._metrics.start()
+
+    // 5. features: exceptions, profiling, events, metrics, tracing, dependencies
+    if (config.catchExceptions !== false) {
+      if (this._mode === 'thread') this._notify.enableThreadCapture()
+      else this._notify.enableCapture()
+      transport.send('axm:option:configuration', { error: true })
+    }
+    if (profiling) {
+      // synchronous: 40 §5.2 puts the profiling options and actions before the app's code
+      const { ProfilingFeature } = require('./features/profiling')
+      this._profiling = new ProfilingFeature(transport, this._actions)
+      this._profiling.connect()
+      this._profiling.init()
+    }
+    // request metrics now (a request can arrive in the first event-loop turn); the
+    // process-level groups (event loop, V8, GC/rusage, fds, network) one tick later
+    this._defaultMetrics = initDefaultMetrics(this._metrics, config.metrics, { relay, later: (fn) => later.unshift(fn) })
+    if (this._defaultMetrics.http) transport.send('axm:option:configuration', { latency: true })
+    if (config.httpErrors !== false) {
+      const inbound = require('./inbound')
+      inbound.setConsumer('errors', this._errorsConsumer())
+      require('./modules').enableErrors()
+      if (process.versions.bun) require('./bun').install()
+    }
+    if (config.tracing && config.tracing.enabled === true) this._startTracing(config)
+
+    // 6. full configuration
+    this._initialized = true
+    if (!relay) {
+      // synchronous: 40 §5.2 sends the full configuration before the app's code runs
+      const pkg = readPackageJsonSync()
+      const report = Object.assign({}, config)
+      delete report.apmOptions
+      decorate(report, pkg, process.env.name !== undefined ? process.env.name : 'outside-pm2')
+      transport.send('axm:option:configuration', report)
+      this._reportTracing()
+      // 40 §8.6: prodman tracing values, applied live (IPC message; standalone: from settings)
+      if (typeof transport.onMessage === 'function') {
+        transport.onMessage((m) => {
+          if (m && typeof m === 'object' && m.type === 'pmx:tracing' && generation === this._generation) {
+            this._setTracingLayer(control.cleanLayer(m.data))
+          }
+        })
+      }
+      // A.8.4 / 40 §5.2: the dependency report comes after the app's code has started
+      later.push(() => this._reportDependencies(generation))
+    }
+    if (later.length) {
+      // a timer, not setImmediate: with an --import preload Node runs the entry point after an
+      // asynchronous step, so immediates would still run before the app's first line. The
+      // first metric push is 990 ms away (GC pauses of the first 100 ms are not measured).
+      const t = setTimeout(() => {
+        for (const fn of later) {
+          if (generation !== this._generation || !this._initialized) return
+          try {
+            fn()
+          } catch (err) {
+            debug('deferred initialisation step failed: %s', err && err.message)
+          }
+        }
+      }, 100)
+      if (t.unref) t.unref()
+    }
+    debug('initialised (transport %s)', transport.kind)
+    return this
+  }
+
+  _startTracing (config) {
+    try {
+      const { TracingFeature } = require('./tracing/index')
+      const batch = this._mode === 'managed' && this._caps.includes('trace-spans')
+      this._tracing = new TracingFeature(this._transport, { metrics: this._metrics, batch })
+      this._tracing.init(config, config.tracing)
+      this._notify.setTracing(true)
+      if (process.versions.bun) require('./bun').install()
+    } catch (err) {
+      console.error('[pmx] tracing disabled: ' + (err && err.message))
+      this._tracing = null
+    }
+  }
+
+  /** 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
+    const t = control.applyLayer(resolveTracing(this._appTracing.value, this._appTracing.has), this._tracingLayer)
+    this._config.tracing = t
+    const want = t.enabled === true
+    if (want && !this._tracing && this._drainingTracing && this._drainingTracing.resume()) {
+      // switched on again while the previous switch-off was still draining: keep that tracer
+      this._tracing = this._drainingTracing
+      this._drainingTracing = null
+    }
+    if (want && !this._tracing) {
+      this._startTracing(this._config)
+    } else if (!want && this._tracing) {
+      // NIO-298: in-flight spans finish and are exported; no new spans meanwhile
+      const f = this._tracing
+      this._tracing = null
+      this._drainingTracing = f
+      try {
+        f.drain(() => {
+          if (this._drainingTracing === f) this._drainingTracing = null
+          if (this._notify && !this._tracing) this._notify.setTracing(false)
+        })
+      } catch (err) {
+        debug('tracing stop failed: %s', err && err.message)
+      }
+    }
+    if (want && this._tracing) {
+      const tracer = this._tracing.getTracer()
+      const eff = control.report(t, {}, {})
+      if (tracer) {
+        tracer.opts = t
+        tracer.sampleRatio = eff.sample_ratio.value
+        if (tracer.db) tracer.db.comment = eff.db_comment.value
+      }
+    }
+    this._reportTracing()
+  }
+
+  /** PROTO-163: `tracing_effective` with the source of each value. */
+  _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 || {}) })
+  }
+
+  _reportDependencies (generation) {
+    const file = findPackageJson()
+    if (!file) return
+    fs.readFile(file, 'utf8', (err, text) => {
+      if (err || generation !== this._generation || !this._initialized) return
+      let pkg
+      try {
+        pkg = JSON.parse(text)
+      } catch (_) {
+        return
+      }
+      if (!isPlainObject(pkg.dependencies)) return
+      const out = {}
+      for (const name of Object.keys(pkg.dependencies)) out[name] = { version: pkg.dependencies[name] }
+      this._transport.send('application:dependencies', out)
+    })
+  }
+
+  destroy () {
+    this._teardown(false)
+    if (this._mode === 'standalone' && this._standalone) {
+      try {
+        this._standalone.destroy()
+      } catch (_) {}
+    }
+  }
+
+  _teardown (keepTransport) {
+    if (!this._initialized) return
+    this._initialized = false
+    this._generation++
+    const safe = (fn) => {
+      try {
+        fn()
+      } catch (err) {
+        debug('destroy step failed: %s', err && err.message)
+      }
+    }
+    safe(() => this._tracing && this._tracing.destroy())
+    safe(() => this._drainingTracing && this._drainingTracing.destroy())
+    this._drainingTracing = null
+    safe(() => this._defaultMetrics && this._defaultMetrics.destroy())
+    safe(() => this._metrics && this._metrics.destroy())
+    safe(() => this._profiling && this._profiling.destroy())
+    safe(() => this._notify && this._notify.destroy())
+    safe(() => this._actions && this._actions.destroy())
+    safe(() => require('./inbound').setConsumer('errors', null))
+    // 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
+    this._notify = this._actions = null
+  }
+
+  getConfig () {
+    return this._config
+  }
+
+  _sendRaw (msg) {
+    if (this._transport) this._transport.sendRaw(msg)
+    else if (typeof process.send === 'function' && process.connected !== false) process.send(msg)
+  }
+
+  _send (type, data) {
+    if (this._transport && this._initialized) this._transport.send(type, data)
+  }
+
+  /** True while tracing is active (used by preload.mjs, NIO-083). */
+  _tracingEnabled () {
+    return Boolean(this._initialized && this._tracing && this._tracing.isEnabled())
+  }
+
+  // ---------------------------------------------------------------- metrics
+
+  _metricService () {
+    if (!this._metrics) {
+      console.trace('Tried to register a metric without initializing @pm2/io')
+      return null
+    }
+    return this._metrics
+  }
+
+  metric (opts) {
+    const s = this._metricService()
+    return s ? s.gauge(opts) : undefined
+  }
+
+  gauge (opts) {
+    return this.metric(opts)
+  }
+
+  counter (opts) {
+    const s = this._metricService()
+    return s ? s.counter(opts) : undefined
+  }
+
+  meter (opts) {
+    const s = this._metricService()
+    return s ? s.meter(opts) : undefined
+  }
+
+  histogram (opts) {
+    const s = this._metricService()
+    return s ? s.histogram(opts) : undefined
+  }
+
+  metrics (list) {
+    const s = this._metricService()
+    return s ? s.metrics(list) : []
+  }
+
+  /** Legacy: passive gauge (NIO-033). */
+  transpose (name, fn) {
+    let opts = normalizeOpts(name)
+    if (typeof fn === 'function') opts = Object.assign({}, opts, { value: fn })
+    else if (typeof opts.data === 'function') opts = Object.assign({}, opts, { value: opts.data })
+    return this.metric(opts)
+  }
+
+  /** Legacy probe() object (NIO-033). */
+  probe () {
+    return {
+      metric: (o) => this.metric(o),
+      gauge: (o) => this.metric(o),
+      counter: (o) => this.counter(o),
+      meter: (o) => this.meter(o),
+      histogram: (o) => this.histogram(o),
+      transpose: (n, f) => this.transpose(n, f)
+    }
+  }
+
+  // ---------------------------------------------------------------- actions
+
+  action (name, opts, handler) {
+    if (name !== null && typeof name === 'object' && opts === undefined && handler === undefined) {
+      handler = name.action
+      opts = name.options !== undefined ? name.options : name.opts
+      name = name.name
+    } else if (typeof opts === 'function' && handler === undefined) {
+      handler = opts
+      opts = undefined
+    }
+    if (!this._actions) return undefined
+    this._actions.register(name, opts, handler)
+    return undefined
+  }
+
+  scopedAction (name, handler) {
+    if (!this._actions) return undefined
+    this._actions.registerScoped(name, handler)
+    return undefined
+  }
+
+  // ---------------------------------------------------------------- errors & events
+
+  notifyError (err, context) {
+    if (!this._notify) return undefined
+    this._notify.notifyError(err, context)
+    return undefined
+  }
+
+  notify (err, context) {
+    return this.notifyError(err, context)
+  }
+
+  expressErrorHandler () {
+    if (!this._notify) return (err, req, res, next) => next(err)
+    return this._notify.expressErrorHandler()
+  }
+
+  koaErrorHandler () {
+    if (!this._notify) return async (ctx, next) => next()
+    return this._notify.koaErrorHandler()
+  }
+
+  emit (name, data) {
+    if (typeof name !== 'string') {
+      console.error('event name must be a string')
+      console.trace()
+      return undefined
+    }
+    if (data === null || typeof data !== 'object') {
+      console.error('event data must be an object')
+      console.trace()
+      return undefined
+    }
+    if (Array.isArray(data)) {
+      console.error('event data cannot be an array')
+      console.trace()
+      return undefined
+    }
+    let copy
+    try {
+      copy = jsonCopy(data)
+    } catch (err) {
+      console.log('Failed to serialize the event data ' + (err && err.message))
+      return undefined
+    }
+    copy = isPlainObject(copy) ? copy : {}
+    copy.__name = name
+    this._send('human:event', copy)
+    return undefined
+  }
+
+  onExit (fn) {
+    return require('./exit').onExit(fn)
+  }
+
+  // ---------------------------------------------------------------- tracing
+
+  getTracer () {
+    if (!this._tracing || !this._tracing.isEnabled()) return require('./tracing/tracer').noopTracer
+    return this._tracing.getTracer()
+  }
+
+  _activeTracer () {
+    return this._tracing && this._tracing.isEnabled() ? this._tracing.getTracer() : null
+  }
+
+  /** NIO-241. */
+  inject (carrier, options) {
+    try {
+      const o = options && typeof options === 'object' ? options : {}
+      let ctx = o.context
+      let bag
+      if (ctx === undefined || ctx === null) {
+        const store = context.current()
+        const span = store && store.span
+        if (!span || typeof span.traceId !== 'string') return carrier
+        // 85 OTX-012: the app's propagator in bridge mode
+        const b = this._activeTracer() && this._activeTracer().bridge
+        if (b && o.overwrite !== true && o.asBytes !== true && b.inject(carrier, span)) return carrier
+        ctx = span.context
+        bag = store.bag || span.bag
+      } else {
+        if (!w3c.isSpanContext(ctx)) {
+          if (ctx && w3c.isSpanContext(ctx.context)) ctx = ctx.context
+          else return carrier
+        }
+        bag = w3c.contextBag(ctx)
+      }
+      w3c.writeHeaders(carrier, w3c.headersFor(ctx, bag), o.overwrite === true, o.asBytes === true)
+    } catch (err) {
+      debug('inject failed: %s', err && err.message)
+    }
+    return carrier
+  }
+
+  /** NIO-242. */
+  extract (carrier) {
+    const t = this._activeTracer()
+    if (t && t.bridge) {
+      const ctx = t.bridge.extract(carrier)
+      if (ctx !== undefined) return ctx
+    }
+    return w3c.extract(carrier)
+  }
+
+  /** NIO-243. */
+  getBaggage () {
+    const store = context.current()
+    return w3c.bagObject(store && store.bag)
+  }
+
+  withBaggage (entries, fn) {
+    if (typeof fn !== 'function') throw new TypeError('withBaggage needs a function')
+    const store = context.current()
+    const bag = w3c.mergeBag((store && store.bag) || w3c.EMPTY_BAG, entries)
+    return context.run({ span: store && store.span, bag, server: store && store.server }, fn)
+  }
+
+  /** NIO-244. */
+  wrap (fn) {
+    return context.bind(fn)
+  }
+
+  /** NIO-245. */
+  traceContext () {
+    if (!this._activeTracer()) return {}
+    const span = context.currentSpan()
+    if (!span || typeof span.traceId !== 'string') return {}
+    return { trace_id: span.traceId, span_id: span.spanId, trace_sampled: span.sampled }
+  }
+
+  /** NIO-246. */
+  consumerSpan (carrier, options, fn) {
+    if (typeof options === 'function' && fn === undefined) {
+      fn = options
+      options = {}
+    }
+    const o = options && typeof options === 'object' ? options : {}
+    const tracer = this.getTracer()
+    const parent = w3c.extract(carrier) || w3c.NEW_TRACE
+    const attributes = Object.assign({}, o.attributes || {})
+    if (o.system !== undefined) attributes['messaging.system'] = o.system
+    if (o.destination !== undefined) attributes['messaging.destination.name'] = o.destination
+    attributes['messaging.operation'] = 'process'
+    const name = o.name || (o.destination !== undefined ? 'process ' + o.destination : 'process')
+    return tracer.startActiveSpan(name, { kind: 'consumer', parent, attributes }, fn)
+  }
+
+  // ---------------------------------------------------------------- modules
+
+  initModule (opts, cb) {
+    opts = isPlainObject(opts) ? opts : {}
+    if (opts.reference !== undefined) {
+      opts.name = opts.reference
+      delete opts.reference
+    }
+    opts.widget = Object.assign({}, DEFAULT_WIDGET, isPlainObject(opts.widget) ? opts.widget : {})
+    opts.isModule = true
+    const file = findPackageJson()
+    if (!file) throw new Error('Cannot find package.json for this module')
+    const pkg = JSON.parse(fs.readFileSync(file, 'utf8'))
+    opts.module_name = pkg.name
+    opts.module_version = pkg.version
+    opts.description = pkg.description
+    decorate(opts, pkg, pkg.name)
+    opts.module_name = pkg.name
+    if (typeof opts.module_version !== 'string') opts.module_version = String(pkg.version)
+    if (typeof opts.description !== 'string') opts.description = pkg.description === undefined ? '' : String(pkg.description)
+    if (this._transport) this._transport.send('axm:option:configuration', opts)
+    else this._sendRaw({ type: 'axm:option:configuration', data: opts })
+    if (typeof cb === 'function') {
+      cb(null, opts)
+      return undefined
+    }
+    return opts
+  }
+
+  /** Legacy: report module options. */
+  configureModule (opts) {
+    if (isPlainObject(opts)) this._send('axm:option:configuration', opts)
+    return undefined
+  }
+}
+
+module.exports = { PMX, PUBLIC_METHODS, REPORTED, printOnce }