@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/tracing/tracer.js

@@ -0,0 +1,850 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// The native tracer (80 B.8, NIO-200..NIO-211; parity with pmx-io's C.10 / C.12, Part G):
+// spans of kind INTERNAL/SERVER/CLIENT/PRODUCER/CONSUMER, parent-based trace-id-ratio sampling,
+// the duration floor with its exemptions, the export rate limit, links and the Zipkin v2 export
+// shape of 40 §7.11. No OpenTelemetry package is ever loaded.
+
+const path = require('path')
+const ctx = require('./context')
+const w3c = require('./w3c')
+const { normalizePath, rawPath } = require('./paths')
+const { VERSION } = require('../constants')
+const debug = require('../debug')('axm:tracing')
+
+const KINDS = ['INTERNAL', 'SERVER', 'CLIENT', 'PRODUCER', 'CONSUMER']
+const DEFAULT_IGNORE_INCOMING = [/(.*).js/, /(.*).css/, /(.*).png/, /(.*).ico/, /(.*).svg/, /webpack/]
+const DEFAULT_SAMPLE_RATIO = 1
+const DEFAULT_MAX_SPANS_PER_SECOND = 2000
+const DEFAULT_MIN_DURATION_US = 1000
+const MAX_LINKS = 128
+const MAX_LINKS_BYTES = 16384
+const TWO_63 = 2 ** 63
+const OTEL_API = Symbol.for('opentelemetry.js.api.1')
+
+// ---------------------------------------------------------------------------------------------
+// ids and clocks
+
+// /dev/urandom where it exists: loading crypto costs ~5 ms of start-up (NIO-024)
+function fillRandom (buf) {
+  const fs = require('fs')
+  try {
+    const fd = fs.openSync('/dev/urandom', 'r')
+    try {
+      if (fs.readSync(fd, buf, 0, buf.length, null) === buf.length) return
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch (_) {}
+  require('crypto').randomFillSync(buf)
+}
+
+const POOL = Buffer.allocUnsafe(4096)
+let poolOff = POOL.length
+
+function randomHex (bytes) {
+  for (;;) {
+    if (poolOff + bytes > POOL.length) {
+      fillRandom(POOL)
+      poolOff = 0
+    }
+    const s = POOL.toString('hex', poolOff, poolOff + bytes)
+    poolOff += bytes
+    if (!/^0+$/.test(s)) return s
+  }
+}
+
+// resolved on first use: reading globalThis.performance loads the perf_hooks internals (NIO-024)
+let perfObj = null
+let ORIGIN = 0
+function perfNow () {
+  if (perfObj === null) {
+    perfObj = globalThis.performance || require('perf_hooks').performance
+    ORIGIN = perfObj.timeOrigin
+  }
+  return perfObj.now()
+}
+const perf = { now: perfNow }
+
+function nowUs () {
+  const t = perfNow()
+  return Math.round((ORIGIN + t) * 1000)
+}
+
+function toUs (t) {
+  if (t instanceof Date) return t.getTime() * 1000
+  if (typeof t === 'number' && Number.isFinite(t)) return Math.round(t * 1000)
+  return undefined
+}
+
+// ---------------------------------------------------------------------------------------------
+// kinds
+
+function normKind (kind) {
+  if (kind === undefined || kind === null) return 'INTERNAL'
+  if (typeof kind === 'number' && Number.isInteger(kind) && kind >= 0 && kind <= 4) return KINDS[kind]
+  if (typeof kind === 'string') {
+    const k = kind.toUpperCase()
+    if (KINDS.includes(k)) return k
+  }
+  throw new TypeError('invalid span kind: ' + String(kind))
+}
+
+// ---------------------------------------------------------------------------------------------
+// tags
+
+function tagValue (v) {
+  if (typeof v === 'string') return v
+  if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'bigint') return String(v)
+  try {
+    const s = JSON.stringify(v)
+    return s === undefined ? String(v) : s
+  } catch (_) {
+    return String(v)
+  }
+}
+
+/** JSON with non-ASCII escaped as \uXXXX (Python's json.dumps default), compact. */
+function asciiJson (v) {
+  return JSON.stringify(v).replace(/[\u007f-￿]/g, (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'))
+}
+
+/** 40 §7.11.1: the `pmx.links` tag value and the number of links it had to leave out. */
+function encodeLinks (links, alreadyDropped) {
+  let dropped = alreadyDropped || 0
+  if (!links || links.length === 0) return { value: undefined, dropped }
+  const items = links.map((l) => {
+    const o = { traceId: l.context.traceId, spanId: l.context.spanId }
+    if (l.attributes) {
+      const a = {}
+      let any = false
+      for (const k of Object.keys(l.attributes)) {
+        const v = l.attributes[k]
+        if (v === undefined || v === null) continue
+        a[k] = tagValue(v)
+        any = true
+      }
+      if (any) o.attributes = a
+    }
+    return o
+  })
+  let value = asciiJson(items)
+  while (items.length > 0 && Buffer.byteLength(value, 'utf8') > MAX_LINKS_BYTES) {
+    items.pop()
+    dropped++
+    value = asciiJson(items)
+  }
+  return { value: items.length ? value : undefined, dropped }
+}
+
+function linkOf (el) {
+  if (w3c.isSpanContext(el)) return { context: el, attributes: undefined }
+  if (el && typeof el === 'object' && w3c.isSpanContext(el.context)) {
+    const attrs = el.attributes && typeof el.attributes === 'object' ? el.attributes : undefined
+    return { context: el.context, attributes: attrs }
+  }
+  if (el instanceof Span) return { context: el.context, attributes: undefined }
+  return null
+}
+
+// ---------------------------------------------------------------------------------------------
+// spans
+
+class Span {
+  constructor (tracer, name, kind, traceId, parentId, sampled, traceState, attributes, bag, remoteParent, localParent, startUs) {
+    this._tracer = tracer
+    this.name = String(name)
+    this.kind = kind
+    this.traceId = traceId
+    this.spanId = randomHex(8)
+    this.parentId = parentId || null
+    this.sampled = sampled
+    this.traceState = traceState || null
+    this.bag = bag || w3c.EMPTY_BAG
+    this.remoteParent = remoteParent === true
+    this.localParent = localParent || null
+    this.childExported = false
+    this.attributes = {}
+    if (attributes && typeof attributes === 'object') Object.assign(this.attributes, attributes)
+    this.events = null
+    this.links = null
+    this.droppedLinks = 0
+    this.maxLinks = MAX_LINKS
+    this.status = null
+    this.error = null
+    this.ended = false
+    this._ctx = null
+    if (startUs !== undefined) {
+      this.startUs = startUs
+      this._t0 = null
+    } else {
+      this.startUs = nowUs()
+      this._t0 = perf.now()
+    }
+  }
+
+  get context () {
+    if (!this._ctx) this._ctx = w3c.makeContext(this.traceId, this.spanId, this.sampled, this.traceState, this.bag, false)
+    return this._ctx
+  }
+
+  /** OpenTelemetry API compatibility. */
+  spanContext () {
+    return { traceId: this.traceId, spanId: this.spanId, traceFlags: this.sampled ? 1 : 0, isRemote: false }
+  }
+
+  isRecording () {
+    return !this.ended
+  }
+
+  setAttribute (key, value) {
+    if (!this.ended && typeof key === 'string') this.attributes[key] = value
+    return this
+  }
+
+  setAttributes (obj) {
+    if (!this.ended && obj && typeof obj === 'object') {
+      for (const k of Object.keys(obj)) this.attributes[k] = obj[k]
+    }
+    return this
+  }
+
+  updateName (name) {
+    if (!this.ended) this.name = String(name)
+    return this
+  }
+
+  addEvent (name, attrsOrTime, time) {
+    if (this.ended) return this
+    let t = toUs(typeof attrsOrTime === 'number' || attrsOrTime instanceof Date ? attrsOrTime : time)
+    if (t === undefined) t = nowUs()
+    const ev = { timestamp: t, value: String(name) }
+    if (this.events) this.events.push(ev)
+    else this.events = [ev]
+    return this
+  }
+
+  addLink (spanContext, attributes) {
+    if (this.ended) return this
+    const l = linkOf(attributes === undefined ? spanContext : { context: spanContext, attributes })
+    if (!l) return this
+    if (!this.links) this.links = []
+    if (this.links.length >= this.maxLinks) this.droppedLinks++
+    else this.links.push(l)
+    return this
+  }
+
+  /** OpenTelemetry API compatibility. */
+  addLinks (links) {
+    if (Array.isArray(links)) for (const l of links) this.addLink(l)
+    return this
+  }
+
+  recordException (err) {
+    if (this.ended) return this
+    this.status = 'ERROR'
+    let msg
+    if (err && typeof err === 'object' && typeof err.message === 'string') msg = err.message || err.name || 'Error'
+    else msg = String(err)
+    this.error = msg
+    return this
+  }
+
+  setStatus (status, message) {
+    if (this.ended) return this
+    let code = status
+    let msg = message
+    if (status && typeof status === 'object') {
+      code = status.code
+      if (msg === undefined) msg = status.message
+    }
+    if (code === 0 || (typeof code === 'string' && code.toUpperCase() === 'UNSET')) {
+      this.status = null
+      return this
+    }
+    if (code === 1 || (typeof code === 'string' && code.toUpperCase() === 'OK')) this.status = 'OK'
+    else if (code === 2 || (typeof code === 'string' && code.toUpperCase() === 'ERROR')) this.status = 'ERROR'
+    else return this
+    if (typeof msg === 'string' && msg !== '') this.error = msg
+    return this
+  }
+
+  traceparent () {
+    return `00-${this.traceId}-${this.spanId}-${this.sampled ? '01' : '00'}`
+  }
+
+  end (endTime) {
+    if (this.ended) return
+    this.ended = true
+    let duration
+    const endUs = toUs(endTime)
+    if (endUs !== undefined) duration = Math.max(0, endUs - this.startUs)
+    else if (this._t0 !== null) duration = Math.max(0, Math.round((perf.now() - this._t0) * 1000))
+    else duration = Math.max(0, nowUs() - this.startUs)
+    try {
+      if (!this._noExport) this._tracer._export(this, duration)
+    } catch (err) {
+      debug('span export failed: %s', err && err.message)
+    }
+    this._tracer._spanEnded(this)
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// no-op tracer (tracing disabled, NIO-207)
+
+const noopSpan = Object.freeze({
+  context: null,
+  name: '',
+  ended: true,
+  sampled: false,
+  spanContext: () => ({ traceId: '00000000000000000000000000000000', spanId: '0000000000000000', traceFlags: 0, isRemote: false }),
+  isRecording: () => false,
+  setAttribute () { return this },
+  setAttributes () { return this },
+  updateName () { return this },
+  addEvent () { return this },
+  addLink () { return this },
+  addLinks () { return this },
+  recordException () { return this },
+  setStatus () { return this },
+  traceparent: () => null,
+  end () {}
+})
+
+function splitActiveArgs (args) {
+  const fn = args[args.length - 1]
+  if (typeof fn !== 'function') throw new TypeError('startActiveSpan needs a function')
+  const options = args.length >= 2 && args[0] && typeof args[0] === 'object' ? args[0] : undefined
+  return { options, fn }
+}
+
+const noopTracer = Object.freeze({
+  enabled: false,
+  startSpan (name, options) {
+    normKind(options && options.kind)
+    return noopSpan
+  },
+  startActiveSpan (name, ...args) {
+    const { options, fn } = splitActiveArgs(args)
+    normKind(options && options.kind)
+    return fn(noopSpan)
+  },
+  withSpan (span, fn) {
+    return fn(span)
+  },
+  currentSpan () {
+    return undefined
+  }
+})
+
+// ---------------------------------------------------------------------------------------------
+// tracer
+
+function num (v, what) {
+  if (v === undefined || v === null || typeof v === 'boolean') {
+    if (typeof v === 'boolean') debug('ignoring non-numeric %s: %s', what, v)
+    return undefined
+  }
+  const n = typeof v === 'number' ? v : Number(v)
+  if (typeof v === 'string' && v.trim() === '') return undefined
+  if (!Number.isFinite(n)) {
+    debug('ignoring non-numeric %s: %s', what, v)
+    return undefined
+  }
+  return n
+}
+
+function testEnv () {
+  return process.env.NODE_ENV === 'test' || process.env.PMX_IO_ENV === 'test'
+}
+
+function matches (rules, url, request) {
+  for (const r of rules) {
+    try {
+      if (typeof r === 'string' && url.includes(r)) return true
+      if (r instanceof RegExp && r.test(url)) return true
+      if (typeof r === 'function' && r(url, request)) return true
+    } catch (_) {}
+  }
+  return false
+}
+
+/** True when trace id `traceId` is sampled at `ratio` (PYI-096; same answer as pmx-io). */
+function sampledFor (traceId, ratio) {
+  if (ratio >= 1) return true
+  if (ratio <= 0) return false
+  return (BigInt('0x' + traceId.slice(16)) >> 1n) < ratio * TWO_63
+}
+
+/**
+ * `tracing.db` (NIO-200, 82 ITG-001/ITG-014/ITG-015/ITG-016): null when off, else
+ * { statement, poolSpans, comment ('on' | 'off' | 'force', 96 SVM-500), applicationName }.
+ */
+function dbOptions (v) {
+  if (v === false || (v && typeof v === 'object' && v.enabled === false)) return null
+  const o = v && typeof v === 'object' ? v : {}
+  const st = typeof o.statement === 'string' ? o.statement.toLowerCase() : 'sanitized'
+  return {
+    statement: st === 'raw' || st === 'off' ? st : 'sanitized',
+    poolSpans: o.poolSpans !== false,
+    comment: require('../itg/dbcomment').normMode(o.comment),
+    applicationName: o.applicationName !== false && o.application_name !== false
+  }
+}
+
+/** `tracing.messaging` (82 ITG-001): null when off, else the resolved object. */
+function messagingOptions (v) {
+  if (v === false || (v && typeof v === 'object' && v.enabled === false)) return null
+  const o = v && typeof v === 'object' ? v : {}
+  let maxLinks = Number(o.maxLinks)
+  if (!Number.isFinite(maxLinks) || o.maxLinks === undefined || o.maxLinks === null) maxLinks = MAX_LINKS
+  maxLinks = Math.max(0, Math.min(1000, Math.floor(maxLinks)))
+  return {
+    rootProducers: o.rootProducers === true,
+    redisStreamFields: o.redisStreamFields === true,
+    payloadCarrier: o.payloadCarrier === true,
+    maxLinks
+  }
+}
+
+function serviceName (opts, config) {
+  if (typeof opts.serviceName === 'string' && opts.serviceName) return opts.serviceName
+  if (process.env.OTEL_SERVICE_NAME) return process.env.OTEL_SERVICE_NAME
+  const apm = config && config.apmOptions
+  if (apm && typeof apm.appName === 'string' && apm.appName) return apm.appName
+  if (process.env.name) return process.env.name
+  const script = process.argv[1]
+  if (script) return path.basename(script).replace(/\.[^.]*$/, '') || 'node'
+  return 'node'
+}
+
+class Tracer {
+  /**
+   * @param {object} opts resolved `tracing` options (NIO-200)
+   * @param {{add: Function}} sink receives finished Zipkin spans
+   * @param {object} [extra] { config, onDrop(n) }
+   */
+  constructor (opts, sink, extra) {
+    this._open = 0
+    this.stopping = false
+    extra = extra || {}
+    this.enabled = true
+    this.opts = opts
+    this._sink = sink
+    this._onDrop = extra.onDrop || null
+    // called before each span is made (outbound wrapping on Node < 22.12), or null
+    this._onStart = typeof extra.onStart === 'function' ? extra.onStart : null
+    // 85 bridge mode: set once an app OpenTelemetry SDK is detected (one-way, OTX-003)
+    this.bridge = null
+    this._bridgeEnv = extra.bridge || null
+    this.serviceName = serviceName(opts, extra.config)
+    this.ignoreIncoming = Array.isArray(opts.ignoreIncomingPaths) ? opts.ignoreIncomingPaths.slice() : DEFAULT_IGNORE_INCOMING
+    this.ignoreOutgoing = Array.isArray(opts.ignoreOutgoingUrls) ? opts.ignoreOutgoingUrls.slice() : []
+    const ratio = num(opts.sampleRatio, 'sampleRatio')
+    this.sampleRatio = ratio === undefined ? DEFAULT_SAMPLE_RATIO : Math.min(1, Math.max(0, ratio))
+    this.exportUnsampledErrors = opts.exportUnsampledErrors !== false
+    const rate = num(opts.maxSpansPerSecond, 'maxSpansPerSecond')
+    this.maxSpansPerSecond = rate === undefined ? DEFAULT_MAX_SPANS_PER_SECOND : Math.max(0, rate)
+    const floor = num(opts.minDurationUs, 'minDurationUs')
+    this.minDurationUs = floor === undefined ? (testEnv() ? 0 : DEFAULT_MIN_DURATION_US) : Math.max(0, floor)
+    this.outbound = opts.outbound !== false
+    this.normalizePaths = opts.normalizePaths !== false
+    this.baggageTags = Array.isArray(opts.baggageTags) ? opts.baggageTags.map(String) : []
+    this.db = dbOptions(opts.db)
+    this.messaging = messagingOptions(opts.messaging)
+    const lc = opts.logCorrelation
+    this.logCorrelation = lc !== false && !(lc && typeof lc === 'object' && lc.enabled === false)
+    this.consoleCorrelation = this.logCorrelation && Boolean(lc && typeof lc === 'object' && lc.console === true)
+    this._tokens = this.maxSpansPerSecond
+    this._refill = null // first export (keeps perf_hooks off the start-up path)
+    this.dropped = 0
+    this._dropLogged = 0
+    this._nextTraceId = null
+    const bun = typeof process.versions.bun === 'string'
+    this.resource = {
+      'service.name': this.serviceName,
+      'process.pid': String(process.pid),
+      'process.runtime.name': bun ? 'bun' : 'nodejs',
+      'process.runtime.version': bun ? process.versions.bun : process.versions.node,
+      'telemetry.sdk.name': '@pmx/io',
+      'telemetry.sdk.language': 'nodejs',
+      'telemetry.sdk.version': VERSION,
+      'telemetry.distro.name': 'pmx'
+    }
+    // pmx 97 PAP-051: `pmx.application` always; `service.namespace` = the application when it
+    // isn't `default`, else a non-default pm2 namespace
+    const appl = require('../application')
+    const application = appl.current()
+    this.resource['pmx.application'] = application
+    const ns = appl.serviceNamespace(application, process.env.namespace)
+    if (ns) this.resource['service.namespace'] = ns
+  }
+
+  // -- construction ---------------------------------------------------------------------------
+
+  _newTrace () {
+    let traceId = this._nextTraceId
+    this._nextTraceId = null
+    if (!traceId) traceId = randomHex(16)
+    return { traceId, sampled: sampledFor(traceId, this.sampleRatio) }
+  }
+
+  _make (name, kind, traceId, parentId, sampled, traceState, attributes, bag, remote, local, startUs) {
+    // NIO-298: while tracing is being switched off, spans still work for their callers but are
+    // unsampled and never exported (no DB tags either); spans started before keep their export
+    if (this.stopping) return this._makeDrained(name, kind, traceId, parentId, traceState, attributes, bag, remote, local, startUs)
+    this._open++
+    const span = this._makeSpan(name, kind, traceId, parentId, sampled, traceState, attributes, bag, remote, local, startUs)
+    span._counted = true
+    return span
+  }
+
+  _makeDrained (name, kind, traceId, parentId, traceState, attributes, bag, remote, local, startUs) {
+    const span = this._makeSpan(name, kind, traceId, parentId, false, traceState, attributes, bag, remote, local, startUs)
+    span._noExport = true
+    return span
+  }
+
+  /** a span ended: one fewer in flight (drain of NIO-298) */
+  _spanEnded (span) {
+    if (span._counted) {
+      span._counted = false
+      this._open--
+    }
+  }
+
+  _makeSpan (name, kind, traceId, parentId, sampled, traceState, attributes, bag, remote, local, startUs) {
+    if (this._onStart !== null) {
+      try {
+        this._onStart()
+      } catch (_) {}
+    }
+    const span = new Span(this, name, kind, traceId, parentId, sampled, traceState, attributes, bag, remote, local, startUs)
+    if (this.baggageTags.length && span.bag.length) {
+      for (const key of this.baggageTags) {
+        const e = span.bag.find((x) => x[0] === key)
+        if (e) span.attributes['baggage.' + key] = e[1]
+      }
+    }
+    return span
+  }
+
+  /** A span of this process under the local span `parent` (baggage: the current one). */
+  childOf (parent, name, kind, attributes) {
+    if (this.bridge) return this.bridge.child(parent, name, kind, attributes)
+    const store = ctx.current()
+    const bag = store && store.bag ? store.bag : parent.bag
+    return this._make(name, kind, parent.traceId, parent.spanId, parent.sampled, parent.traceState, attributes, bag, false, parent)
+  }
+
+  // -- public API (NIO-207) -------------------------------------------------------------------
+
+  /**
+   * OTX-002/003: switch to bridge mode when the app registered an OpenTelemetry SDK. Called at
+   * activation and before entry spans; a property lookup when there is no OTel API global.
+   */
+  checkBridge () {
+    if (this.bridge) return this.bridge
+    if (globalThis[OTEL_API] === undefined || !this._bridgeEnv) return null
+    let b = null
+    try {
+      const mod = require('../otel/bridge')
+      const provider = mod.detect()
+      if (!provider) return null
+      b = new mod.Bridge(this, provider, this._bridgeEnv)
+      this.bridge = b
+      ctx.setBridge(b)
+      b.start()
+    } catch (err) {
+      debug('OpenTelemetry bridge failed: %s', err && err.message)
+    }
+    return this.bridge
+  }
+
+  startSpan (name, options) {
+    const o = options && typeof options === 'object' ? options : {}
+    const kind = normKind(o.kind)
+    const b = this.bridge || this.checkBridge()
+    if (b) {
+      const parent = o.parent === noopSpan || o.parent === null ? undefined : o.parent
+      if (parent !== undefined && parent !== w3c.NEW_TRACE && !(parent instanceof Span) && !w3c.isSpanContext(parent) && !(parent && parent.foreign)) {
+        throw new TypeError('parent must be undefined, a Span, a SpanContext or NEW_TRACE')
+      }
+      return b.startSpan(name, kind, { parent, links: o.links, attributes: o.attributes, startUs: toUs(o.startTime) }, ctx.current())
+    }
+    const startUs = toUs(o.startTime)
+    let parent = o.parent
+    if (parent === noopSpan || parent === null) parent = undefined
+    let span
+    if (parent === undefined) {
+      const store = ctx.current()
+      const cur = store && store.span
+      if (cur && cur !== noopSpan) {
+        const bag = store.bag || cur.bag
+        span = this._make(name, kind, cur.traceId, cur.spanId, cur.sampled, cur.traceState, o.attributes, bag, false, cur, startUs)
+      } else {
+        const t = this._newTrace()
+        span = this._make(name, kind, t.traceId, null, t.sampled, null, o.attributes, store && store.bag, false, null, startUs)
+      }
+    } else if (parent === w3c.NEW_TRACE) {
+      const store = ctx.current()
+      const t = this._newTrace()
+      span = this._make(name, kind, t.traceId, null, t.sampled, null, o.attributes, store && store.bag, false, null, startUs)
+    } else if (parent instanceof Span) {
+      span = this._make(name, kind, parent.traceId, parent.spanId, parent.sampled, parent.traceState, o.attributes, parent.bag, false, parent, startUs)
+    } else if (w3c.isSpanContext(parent)) {
+      span = this._make(name, kind, parent.traceId, parent.spanId, parent.sampled, parent.traceState, o.attributes, w3c.contextBag(parent), parent.isRemote, null, startUs)
+    } else {
+      throw new TypeError('parent must be undefined, a Span, a SpanContext or NEW_TRACE')
+    }
+    if (Array.isArray(o.links)) for (const l of o.links) span.addLink(l)
+    return span
+  }
+
+  startActiveSpan (name, ...args) {
+    const { options, fn } = splitActiveArgs(args)
+    const span = this.startSpan(name, options)
+    return runActive(span, fn)
+  }
+
+  withSpan (span, fn) {
+    if (!(span instanceof Span)) return fn(span)
+    const store = ctx.current()
+    return ctx.run({ span, bag: span.bag, server: store && store.server }, fn, undefined, [span])
+  }
+
+  currentSpan () {
+    const s = ctx.currentSpan()
+    return s instanceof Span ? s : undefined
+  }
+
+  // -- instrumentation helpers ----------------------------------------------------------------
+
+  ignoreInbound (method, target, request) {
+    const m = String(method || '').toUpperCase()
+    if (m === 'OPTIONS' || m === 'HEAD') return true
+    return matches(this.ignoreIncoming, target || '', request)
+  }
+
+  /** NIO-220: a SERVER span for an inbound request, or null when ignored. */
+  serverSpan (req) {
+    const method = req.method || 'GET'
+    const target = req.target
+    if (this.ignoreInbound(method, target, req.request)) return null
+    const b = this.bridge || this.checkBridge()
+    if (b) {
+      const tags = { 'http.method': method, 'http.target': target, 'http.scheme': req.scheme, 'http.host': req.host, 'http.url': `${req.scheme}://${req.host}${target}` }
+      if (req.userAgent) tags['http.user_agent'] = req.userAgent
+      return b.serverSpan(method + ' ' + (this.normalizePaths ? normalizePath(target) : rawPath(target)), tags, req.headers)
+    }
+    const headers = req.headers
+    // Node's IncomingHttpHeaders have lowercase keys: read them directly (hot path)
+    const plain = Boolean(headers && req.lowercaseHeaders === true)
+    const read = (name) => (plain ? headers[name] : firstValue(headers, name))
+    const parsed = headers ? w3c.parseTraceparent(read('traceparent')) : null
+    let traceId
+    let parentId = null
+    let sampled
+    let state = null
+    let remote = false
+    if (parsed) {
+      traceId = parsed.traceId
+      parentId = parsed.spanId
+      sampled = parsed.sampled
+      remote = true
+      const states = (plain ? [].concat(headers.tracestate === undefined ? [] : headers.tracestate) : w3c.getAll(headers, 'tracestate')).map(w3c.text).filter((s) => s)
+      state = states.length ? states.join(',') : null
+    } else {
+      const t = this._newTrace()
+      traceId = t.traceId
+      sampled = t.sampled
+    }
+    const rawBag = headers ? (plain ? headers.baggage : w3c.getAll(headers, 'baggage')) : undefined
+    const bag = rawBag === undefined || (Array.isArray(rawBag) && rawBag.length === 0) ? w3c.EMPTY_BAG : w3c.parseBaggage(rawBag)
+    const tags = {
+      'http.method': method,
+      'http.target': target,
+      'http.scheme': req.scheme,
+      'http.host': req.host,
+      'http.url': `${req.scheme}://${req.host}${target}`
+    }
+    if (req.userAgent) tags['http.user_agent'] = req.userAgent
+    const name = method + ' ' + (this.normalizePaths ? normalizePath(target) : rawPath(target))
+    return this._make(name, 'SERVER', traceId, parentId, sampled, state, tags, bag, remote, null)
+  }
+
+  /** NIO-222: a CLIENT span under the current span, or null (no root CLIENT spans). */
+  clientSpan (method, url, host, port, request) {
+    if (!this.outbound) return null
+    const store = ctx.current()
+    const parent = store && store.span
+    if (this.bridge) {
+      if (!parent || matches(this.ignoreOutgoing, url, request)) return null
+      const t = { 'http.method': method, 'http.url': url, 'net.peer.name': host }
+      if (port) t['net.peer.port'] = port
+      return this.bridge.child(parent, method + ' ' + host, 'CLIENT', t)
+    }
+    if (!(parent instanceof Span)) return null
+    if (matches(this.ignoreOutgoing, url, request)) return null
+    const tags = { 'http.method': method, 'http.url': url, 'net.peer.name': host }
+    if (port) tags['net.peer.port'] = port
+    return this.childOf(parent, method + ' ' + host, 'CLIENT', tags)
+  }
+
+  // -- export (NIO-204..NIO-206) --------------------------------------------------------------
+
+  _takeToken () {
+    const rate = this.maxSpansPerSecond
+    if (rate <= 0) return true
+    const now = perf.now()
+    if (this._refill === null) this._refill = now
+    let tokens = this._tokens + ((now - this._refill) / 1000) * rate
+    this._refill = now
+    if (tokens > rate) tokens = rate
+    if (tokens >= 1) {
+      this._tokens = tokens - 1
+      return true
+    }
+    this._tokens = tokens
+    return false
+  }
+
+  recordDropped (n) {
+    n = n || 1
+    this.dropped += n
+    const now = Date.now()
+    if (now - this._dropLogged >= 60000) {
+      this._dropLogged = now
+      debug('trace spans dropped (rate limit or send failure): %d so far', this.dropped)
+    }
+    if (this._onDrop) {
+      try {
+        this._onDrop(n)
+      } catch (_) {}
+    }
+  }
+
+  /** OTX-032: a span converted by the bridge's processor (the app SDK sampled it already). */
+  exportConverted (zipkin) {
+    if (!this._takeToken()) {
+      this.recordDropped(1)
+      return
+    }
+    this._sink.add(zipkin)
+  }
+
+  flush () {
+    if (this._sink && typeof this._sink.flush === 'function') this._sink.flush()
+  }
+
+  _export (span, durationUs) {
+    const local = span.localParent
+    span.localParent = null
+    // 1. root CLIENT spans are never exported (A.6)
+    if (span.kind === 'CLIENT' && !span.parentId) return
+    const error = span.status === 'ERROR'
+    // 2. sampling (NIO-205)
+    if (!span.sampled && !(error && this.exportUnsampledErrors)) return
+    // 3. duration floor and its exemptions
+    if (durationUs <= this.minDurationUs && !error && span.kind !== 'PRODUCER' && !span.remoteParent && !span.childExported) return
+    // 4. rate limit (NIO-206)
+    if (!this._takeToken()) {
+      this.recordDropped(1)
+      return
+    }
+    if (local) local.childExported = true
+    this._sink.add(this.toZipkin(span, durationUs))
+  }
+
+  toZipkin (span, durationUs) {
+    const tags = {}
+    const attrs = span.attributes
+    for (const k of Object.keys(attrs)) {
+      const v = attrs[k]
+      if (v === undefined || v === null) continue
+      tags[k] = tagValue(v)
+    }
+    const alias = (legacy, stable) => {
+      if (tags[legacy] === undefined && tags[stable] !== undefined) tags[legacy] = tags[stable]
+    }
+    alias('http.method', 'http.request.method')
+    alias('http.status_code', 'http.response.status_code')
+    alias('http.url', 'url.full')
+    alias('http.scheme', 'url.scheme')
+    if (tags['http.target'] === undefined && tags['url.path'] !== undefined) {
+      tags['http.target'] = tags['url.path'] + (tags['url.query'] !== undefined ? '?' + tags['url.query'] : '')
+    }
+    if (span.status) {
+      tags['otel.status_code'] = span.status
+      if (span.status === 'ERROR' && span.error) tags.error = span.error
+    }
+    if (!span.sampled) tags['pmx.sampled'] = 'false'
+    const links = encodeLinks(span.links, span.droppedLinks)
+    if (links.value !== undefined) tags['pmx.links'] = links.value
+    if (links.dropped) tags['otel.dropped_links_count'] = String(links.dropped)
+    for (const k of Object.keys(this.resource)) {
+      if (tags[k] === undefined) tags[k] = this.resource[k]
+    }
+    const out = { traceId: span.traceId, id: span.spanId }
+    if (span.parentId) out.parentId = span.parentId
+    out.name = span.name
+    if (span.kind !== 'INTERNAL') out.kind = span.kind
+    out.timestamp = span.startUs
+    out.duration = durationUs
+    out.localEndpoint = { serviceName: this.serviceName }
+    out.tags = tags
+    if (span.events && span.events.length) out.annotations = span.events.slice()
+    return out
+  }
+}
+
+/** startActiveSpan semantics (NIO-207): the span ends when fn returns, throws or settles. */
+function runActive (span, fn) {
+  if (!(span instanceof Span)) return fn(span)
+  const store = ctx.current()
+  let r
+  try {
+    r = ctx.run({ span, bag: span.bag, server: store && store.server }, fn, undefined, [span])
+  } catch (err) {
+    span.recordException(err)
+    span.end()
+    throw err
+  }
+  if (r && typeof r.then === 'function') {
+    return Promise.resolve(r).then((v) => {
+      span.end()
+      return v
+    }, (err) => {
+      span.recordException(err)
+      span.end()
+      throw err
+    })
+  }
+  span.end()
+  return r
+}
+
+function firstValue (headers, name) {
+  const all = w3c.getAll(headers, name)
+  return all.length ? all[0] : undefined
+}
+
+module.exports = {
+  Tracer,
+  Span,
+  noopTracer,
+  noopSpan,
+  normKind,
+  sampledFor,
+  encodeLinks,
+  tagValue,
+  runActive,
+  randomHex,
+  nowUs,
+  dbOptions,
+  messagingOptions,
+  DEFAULT_IGNORE_INCOMING,
+  MAX_LINKS
+}