@aidra/pmx-io 0.0.0-stage → 9.14.0

package/lib/otel/bridge.js

@@ -0,0 +1,797 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Bridge mode (85 Part A; OTX-001…OTX-036, Node side): when the app runs its own OpenTelemetry SDK,
+// @aidra/pmx-io creates its spans through that SDK instead of exporting competing ones.
+//
+//  * Detection (OTX-002/003) is a property lookup on the OTel API's global registry
+//    (globalThis[Symbol.for('opentelemetry.js.api.1')]); this module is loaded only once an app SDK
+//    was found. The switch is one-way; spans started natively before it end natively.
+//  * Spans (OTX-010/015): created with the app SDK's tracer '@aidra/pmx-io' and wrapped in BridgeSpan,
+//    which has the native Span's API, so instrumentation and getTracer() code is unchanged.
+//  * Context (OTX-011): the OTel active context is the source of truth. When pmx makes a span current
+//    (context.js run/enter/bind) it also makes the OTel span active; pmx's current span is the OTel
+//    active span (its own BridgeSpan, or a ForeignSpan wrapping an app/OTel-instrumentation span).
+//  * Propagation (OTX-012): inject/extract and inbound/outbound HTTP use the app's global propagator.
+//  * Sampling (OTX-013): the app SDK's sampler decides; pmx's sampling options are ignored.
+//  * No double spans (OTX-020/021): no SERVER span when a recording SERVER span of another scope is
+//    active; no CLIENT/PRODUCER span when the active span is a recording span of the same kind from
+//    another scope; libraries whose hooked function OTel's shimmer wrapped again (`__wrapped`) are
+//    passed through (lib/itg/common.js). Metrics are never suppressed (OTX-022).
+//  * Export (OTX-030…036): 'receiver' (the app's OTLP exporter reaches prodman), 'processor' (a span
+//    processor added to the app SDK converts finished, sampled spans to the native Zipkin shape and
+//    hands them to the native export pipeline) or 'none'.
+//
+// Nothing here requires an OpenTelemetry package: only objects the app's SDK registered are used.
+
+const { VERSION } = require('../constants')
+const w3c = require('../tracing/w3c')
+const debug = require('../debug')('axm:tracing')
+
+const API_KEY = Symbol.for('opentelemetry.js.api.1')
+const SPAN_KEY = Symbol.for('OpenTelemetry Context Key SPAN')
+const KINDS = ['INTERNAL', 'SERVER', 'CLIENT', 'PRODUCER', 'CONSUMER']
+const OTEL_KIND = { INTERNAL: 0, SERVER: 1, CLIENT: 2, PRODUCER: 3, CONSUMER: 4 }
+
+/** OTX-002: the app's tracer provider, or null (no allocation when there is none). */
+function detect () {
+  const g = globalThis[API_KEY]
+  if (!g || !g.trace) return null
+  let p = g.trace
+  try {
+    if (typeof p.getDelegate === 'function') p = p.getDelegate()
+  } catch (_) {
+    return null
+  }
+  if (!p || (p.constructor && p.constructor.name === 'NoopTracerProvider')) return null
+  return p
+}
+
+// ---------------------------------------------------------------------------------------------
+// minimal OTel-compatible values (no API package is loaded)
+
+class BaseContext {
+  constructor (parent) {
+    this._v = parent ? new Map(parent._v) : new Map()
+  }
+
+  getValue (k) {
+    return this._v.get(k)
+  }
+
+  setValue (k, v) {
+    const c = new BaseContext(this)
+    c._v.set(k, v)
+    return c
+  }
+
+  deleteValue (k) {
+    const c = new BaseContext(this)
+    c._v.delete(k)
+    return c
+  }
+}
+const ROOT = new BaseContext()
+
+class TraceState {
+  constructor (s) {
+    this._s = s || ''
+  }
+
+  serialize () {
+    return this._s
+  }
+
+  get (key) {
+    for (const part of this._s.split(',')) {
+      const i = part.indexOf('=')
+      if (i > 0 && part.slice(0, i).trim() === key) return part.slice(i + 1).trim()
+    }
+    return undefined
+  }
+
+  set () { return this }
+  unset () { return this }
+}
+
+/** A non-recording span standing for a remote or native parent context. */
+function parentSpan (traceId, spanId, sampled, traceState, isRemote) {
+  const sc = { traceId, spanId, traceFlags: sampled ? 1 : 0, isRemote: Boolean(isRemote) }
+  if (traceState) sc.traceState = new TraceState(traceState)
+  return {
+    spanContext: () => sc,
+    isRecording: () => false,
+    setAttribute () { return this },
+    setAttributes () { return this },
+    addEvent () { return this },
+    addLink () { return this },
+    addLinks () { return this },
+    setStatus () { return this },
+    updateName () { return this },
+    recordException () {},
+    end () {}
+  }
+}
+
+const SETTER = { set (c, k, v) { c[k] = v } }
+const GETTER = {
+  keys: (c) => Object.keys(c || {}),
+  get (c, k) {
+    const all = w3c.getAll(c, String(k).toLowerCase())
+    if (all.length === 0) return undefined
+    return all.length === 1 ? w3c.text(all[0]) || all[0] : all.map((v) => w3c.text(v) || v)
+  }
+}
+
+function scopeOf (o) {
+  const s = o && (o.instrumentationScope || o.instrumentationLibrary)
+  return s && typeof s.name === 'string' ? s.name : undefined
+}
+
+function kindOf (o) {
+  return o && typeof o.kind === 'number' ? KINDS[o.kind] : undefined
+}
+
+/** '@opentelemetry/instrumentation-pg' → 'pg' (the name reported in `suppressed`). */
+function libName (scope) {
+  if (!scope) return 'unknown'
+  return scope.replace(/^@opentelemetry\/instrumentation-/, '').replace(/^opentelemetry-instrumentation-/, '')
+}
+
+// ---------------------------------------------------------------------------------------------
+// spans
+
+function makeSpanClasses (Span) {
+  /** A pmx span backed by an app SDK span (OTX-010). */
+  class BridgeSpan extends Span {
+    constructor (tracer, otel, name, kind, parentId, attributes, bag) {
+      const sc = otel.spanContext()
+      super(tracer, name, kind, sc.traceId, parentId, (sc.traceFlags & 1) === 1,
+        sc.traceState && typeof sc.traceState.serialize === 'function' ? sc.traceState.serialize() || null : null,
+        attributes, bag, false, null)
+      this.spanId = sc.spanId
+      this.otel = otel
+    }
+
+    setAttribute (key, value) {
+      if (!this.ended && typeof key === 'string') {
+        this.attributes[key] = value
+        try {
+          if (value !== undefined && value !== null) this.otel.setAttribute(key, otelValue(value))
+        } catch (_) {}
+      }
+      return this
+    }
+
+    setAttributes (obj) {
+      if (obj && typeof obj === 'object') for (const k of Object.keys(obj)) this.setAttribute(k, obj[k])
+      return this
+    }
+
+    updateName (name) {
+      if (!this.ended) {
+        this.name = String(name)
+        try { this.otel.updateName(this.name) } catch (_) {}
+      }
+      return this
+    }
+
+    addEvent (name, attrsOrTime, time) {
+      if (!this.ended) {
+        try { this.otel.addEvent(String(name), attrsOrTime, time) } catch (_) {}
+      }
+      return this
+    }
+
+    addLink (spanContext, attributes) {
+      if (this.ended) return this
+      const l = attributes === undefined ? spanContext : { context: spanContext, attributes }
+      const ctx = l && (w3c.isSpanContext(l) ? l : l.context)
+      if (!w3c.isSpanContext(ctx)) return this
+      if (!this.links) this.links = []
+      if (this.links.length >= this.maxLinks) {
+        this.droppedLinks++
+        return this
+      }
+      this.links.push(l)
+      try {
+        if (typeof this.otel.addLink === 'function') this.otel.addLink(otelLink(l))
+      } catch (_) {}
+      return this
+    }
+
+    recordException (err) {
+      if (this.ended) return this
+      super.recordException(err)
+      try {
+        this.otel.recordException(err)
+        this.otel.setStatus({ code: 2, message: this.error || undefined })
+      } catch (_) {}
+      return this
+    }
+
+    setStatus (status, message) {
+      if (this.ended) return this
+      super.setStatus(status, message)
+      try {
+        if (this.status === 'ERROR') this.otel.setStatus({ code: 2, message: this.error || undefined })
+        else if (this.status === 'OK') this.otel.setStatus({ code: 1 })
+        else this.otel.setStatus({ code: 0 })
+      } catch (_) {}
+      return this
+    }
+
+    isRecording () {
+      try {
+        return !this.ended && this.otel.isRecording()
+      } catch (_) {
+        return !this.ended
+      }
+    }
+
+    end (endTime) {
+      if (this.ended) return
+      this.ended = true
+      try {
+        if (this.droppedLinks && typeof this.otel.setAttribute === 'function') {
+          this.otel.setAttribute('otel.dropped_links_count', this.droppedLinks)
+        }
+        this.otel.end(endTime)
+      } catch (err) {
+        debug('span end failed: %s', err && err.message)
+      }
+    }
+  }
+
+  return BridgeSpan
+}
+
+/** An app or OTel-instrumentation span seen as pmx's current span (parent of pmx spans). */
+class ForeignSpan {
+  constructor (otel) {
+    const sc = otel.spanContext()
+    this.otel = otel
+    this.foreign = true
+    this.traceId = sc.traceId
+    this.spanId = sc.spanId
+    this.sampled = (sc.traceFlags & 1) === 1
+    this.traceState = sc.traceState && typeof sc.traceState.serialize === 'function' ? sc.traceState.serialize() || null : null
+    this.bag = w3c.EMPTY_BAG
+    this.kind = kindOf(otel) || 'INTERNAL'
+    this.attributes = {}
+    this.ended = false
+    this._ctx = null
+  }
+
+  get context () {
+    if (!this._ctx) this._ctx = w3c.makeContext(this.traceId, this.spanId, this.sampled, this.traceState, this.bag, false)
+    return this._ctx
+  }
+
+  isRecording () {
+    try { return this.otel.isRecording() } catch (_) { return false }
+  }
+
+  spanContext () { return this.otel.spanContext() }
+  traceparent () { return `00-${this.traceId}-${this.spanId}-${this.sampled ? '01' : '00'}` }
+  setAttribute (k, v) { try { this.otel.setAttribute(k, otelValue(v)) } catch (_) {} return this }
+  setAttributes (o) { if (o) for (const k of Object.keys(o)) this.setAttribute(k, o[k]); return this }
+  updateName (n) { try { this.otel.updateName(String(n)) } catch (_) {} return this }
+  addEvent (n) { try { this.otel.addEvent(String(n)) } catch (_) {} return this }
+  addLink () { return this }
+  recordException (e) { try { this.otel.recordException(e) } catch (_) {} return this }
+  setStatus () { return this }
+  end () {} // not ours to end
+}
+
+function otelValue (v) {
+  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') return v
+  if (Array.isArray(v)) return v.map((x) => (typeof x === 'number' || typeof x === 'boolean' ? x : String(x)))
+  try {
+    return JSON.stringify(v)
+  } catch (_) {
+    return String(v)
+  }
+}
+
+function otelLink (l) {
+  const ctx = w3c.isSpanContext(l) ? l : l.context
+  const out = { context: { traceId: ctx.traceId, spanId: ctx.spanId, traceFlags: ctx.sampled ? 1 : 0, isRemote: true } }
+  if (l.attributes) {
+    out.attributes = {}
+    for (const k of Object.keys(l.attributes)) out.attributes[k] = otelValue(l.attributes[k])
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------------------------
+// the bridge
+
+class Bridge {
+  /**
+   * @param {object} tracer the native Tracer (lib/tracing/tracer.js)
+   * @param {object} provider the app's tracer provider (detect())
+   * @param {object} env { report(obj), tracing (pmx tracing enabled), standalone, prodmanUrl, debugOut }
+   */
+  constructor (tracer, provider, env) {
+    const { Span } = require('../tracing/tracer')
+    this.BridgeSpan = makeSpanClasses(Span)
+    this.tracer = tracer
+    this.provider = provider
+    this.env = env || {}
+    this.g = globalThis[API_KEY]
+    this.otelTracer = provider.getTracer('@pmx/io', VERSION)
+    this.byOtel = new WeakMap() // otel span → BridgeSpan
+    this.foreign = new WeakMap() // otel span → ForeignSpan
+    this.suppressed = new Set()
+    this.exportPath = 'none'
+    this.processor = null
+    this.sdk = sdkVersion(provider)
+    this.disabledMarkerCheck = process.env.PMX_IO_TEST_OTEL_NO_MARKER === '1'
+    this.enterWarned = false
+  }
+
+  // -- context ----------------------------------------------------------------------------------
+
+  cm () {
+    const g = this.g
+    return g && g.context && typeof g.context.active === 'function' ? g.context : null
+  }
+
+  active () {
+    const cm = this.cm()
+    try {
+      return cm ? cm.active() : ROOT
+    } catch (_) {
+      return ROOT
+    }
+  }
+
+  activeOtelSpan () {
+    const ctx = this.active()
+    return ctx && typeof ctx.getValue === 'function' ? ctx.getValue(SPAN_KEY) : undefined
+  }
+
+  /** The OTel span standing for a pmx span (BridgeSpan, ForeignSpan, native Span). */
+  otelOf (span) {
+    if (!span) return undefined
+    if (span.otel) return span.otel
+    if (typeof span.traceId === 'string' && typeof span.spanId === 'string') {
+      return parentSpan(span.traceId, span.spanId, span.sampled, span.traceState, false)
+    }
+    return undefined
+  }
+
+  ctxWith (span, base) {
+    const o = this.otelOf(span)
+    base = base || this.active()
+    return o ? base.setValue(SPAN_KEY, o) : base
+  }
+
+  /** context.js: the store pmx code sees as current (OTX-011). */
+  current (store) {
+    const o = this.activeOtelSpan()
+    if (!o) return store
+    if (store && store.span && store.span.otel === o) return store
+    let span = this.byOtel.get(o)
+    if (!span) {
+      span = this.foreign.get(o)
+      if (!span) {
+        try {
+          span = new ForeignSpan(o)
+        } catch (_) {
+          return store
+        }
+        this.foreign.set(o, span)
+      }
+    }
+    return { span, bag: store ? store.bag : w3c.EMPTY_BAG, server: store && store.server }
+  }
+
+  /** context.js run(): fn runs with the store and, in OTel, with its span active. */
+  run (als, store, fn, thisArg, args) {
+    const cm = this.cm()
+    const span = store && store.span
+    if (!cm || !span) return als.run(store, () => fn.apply(thisArg, args || []))
+    const ctx = this.ctxWith(span)
+    return als.run(store, () => cm.with(ctx, () => fn.apply(thisArg, args || [])))
+  }
+
+  /** context.js enter(): also enter the OTel context (AsyncLocalStorageContextManager). */
+  enter (store) {
+    const cm = this.cm()
+    const als = cm && cm._asyncLocalStorage
+    if (!als || typeof als.enterWith !== 'function') {
+      // another context manager (or a future SDK without the private field): pmx's own context
+      // still holds the span, but OTel spans the app starts there do not see it as their parent
+      if (!this.enterWarned) {
+        this.enterWarned = true
+        debug('OpenTelemetry context manager without _asyncLocalStorage: inbound requests and iterator spans are not mirrored into the app SDK context')
+      }
+      return
+    }
+    try {
+      const span = store && store.span
+      als.enterWith(span ? this.ctxWith(span) : this.active().deleteValue(SPAN_KEY))
+    } catch (_) {}
+  }
+
+  /** context.js bind(): fn runs in the OTel context current at bind time as well. */
+  bind (fn) {
+    const cm = this.cm()
+    if (!cm || typeof cm.bind !== 'function') return fn
+    try {
+      return cm.bind(this.active(), fn)
+    } catch (_) {
+      return fn
+    }
+  }
+
+  // -- spans ------------------------------------------------------------------------------------
+
+  /** OTX-021: the active span blocks a pmx span of this kind, else null; records the library. */
+  guard (kind) {
+    if (kind !== 'SERVER' && kind !== 'CLIENT' && kind !== 'PRODUCER') return false
+    const o = this.activeOtelSpan()
+    if (!o || this.byOtel.has(o)) return false
+    let recording = false
+    try {
+      recording = o.isRecording()
+    } catch (_) {}
+    if (!recording || kindOf(o) !== kind) return false
+    const scope = scopeOf(o)
+    if (scope === '@pmx/io') return false
+    this.suppress(libName(scope))
+    return true
+  }
+
+  suppress (lib) {
+    if (this.suppressed.has(lib)) return
+    this.suppressed.add(lib)
+    this.report()
+  }
+
+  /** Create a BridgeSpan under the OTel context `ctx`. */
+  make (name, kind, ctx, attributes, links, startUs, bag) {
+    if (this.tracer._onStart) {
+      try { this.tracer._onStart() } catch (_) {}
+    }
+    const opts = { kind: OTEL_KIND[kind] || 0 }
+    if (attributes) {
+      opts.attributes = {}
+      for (const k of Object.keys(attributes)) {
+        const v = attributes[k]
+        if (v !== undefined && v !== null) opts.attributes[k] = otelValue(v)
+      }
+    }
+    if (links && links.length) opts.links = links.map(otelLink)
+    if (startUs !== undefined) opts.startTime = startUs / 1000
+    const o = this.otelTracer.startSpan(String(name), opts, ctx)
+    const parent = ctx && ctx.getValue(SPAN_KEY)
+    let parentId = null
+    try {
+      if (parent) parentId = parent.spanContext().spanId
+    } catch (_) {}
+    const span = new this.BridgeSpan(this.tracer, o, String(name), kind, parentId, attributes, bag)
+    if (links && links.length) span.links = links.slice(0, span.maxLinks)
+    this.byOtel.set(o, span)
+    return span
+  }
+
+  /** Tracer.startSpan in bridge mode (parent: undefined | Span | ForeignSpan | SpanContext | NEW_TRACE). */
+  startSpan (name, kind, o, store) {
+    const parent = o.parent
+    let ctx
+    let bag = store ? store.bag : undefined
+    if (parent === undefined) {
+      ctx = this.active()
+      if (store && store.span && !ctx.getValue(SPAN_KEY)) ctx = this.ctxWith(store.span, ctx)
+    } else if (parent === w3c.NEW_TRACE) {
+      ctx = this.active().deleteValue(SPAN_KEY)
+    } else if (w3c.isSpanContext(parent)) {
+      ctx = this.active().setValue(SPAN_KEY, parentSpan(parent.traceId, parent.spanId, parent.sampled, parent.traceState, parent.isRemote))
+      bag = w3c.contextBag(parent)
+    } else {
+      ctx = this.ctxWith(parent)
+      bag = parent.bag
+    }
+    const links = Array.isArray(o.links) ? o.links.map(linkOf).filter(Boolean) : null
+    return this.make(name, kind, ctx, o.attributes, links, o.startUs, bag)
+  }
+
+  child (parent, name, kind, attributes) {
+    if (this.guard(kind)) return null
+    return this.make(name, kind, this.ctxWith(parent), attributes, null, undefined, parent && parent.bag)
+  }
+
+  /** Inbound HTTP (NIO-220) through the app's propagator (OTX-012) and the runtime guard. */
+  serverSpan (name, tags, headers) {
+    if (this.guard('SERVER')) return null
+    // OTX-020: OpenTelemetry's http instrumentation wraps Server.prototype.emit (shimmer
+    // `__wrapped`). On Node ≥ 20 pmx sees the request through the `http.server.request.start`
+    // channel, published before that wrapper runs, so its span is not active yet: the marker decides.
+    if (!this.disabledMarkerCheck && this.httpCovered()) {
+      this.suppress('http')
+      return null
+    }
+    let ctx = this.active().deleteValue(SPAN_KEY)
+    const prop = this.g && this.g.propagation
+    if (prop && typeof prop.extract === 'function' && headers) {
+      try {
+        ctx = prop.extract(ctx, headers, GETTER)
+      } catch (_) {}
+    } else if (headers) {
+      const sc = w3c.extract(headers)
+      if (sc) ctx = ctx.setValue(SPAN_KEY, parentSpan(sc.traceId, sc.spanId, sc.sampled, sc.traceState, true))
+    }
+    return this.make(name, 'SERVER', ctx, tags, null, undefined, undefined)
+  }
+
+  httpCovered () {
+    try {
+      const e = require('http').Server.prototype.emit
+      return Boolean(e && e.__wrapped === true)
+    } catch (_) {
+      return false
+    }
+  }
+
+  /** [[name, value]] trace headers for `span` through the app's propagator (OTX-012). */
+  headersFor (span) {
+    const prop = this.g && this.g.propagation
+    if (!prop || typeof prop.inject !== 'function') return null
+    const carrier = {}
+    try {
+      prop.inject(this.ctxWith(span), carrier, SETTER)
+    } catch (_) {
+      return null
+    }
+    return Object.keys(carrier).map((k) => [k, String(carrier[k])])
+  }
+
+  /** io.inject (NIO-241) through the propagator; false when there is none (native rules apply). */
+  inject (carrier, span) {
+    const pairs = this.headersFor(span)
+    if (!pairs) return false
+    w3c.writeHeaders(carrier, pairs, false, false)
+    return true
+  }
+
+  /** io.extract (NIO-242) through the propagator: a pmx SpanContext, or undefined (none). */
+  extract (carrier) {
+    const prop = this.g && this.g.propagation
+    if (!prop || typeof prop.extract !== 'function') return undefined
+    try {
+      const ctx = prop.extract(ROOT, carrier, GETTER)
+      const o = ctx && ctx.getValue(SPAN_KEY)
+      if (!o) return null
+      const sc = o.spanContext()
+      return w3c.makeContext(sc.traceId, sc.spanId, (sc.traceFlags & 1) === 1,
+        sc.traceState && typeof sc.traceState.serialize === 'function' ? sc.traceState.serialize() || null : null,
+        w3c.contextBag(w3c.extract(carrier)), true)
+    } catch (_) {
+      return null
+    }
+  }
+
+  /** OTX-020 for fetch: OTel's undici instrumentation subscribes to the same channel. */
+  undiciCovered () {
+    try {
+      const ch = require('diagnostics_channel').channel('undici:request:create')
+      const subs = ch._subscribers
+      if (Array.isArray(subs) && subs.length > 1) {
+        this.suppress('undici')
+        return true
+      }
+    } catch (_) {}
+    return false
+  }
+
+  // -- export (OTX-030…036) ---------------------------------------------------------------------
+
+  setting () {
+    const v = String(process.env.PMX_OTEL_BRIDGE || this.env.bridge || 'auto').toLowerCase()
+    return ['auto', 'receiver', 'processor', 'off'].includes(v) ? v : 'auto'
+  }
+
+  /** OTX-031 / OTX-051: does the app SDK's own exporter reach prodman (directly or via the receiver)? */
+  receiverInUse () {
+    const env = process.env
+    const ep = env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT || env.OTEL_EXPORTER_OTLP_ENDPOINT || ''
+    const exp = env.OTEL_TRACES_EXPORTER
+    const otlp = !exp || exp.split(',').map((s) => s.trim()).includes('otlp')
+    if (!otlp || !ep) return false
+    if (env.PMX_OTLP_ENDPOINT && ep.startsWith(env.PMX_OTLP_ENDPOINT)) return true
+    let prodman = this.env.prodmanUrl
+    if (env.PMX_IO_STANDALONE === '1' || prodman) {
+      try {
+        prodman = require('../standalone/transport').resolveUrl(prodman, env)
+      } catch (_) {}
+    }
+    if (prodman && ep.startsWith(prodman.replace(/\/+$/, '') + '/otlp')) return true
+    return false
+  }
+
+  start () {
+    const setting = this.setting()
+    if (setting === 'receiver' || (setting !== 'processor' && this.receiverInUse())) {
+      this.exportPath = 'receiver'
+    } else if ((setting === 'processor' || setting === 'auto') && this.env.tracing !== false) {
+      this.exportPath = this.attachProcessor() ? 'processor' : 'none'
+    } else {
+      this.exportPath = 'none'
+    }
+    const t = this.tracer
+    const ignored = []
+    if (t.opts.sampleRatio !== undefined) ignored.push('sampleRatio')
+    if (t.opts.minDurationUs !== undefined) ignored.push('minDurationUs')
+    if (t.opts.maxSpansPerSecond !== undefined && this.exportPath !== 'processor') ignored.push('maxSpansPerSecond')
+    if (t.opts.exportUnsampledErrors !== undefined) ignored.push('exportUnsampledErrors')
+    if (ignored.length) debug('OpenTelemetry SDK decides sampling: ignoring %s', ignored.join(', '))
+    const line = `[@pmx/io] OpenTelemetry SDK detected (${this.sdk}): pmx spans are created through it; export: ${this.exportPath}`
+    debug(line)
+    if (this.env.debugOut) {
+      try { this.env.debugOut(line) } catch (_) {}
+    }
+    this.report()
+  }
+
+  report () {
+    if (typeof this.env.report !== 'function') return
+    try {
+      this.env.report({ otel: { sdk: this.sdk, mode: 'bridge', export: this.exportPath, suppressed: Array.from(this.suppressed).sort() } })
+    } catch (_) {}
+  }
+
+  /** OTX-032: add the processor to SDK 1.x (addSpanProcessor) or 2.x (the active processor's list). */
+  attachProcessor () {
+    const p = this.provider
+    const proc = new Processor(this)
+    try {
+      if (process.env.PMX_IO_TEST_OTEL_NO_PRIVATE === '1') throw new Error('test hook: no private fields')
+      if (typeof p.addSpanProcessor === 'function') {
+        p.addSpanProcessor(proc)
+      } else if (p._activeSpanProcessor && Array.isArray(p._activeSpanProcessor._spanProcessors)) {
+        p._activeSpanProcessor._spanProcessors.push(proc)
+      } else {
+        throw new Error('no span processor list')
+      }
+    } catch (err) {
+      debug('cannot attach to this OpenTelemetry SDK; set OTEL_EXPORTER_OTLP_ENDPOINT to $PMX_OTLP_ENDPOINT to reach prodman (%s)', err && err.message)
+      return false
+    }
+    this.processor = proc
+    return true
+  }
+
+  /** The processor failed (OTX-019 isolation): stop using it. */
+  processorFailed (err) {
+    if (this.exportPath !== 'processor') return
+    debug('OpenTelemetry span processor disabled: %s', err && err.message)
+    this.exportPath = 'none'
+    if (this.processor) this.processor.disabled = true
+    this.report()
+  }
+}
+
+function linkOf (el) {
+  if (w3c.isSpanContext(el)) return { context: el }
+  if (el && typeof el === 'object' && w3c.isSpanContext(el.context)) return { context: el.context, attributes: el.attributes }
+  if (el && typeof el.traceId === 'string' && typeof el.spanId === 'string' && el.context) return { context: el.context }
+  return null
+}
+
+function sdkVersion (provider) {
+  try {
+    const res = provider.resource || provider._resource || (provider._config && provider._config.resource) ||
+      (provider._tracers && provider._tracers.size && Array.from(provider._tracers.values())[0]._resource)
+    const attrs = res && res.attributes
+    const v = attrs && attrs['telemetry.sdk.version']
+    return 'nodejs ' + (typeof v === 'string' ? v : 'unknown')
+  } catch (_) {
+    return 'nodejs unknown'
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// processor path (OTX-032/034)
+
+function hrToUs (t) {
+  if (Array.isArray(t)) return t[0] * 1e6 + Math.round(t[1] / 1000)
+  if (typeof t === 'number') return Math.round(t * 1000)
+  if (t instanceof Date) return t.getTime() * 1000
+  return 0
+}
+
+class Processor {
+  constructor (bridge) {
+    this.bridge = bridge
+    this.disabled = false
+  }
+
+  onStart () {}
+  onEnding () {}
+
+  onEnd (span) {
+    if (this.disabled) return
+    try {
+      if (process.env.PMX_IO_TEST_OTEL_THROW === '1') throw new Error('test hook: onEnd throws')
+      const sc = span.spanContext()
+      if ((sc.traceFlags & 1) !== 1) return
+      this.bridge.tracer.exportConverted(toZipkin(span, this.bridge.tracer))
+    } catch (err) {
+      this.bridge.processorFailed(err)
+    }
+  }
+
+  forceFlush () {
+    try {
+      this.bridge.tracer.flush()
+    } catch (_) {}
+    return Promise.resolve()
+  }
+
+  shutdown () {
+    return this.forceFlush()
+  }
+}
+
+/** OTX-034: a finished OTel span in the native Zipkin v2 shape (40 §7.11). */
+function toZipkin (span, tracer) {
+  const { tagValue, encodeLinks } = require('../tracing/tracer')
+  const sc = span.spanContext()
+  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'] : '')
+  }
+  const status = span.status || {}
+  if (status.code === 1) tags['otel.status_code'] = 'OK'
+  else if (status.code === 2) {
+    tags['otel.status_code'] = 'ERROR'
+    tags.error = status.message || 'Error'
+  }
+  if (span.droppedAttributesCount) tags['otel.dropped_attributes_count'] = String(span.droppedAttributesCount)
+  if (span.droppedEventsCount) tags['otel.dropped_events_count'] = String(span.droppedEventsCount)
+  const links = (span.links || []).map((l) => ({
+    context: { traceId: l.context.traceId, spanId: l.context.spanId },
+    attributes: l.attributes && Object.keys(l.attributes).length ? l.attributes : undefined
+  }))
+  const enc = encodeLinks(links.slice(0, 128), Math.max(0, links.length - 128) + (span.droppedLinksCount || 0))
+  if (enc.value !== undefined) tags['pmx.links'] = enc.value
+  if (enc.dropped) tags['otel.dropped_links_count'] = String(enc.dropped)
+  const scope = span.instrumentationScope || span.instrumentationLibrary
+  if (scope && scope.name) tags['otel.scope.name'] = scope.name
+  if (scope && scope.version) tags['otel.scope.version'] = scope.version
+  const res = span.resource && span.resource.attributes ? span.resource.attributes : {}
+  for (const k of Object.keys(res)) {
+    if (tags[k] === undefined && res[k] !== undefined && res[k] !== null) tags[k] = tagValue(res[k])
+  }
+  tags['pmx.bridge'] = 'processor'
+  const out = { traceId: sc.traceId, id: sc.spanId }
+  const parentId = span.parentSpanId || (span.parentSpanContext && span.parentSpanContext.spanId)
+  if (parentId) out.parentId = parentId
+  out.name = span.name
+  const kind = KINDS[span.kind]
+  if (kind && kind !== 'INTERNAL') out.kind = kind
+  out.timestamp = hrToUs(span.startTime)
+  out.duration = Math.max(0, span.duration ? hrToUs(span.duration) : hrToUs(span.endTime) - out.timestamp)
+  out.localEndpoint = { serviceName: typeof res['service.name'] === 'string' ? res['service.name'] : tracer.serviceName }
+  out.tags = tags
+  if (span.events && span.events.length) out.annotations = span.events.map((e) => ({ timestamp: hrToUs(e.time), value: e.name }))
+  return out
+}
+
+module.exports = { detect, Bridge, toZipkin, ForeignSpan, API_KEY, SPAN_KEY, ROOT, BaseContext }