@open-mercato/telemetry 0.6.8-develop.6993.1.3fc50f3409 → 0.6.8-develop.7000.1.0ae682bad1

package/AGENTS.md

@@ -17,6 +17,14 @@ off by default. Spec:
   provider activates only after an explicit bootstrap registers the exact
   configured name and calls `initTelemetry()`.
 - Name spans `module.entity.action` (lowercase, dot-separated).
+- Root the repeating unit of a long-lived job (batch/page) with
+  `withSpan(name, fn, { root: true, links: [runCarrier] })`. Without it the whole
+  job inherits one sampling decision from its trigger — a blind spot below ratio
+  1.0, an unrenderable trace at 1.0. Always pair `root` with `links` so the chain
+  back to the trigger survives.
+- Emit spans from packages that must not depend on this one via
+  `withTelemetrySpan` / `captureTelemetryTrace` from
+  `@open-mercato/shared/lib/telemetry/runtime`, never a direct import.
 - Use semantic-convention metric/attribute names when available.
 - Keep metric labels low-cardinality. Tenant, organization, and user IDs belong
   on span attributes, never metric labels.

package/README.md

@@ -125,7 +125,7 @@ bridge, so the package is not loaded on the disabled path.
 
 | Export | Description |
 | --- | --- |
-| `withSpan(name, fn, opts?)` | Run `fn` in a provider-owned span |
+| `withSpan(name, fn, opts?)` | Run `fn` in a provider-owned span. `opts.root` starts a new trace; `opts.links` attaches causal links (see [Long-lived jobs](#long-lived-jobs-root-spans)) |
 | `currentSpan()` / `setAttributes(attrs)` | Active span access |
 | `counter` / `histogram` / `gauge` | Metric helpers |
 | `reportError(err, ctx?)` | Span exception + shared error log + `om.errors` |
@@ -138,6 +138,64 @@ bridge, so the package is not loaded on the disabled path.
 `@open-mercato/telemetry/nextjs-config` separately exports only
 `telemetryServerExternalPackages` for build configuration.
 
+### Long-lived jobs: root spans
+
+Trace context propagates from the request that triggered a job through the queue
+into the worker, and `ParentBasedSampler` only decides sampling at a trace's
+**root**. A job that runs for hours therefore inherits one decision made on a
+request from long before it: below `TELEMETRY_SAMPLING_RATIO=1.0` an entire run
+can emit nothing at all, and at `1.0` the run becomes one unrenderable trace.
+
+Give the unit of work you actually analyse — a batch, a page — its own trace, and
+link it back so the causal chain survives:
+
+```ts
+import { withSpan, captureTraceContext } from '@open-mercato/telemetry'
+
+const runTrace = captureTraceContext() // the triggering job's trace
+
+for (const batch of batches) {
+  await withSpan('import.batch', async (span) => {
+    span.setAttributes({ 'import.batch_index': batch.index })
+    await processBatch(batch)
+  }, { root: true, links: [runTrace] })
+}
+```
+
+Each batch now samples independently and each trace stays small enough to render.
+Sampling stays probabilistic: at ratio `p` a run of `n` batches still emits
+nothing with probability `(1 - p)^n` — at `p = 0.25` that is 75% for one batch,
+32% for four, 0.3% for twenty. Rooting shrinks the blind spot fast as a run gets
+longer; it does not promise a signal from every run. Only ratio `1.0` does that,
+and rooting is what makes `1.0` renderable.
+
+`links` takes W3C **carriers**, so it accepts both `captureTraceContext()` and a
+carrier received from another process; empty or malformed carriers are dropped
+rather than emitted as invalid links.
+
+### Emitting spans without depending on this package
+
+Packages that must not take a dependency on `@open-mercato/telemetry` use the
+shared runtime bridge instead. With telemetry off, `withTelemetrySpan` is `fn`
+plus one global lookup — no span is allocated and the OTEL SDK is never reached.
+
+```ts
+import {
+  withTelemetrySpan,
+  captureTelemetryTrace,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+
+const runTrace = captureTelemetryTrace() // undefined when telemetry is off
+
+await withTelemetrySpan('data_sync.import.batch', async (span) => {
+  span.setAttributes({ 'data_sync.batch_index': index })
+  await processBatch()
+}, { root: true, links: runTrace ? [runTrace] : undefined })
+```
+
+`packages/core/src/modules/data_sync/lib/batch-stream.ts` is the reference
+consumer.
+
 ## Security and privacy
 
 - Explicit off is absolute: custom providers cannot override an unset/noop

package/dist/init.js

@@ -11,6 +11,7 @@ import {
 import { createLogger } from "@open-mercato/shared/lib/logger";
 import { registerTelemetryLogger } from "./facade/logger-bridge.js";
 import { captureTraceContext, continueTrace } from "./facade/propagation.js";
+import { withSpan } from "./facade/tracer.js";
 import { recordHttpDuration } from "./facade/http.js";
 import { reportError } from "./facade/report-error.js";
 let initialized = false;
@@ -77,6 +78,7 @@ function createRuntime(provider) {
     canUseGlobalTracePropagation: () => isOtlpBackend(provider.name) && readTelemetryEnv().trustInboundTrace,
     captureTraceContext,
     continueTrace: (carrier, name, fn, options) => continueTrace(carrier, name, () => fn(), options),
+    withSpan: (name, fn, options) => withSpan(name, fn, options),
     recordHttpDuration,
     reportError,
     shutdown: shutdownTelemetry

package/dist/init.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/init.ts"],
-  "sourcesContent": ["import type { TelemetryBackendName, TelemetryProvider } from './types'\nimport { isOtlpBackend, readTelemetryEnv, resetTelemetryEnvCache } from './env'\nimport { ConsoleProvider } from './provider/console-provider'\nimport {\n  getRegisteredProvider,\n  clearActiveProvider,\n  setActiveProvider,\n} from './provider/registry'\nimport {\n  registerTelemetryRuntime,\n  type TelemetryRuntime,\n} from '@open-mercato/shared/lib/telemetry/runtime'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { registerTelemetryLogger } from './facade/logger-bridge'\nimport { captureTraceContext, continueTrace } from './facade/propagation'\nimport { recordHttpDuration } from './facade/http'\nimport { reportError } from './facade/report-error'\n\nlet initialized = false\nlet activeProvider: TelemetryProvider | undefined\nlet disposeLoggerExtension: (() => void) | undefined\nlet disposeRuntime: (() => void) | undefined\n\nconst logger = createLogger('telemetry')\n\n/**\n * One-shot bootstrap, invoked from `apps/mercato/instrumentation.ts` (web) and,\n * for cross-boundary propagation, from the queue/worker bootstrap. Resolves the\n * backend from `TELEMETRY_BACKEND`, starts it, and installs it as the active\n * provider. Idempotent and safe to call when telemetry is off (defaults to\n * no-op).\n */\nexport async function initTelemetry(): Promise<void> {\n  if (initialized) return\n\n  // Drop any env snapshot memoized BEFORE the host loaded its `.env` (the CLI\n  // binary imports this package before dotenv runs) so init resolves the backend\n  // from the actual, fully-loaded environment.\n  resetTelemetryEnvCache()\n  const env = readTelemetryEnv()\n  const configuredBackend = process.env.TELEMETRY_BACKEND?.trim().toLowerCase() ?? ''\n  const registeredProvider = configuredBackend && configuredBackend !== 'noop'\n    ? getRegisteredProvider(configuredBackend)\n    : undefined\n  // Explicit off is absolute: do not resolve providers, register hooks, or\n  // install process-wide bridges when the backend is unset/noop/unregistered.\n  if (!env.enabled && !registeredProvider) return\n\n  const provider = registeredProvider ?? await resolveProvider(env.backend)\n  if (!provider) {\n    logger.warn('Telemetry backend is unsupported; telemetry remains disabled', {\n      backend: configuredBackend || env.backend,\n    })\n    return\n  }\n\n  // Only flag initialized AFTER start() succeeds \u2014 a throw here must leave\n  // telemetry re-initializable, not stuck flagged-on with an unstarted provider.\n  await provider.start()\n  setActiveProvider(provider)\n  activeProvider = provider\n  disposeLoggerExtension = registerTelemetryLogger(provider)\n  disposeRuntime = registerTelemetryRuntime(createRuntime(provider))\n  initialized = true\n\n  logger.info('Telemetry initialized', {\n    backend: provider.name,\n    samplingRatio: env.samplingRatio,\n  })\n}\n\nasync function resolveProvider(backend: TelemetryBackendName): Promise<TelemetryProvider | undefined> {\n  const registered = getRegisteredProvider(backend)\n  if (registered) return registered\n\n  if (backend === 'console') return new ConsoleProvider()\n  // signoz | newrelic | otlp \u2014 same OTLP provider, vendor differs only by endpoint.\n  if (isOtlpBackend(backend)) return await loadOtlpProvider(backend)\n  return undefined\n}\n\n/**\n * Dynamically load the OTLP provider so `@opentelemetry/*` (optionalDependencies)\n * is imported only when an OTLP backend is selected. Falls back to console if\n * the OTEL packages are absent rather than crashing the app.\n */\nasync function loadOtlpProvider(backend: TelemetryBackendName): Promise<TelemetryProvider> {\n  try {\n    const mod = await import('./provider/otlp-provider')\n    return new mod.OtlpProvider({}, backend)\n  } catch (err) {\n    logger.warn('OTLP provider unavailable; falling back to console', {\n      reason: err instanceof Error ? err.message : String(err),\n    })\n    return new ConsoleProvider()\n  }\n}\n\n/** Flush + tear down the active backend (shutdown hook / `after()`). */\nexport async function shutdownTelemetry(): Promise<void> {\n  const provider = activeProvider\n  activeProvider = undefined\n  initialized = false\n  disposeLoggerExtension?.()\n  disposeLoggerExtension = undefined\n  disposeRuntime?.()\n  disposeRuntime = undefined\n  clearActiveProvider()\n  if (provider) await provider.shutdown()\n}\n\nfunction createRuntime(provider: TelemetryProvider): TelemetryRuntime {\n  return {\n    canUseGlobalTracePropagation: () =>\n      isOtlpBackend(provider.name as TelemetryBackendName)\n      && readTelemetryEnv().trustInboundTrace,\n    captureTraceContext,\n    continueTrace: (carrier, name, fn, options) =>\n      continueTrace(carrier, name, () => fn(), options),\n    recordHttpDuration,\n    reportError,\n    shutdown: shutdownTelemetry,\n  }\n}\n\n/** Test-only: allow re-init in jest. */\nexport function resetTelemetryInit(): void {\n  initialized = false\n  activeProvider = undefined\n  disposeLoggerExtension?.()\n  disposeLoggerExtension = undefined\n  disposeRuntime?.()\n  disposeRuntime = undefined\n}\n"],
-  "mappings": "AACA,SAAS,eAAe,kBAAkB,8BAA8B;AACxE,SAAS,uBAAuB;AAChC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,OAEK;AACP,SAAS,oBAAoB;AAC7B,SAAS,+BAA+B;AACxC,SAAS,qBAAqB,qBAAqB;AACnD,SAAS,0BAA0B;AACnC,SAAS,mBAAmB;AAE5B,IAAI,cAAc;AAClB,IAAI;AACJ,IAAI;AACJ,IAAI;AAEJ,MAAM,SAAS,aAAa,WAAW;AASvC,eAAsB,gBAA+B;AACnD,MAAI,YAAa;AAKjB,yBAAuB;AACvB,QAAM,MAAM,iBAAiB;AAC7B,QAAM,oBAAoB,QAAQ,IAAI,mBAAmB,KAAK,EAAE,YAAY,KAAK;AACjF,QAAM,qBAAqB,qBAAqB,sBAAsB,SAClE,sBAAsB,iBAAiB,IACvC;AAGJ,MAAI,CAAC,IAAI,WAAW,CAAC,mBAAoB;AAEzC,QAAM,WAAW,sBAAsB,MAAM,gBAAgB,IAAI,OAAO;AACxE,MAAI,CAAC,UAAU;AACb,WAAO,KAAK,gEAAgE;AAAA,MAC1E,SAAS,qBAAqB,IAAI;AAAA,IACpC,CAAC;AACD;AAAA,EACF;AAIA,QAAM,SAAS,MAAM;AACrB,oBAAkB,QAAQ;AAC1B,mBAAiB;AACjB,2BAAyB,wBAAwB,QAAQ;AACzD,mBAAiB,yBAAyB,cAAc,QAAQ,CAAC;AACjE,gBAAc;AAEd,SAAO,KAAK,yBAAyB;AAAA,IACnC,SAAS,SAAS;AAAA,IAClB,eAAe,IAAI;AAAA,EACrB,CAAC;AACH;AAEA,eAAe,gBAAgB,SAAuE;AACpG,QAAM,aAAa,sBAAsB,OAAO;AAChD,MAAI,WAAY,QAAO;AAEvB,MAAI,YAAY,UAAW,QAAO,IAAI,gBAAgB;AAEtD,MAAI,cAAc,OAAO,EAAG,QAAO,MAAM,iBAAiB,OAAO;AACjE,SAAO;AACT;AAOA,eAAe,iBAAiB,SAA2D;AACzF,MAAI;AACF,UAAM,MAAM,MAAM,OAAO,0BAA0B;AACnD,WAAO,IAAI,IAAI,aAAa,CAAC,GAAG,OAAO;AAAA,EACzC,SAAS,KAAK;AACZ,WAAO,KAAK,sDAAsD;AAAA,MAChE,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IACzD,CAAC;AACD,WAAO,IAAI,gBAAgB;AAAA,EAC7B;AACF;AAGA,eAAsB,oBAAmC;AACvD,QAAM,WAAW;AACjB,mBAAiB;AACjB,gBAAc;AACd,2BAAyB;AACzB,2BAAyB;AACzB,mBAAiB;AACjB,mBAAiB;AACjB,sBAAoB;AACpB,MAAI,SAAU,OAAM,SAAS,SAAS;AACxC;AAEA,SAAS,cAAc,UAA+C;AACpE,SAAO;AAAA,IACL,8BAA8B,MAC5B,cAAc,SAAS,IAA4B,KAChD,iBAAiB,EAAE;AAAA,IACxB;AAAA,IACA,eAAe,CAAC,SAAS,MAAM,IAAI,YACjC,cAAc,SAAS,MAAM,MAAM,GAAG,GAAG,OAAO;AAAA,IAClD;AAAA,IACA;AAAA,IACA,UAAU;AAAA,EACZ;AACF;AAGO,SAAS,qBAA2B;AACzC,gBAAc;AACd,mBAAiB;AACjB,2BAAyB;AACzB,2BAAyB;AACzB,mBAAiB;AACjB,mBAAiB;AACnB;",
+  "sourcesContent": ["import type { TelemetryBackendName, TelemetryProvider } from './types'\nimport { isOtlpBackend, readTelemetryEnv, resetTelemetryEnvCache } from './env'\nimport { ConsoleProvider } from './provider/console-provider'\nimport {\n  getRegisteredProvider,\n  clearActiveProvider,\n  setActiveProvider,\n} from './provider/registry'\nimport {\n  registerTelemetryRuntime,\n  type TelemetryRuntime,\n} from '@open-mercato/shared/lib/telemetry/runtime'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { registerTelemetryLogger } from './facade/logger-bridge'\nimport { captureTraceContext, continueTrace } from './facade/propagation'\nimport { withSpan } from './facade/tracer'\nimport { recordHttpDuration } from './facade/http'\nimport { reportError } from './facade/report-error'\n\nlet initialized = false\nlet activeProvider: TelemetryProvider | undefined\nlet disposeLoggerExtension: (() => void) | undefined\nlet disposeRuntime: (() => void) | undefined\n\nconst logger = createLogger('telemetry')\n\n/**\n * One-shot bootstrap, invoked from `apps/mercato/instrumentation.ts` (web) and,\n * for cross-boundary propagation, from the queue/worker bootstrap. Resolves the\n * backend from `TELEMETRY_BACKEND`, starts it, and installs it as the active\n * provider. Idempotent and safe to call when telemetry is off (defaults to\n * no-op).\n */\nexport async function initTelemetry(): Promise<void> {\n  if (initialized) return\n\n  // Drop any env snapshot memoized BEFORE the host loaded its `.env` (the CLI\n  // binary imports this package before dotenv runs) so init resolves the backend\n  // from the actual, fully-loaded environment.\n  resetTelemetryEnvCache()\n  const env = readTelemetryEnv()\n  const configuredBackend = process.env.TELEMETRY_BACKEND?.trim().toLowerCase() ?? ''\n  const registeredProvider = configuredBackend && configuredBackend !== 'noop'\n    ? getRegisteredProvider(configuredBackend)\n    : undefined\n  // Explicit off is absolute: do not resolve providers, register hooks, or\n  // install process-wide bridges when the backend is unset/noop/unregistered.\n  if (!env.enabled && !registeredProvider) return\n\n  const provider = registeredProvider ?? await resolveProvider(env.backend)\n  if (!provider) {\n    logger.warn('Telemetry backend is unsupported; telemetry remains disabled', {\n      backend: configuredBackend || env.backend,\n    })\n    return\n  }\n\n  // Only flag initialized AFTER start() succeeds \u2014 a throw here must leave\n  // telemetry re-initializable, not stuck flagged-on with an unstarted provider.\n  await provider.start()\n  setActiveProvider(provider)\n  activeProvider = provider\n  disposeLoggerExtension = registerTelemetryLogger(provider)\n  disposeRuntime = registerTelemetryRuntime(createRuntime(provider))\n  initialized = true\n\n  logger.info('Telemetry initialized', {\n    backend: provider.name,\n    samplingRatio: env.samplingRatio,\n  })\n}\n\nasync function resolveProvider(backend: TelemetryBackendName): Promise<TelemetryProvider | undefined> {\n  const registered = getRegisteredProvider(backend)\n  if (registered) return registered\n\n  if (backend === 'console') return new ConsoleProvider()\n  // signoz | newrelic | otlp \u2014 same OTLP provider, vendor differs only by endpoint.\n  if (isOtlpBackend(backend)) return await loadOtlpProvider(backend)\n  return undefined\n}\n\n/**\n * Dynamically load the OTLP provider so `@opentelemetry/*` (optionalDependencies)\n * is imported only when an OTLP backend is selected. Falls back to console if\n * the OTEL packages are absent rather than crashing the app.\n */\nasync function loadOtlpProvider(backend: TelemetryBackendName): Promise<TelemetryProvider> {\n  try {\n    const mod = await import('./provider/otlp-provider')\n    return new mod.OtlpProvider({}, backend)\n  } catch (err) {\n    logger.warn('OTLP provider unavailable; falling back to console', {\n      reason: err instanceof Error ? err.message : String(err),\n    })\n    return new ConsoleProvider()\n  }\n}\n\n/** Flush + tear down the active backend (shutdown hook / `after()`). */\nexport async function shutdownTelemetry(): Promise<void> {\n  const provider = activeProvider\n  activeProvider = undefined\n  initialized = false\n  disposeLoggerExtension?.()\n  disposeLoggerExtension = undefined\n  disposeRuntime?.()\n  disposeRuntime = undefined\n  clearActiveProvider()\n  if (provider) await provider.shutdown()\n}\n\nfunction createRuntime(provider: TelemetryProvider): TelemetryRuntime {\n  return {\n    canUseGlobalTracePropagation: () =>\n      isOtlpBackend(provider.name as TelemetryBackendName)\n      && readTelemetryEnv().trustInboundTrace,\n    captureTraceContext,\n    continueTrace: (carrier, name, fn, options) =>\n      continueTrace(carrier, name, () => fn(), options),\n    withSpan: (name, fn, options) => withSpan(name, fn, options),\n    recordHttpDuration,\n    reportError,\n    shutdown: shutdownTelemetry,\n  }\n}\n\n/** Test-only: allow re-init in jest. */\nexport function resetTelemetryInit(): void {\n  initialized = false\n  activeProvider = undefined\n  disposeLoggerExtension?.()\n  disposeLoggerExtension = undefined\n  disposeRuntime?.()\n  disposeRuntime = undefined\n}\n"],
+  "mappings": "AACA,SAAS,eAAe,kBAAkB,8BAA8B;AACxE,SAAS,uBAAuB;AAChC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,OAEK;AACP,SAAS,oBAAoB;AAC7B,SAAS,+BAA+B;AACxC,SAAS,qBAAqB,qBAAqB;AACnD,SAAS,gBAAgB;AACzB,SAAS,0BAA0B;AACnC,SAAS,mBAAmB;AAE5B,IAAI,cAAc;AAClB,IAAI;AACJ,IAAI;AACJ,IAAI;AAEJ,MAAM,SAAS,aAAa,WAAW;AASvC,eAAsB,gBAA+B;AACnD,MAAI,YAAa;AAKjB,yBAAuB;AACvB,QAAM,MAAM,iBAAiB;AAC7B,QAAM,oBAAoB,QAAQ,IAAI,mBAAmB,KAAK,EAAE,YAAY,KAAK;AACjF,QAAM,qBAAqB,qBAAqB,sBAAsB,SAClE,sBAAsB,iBAAiB,IACvC;AAGJ,MAAI,CAAC,IAAI,WAAW,CAAC,mBAAoB;AAEzC,QAAM,WAAW,sBAAsB,MAAM,gBAAgB,IAAI,OAAO;AACxE,MAAI,CAAC,UAAU;AACb,WAAO,KAAK,gEAAgE;AAAA,MAC1E,SAAS,qBAAqB,IAAI;AAAA,IACpC,CAAC;AACD;AAAA,EACF;AAIA,QAAM,SAAS,MAAM;AACrB,oBAAkB,QAAQ;AAC1B,mBAAiB;AACjB,2BAAyB,wBAAwB,QAAQ;AACzD,mBAAiB,yBAAyB,cAAc,QAAQ,CAAC;AACjE,gBAAc;AAEd,SAAO,KAAK,yBAAyB;AAAA,IACnC,SAAS,SAAS;AAAA,IAClB,eAAe,IAAI;AAAA,EACrB,CAAC;AACH;AAEA,eAAe,gBAAgB,SAAuE;AACpG,QAAM,aAAa,sBAAsB,OAAO;AAChD,MAAI,WAAY,QAAO;AAEvB,MAAI,YAAY,UAAW,QAAO,IAAI,gBAAgB;AAEtD,MAAI,cAAc,OAAO,EAAG,QAAO,MAAM,iBAAiB,OAAO;AACjE,SAAO;AACT;AAOA,eAAe,iBAAiB,SAA2D;AACzF,MAAI;AACF,UAAM,MAAM,MAAM,OAAO,0BAA0B;AACnD,WAAO,IAAI,IAAI,aAAa,CAAC,GAAG,OAAO;AAAA,EACzC,SAAS,KAAK;AACZ,WAAO,KAAK,sDAAsD;AAAA,MAChE,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IACzD,CAAC;AACD,WAAO,IAAI,gBAAgB;AAAA,EAC7B;AACF;AAGA,eAAsB,oBAAmC;AACvD,QAAM,WAAW;AACjB,mBAAiB;AACjB,gBAAc;AACd,2BAAyB;AACzB,2BAAyB;AACzB,mBAAiB;AACjB,mBAAiB;AACjB,sBAAoB;AACpB,MAAI,SAAU,OAAM,SAAS,SAAS;AACxC;AAEA,SAAS,cAAc,UAA+C;AACpE,SAAO;AAAA,IACL,8BAA8B,MAC5B,cAAc,SAAS,IAA4B,KAChD,iBAAiB,EAAE;AAAA,IACxB;AAAA,IACA,eAAe,CAAC,SAAS,MAAM,IAAI,YACjC,cAAc,SAAS,MAAM,MAAM,GAAG,GAAG,OAAO;AAAA,IAClD,UAAU,CAAC,MAAM,IAAI,YAAY,SAAS,MAAM,IAAI,OAAO;AAAA,IAC3D;AAAA,IACA;AAAA,IACA,UAAU;AAAA,EACZ;AACF;AAGO,SAAS,qBAA2B;AACzC,gBAAc;AACd,mBAAiB;AACjB,2BAAyB;AACzB,2BAAyB;AACzB,mBAAiB;AACjB,mBAAiB;AACnB;",
   "names": []
 }

package/dist/provider/console-provider.js

@@ -15,6 +15,9 @@ class ConsoleSpan {
   setAttributes(attributes) {
     Object.assign(this.attributes, attributes);
   }
+  updateName(name) {
+    this.name = name;
+  }
   recordException(error) {
     this.status = "error";
     this.attributes.exception = serializeError(error).message;

package/dist/provider/console-provider.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/provider/console-provider.ts"],
-  "sourcesContent": ["import type {\n  LogRecord,\n  MetricPoint,\n  Span,\n  SpanOptions,\n  TelemetryProvider,\n  TelemetrySignal,\n  TraceCarrier,\n  TraceContext,\n} from '../types'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { serializeError } from '../facade/serialize'\nimport { runSpan } from './run-span'\n\nconst logger = createLogger('telemetry')\n\n/**\n * Dev backend: prints span timings and metric points to stdout (via the shared\n * logger). It does NOT handle logs \u2014 the facade's logger already writes those to\n * stdout, so `emitLog` is a no-op here to avoid duplication.\n */\nclass ConsoleSpan implements Span {\n  private readonly attributes: Record<string, unknown> = {}\n  private status: 'ok' | 'error' = 'ok'\n  private readonly startedAt = Date.now()\n\n  constructor(private readonly name: string) {}\n\n  setAttribute(key: string, value: string | number | boolean): void {\n    this.attributes[key] = value\n  }\n  setAttributes(attributes: Record<string, string | number | boolean | undefined>): void {\n    Object.assign(this.attributes, attributes)\n  }\n  recordException(error: unknown): void {\n    this.status = 'error'\n    this.attributes.exception = serializeError(error).message\n  }\n  setStatus(status: 'ok' | 'error'): void {\n    this.status = status\n  }\n  end(): void {\n    logger[this.status === 'error' ? 'error' : 'debug'](`Span ${this.name}`, {\n      span: this.name,\n      durationMs: Date.now() - this.startedAt,\n      status: this.status,\n    })\n  }\n}\n\nexport class ConsoleProvider implements TelemetryProvider {\n  readonly name = 'console'\n  readonly supports: readonly TelemetrySignal[] = ['traces', 'metrics']\n\n  async start(): Promise<void> {}\n  async shutdown(): Promise<void> {}\n\n  runInSpan<T>(name: string, _options: SpanOptions, fn: (span: Span) => T): T {\n    return runSpan(new ConsoleSpan(name), fn)\n  }\n\n  activeSpan(): Span | undefined {\n    return undefined\n  }\n\n  activeTraceContext(): TraceContext | undefined {\n    // ConsoleSpan carries no real trace ids (dev-only timing print).\n    return undefined\n  }\n\n  inject(_carrier: TraceCarrier): void {}\n\n  runInRemoteSpan<T>(_carrier: TraceCarrier, name: string, _options: SpanOptions, fn: (span: Span) => T): T {\n    return runSpan(new ConsoleSpan(name), fn)\n  }\n\n  emitLog(_record: LogRecord): void {}\n\n  recordMetric(point: MetricPoint): void {\n    logger.debug(`Metric ${point.name}`, {\n      metric: point.name,\n      kind: point.kind,\n      value: point.value,\n      ...point.labels,\n    })\n  }\n}\n"],
-  "mappings": "AAUA,SAAS,oBAAoB;AAC7B,SAAS,sBAAsB;AAC/B,SAAS,eAAe;AAExB,MAAM,SAAS,aAAa,WAAW;AAOvC,MAAM,YAA4B;AAAA,EAKhC,YAA6B,MAAc;AAAd;AAJ7B,SAAiB,aAAsC,CAAC;AACxD,SAAQ,SAAyB;AACjC,SAAiB,YAAY,KAAK,IAAI;AAAA,EAEM;AAAA,EAE5C,aAAa,KAAa,OAAwC;AAChE,SAAK,WAAW,GAAG,IAAI;AAAA,EACzB;AAAA,EACA,cAAc,YAAyE;AACrF,WAAO,OAAO,KAAK,YAAY,UAAU;AAAA,EAC3C;AAAA,EACA,gBAAgB,OAAsB;AACpC,SAAK,SAAS;AACd,SAAK,WAAW,YAAY,eAAe,KAAK,EAAE;AAAA,EACpD;AAAA,EACA,UAAU,QAA8B;AACtC,SAAK,SAAS;AAAA,EAChB;AAAA,EACA,MAAY;AACV,WAAO,KAAK,WAAW,UAAU,UAAU,OAAO,EAAE,QAAQ,KAAK,IAAI,IAAI;AAAA,MACvE,MAAM,KAAK;AAAA,MACX,YAAY,KAAK,IAAI,IAAI,KAAK;AAAA,MAC9B,QAAQ,KAAK;AAAA,IACf,CAAC;AAAA,EACH;AACF;AAEO,MAAM,gBAA6C;AAAA,EAAnD;AACL,SAAS,OAAO;AAChB,SAAS,WAAuC,CAAC,UAAU,SAAS;AAAA;AAAA,EAEpE,MAAM,QAAuB;AAAA,EAAC;AAAA,EAC9B,MAAM,WAA0B;AAAA,EAAC;AAAA,EAEjC,UAAa,MAAc,UAAuB,IAA0B;AAC1E,WAAO,QAAQ,IAAI,YAAY,IAAI,GAAG,EAAE;AAAA,EAC1C;AAAA,EAEA,aAA+B;AAC7B,WAAO;AAAA,EACT;AAAA,EAEA,qBAA+C;AAE7C,WAAO;AAAA,EACT;AAAA,EAEA,OAAO,UAA8B;AAAA,EAAC;AAAA,EAEtC,gBAAmB,UAAwB,MAAc,UAAuB,IAA0B;AACxG,WAAO,QAAQ,IAAI,YAAY,IAAI,GAAG,EAAE;AAAA,EAC1C;AAAA,EAEA,QAAQ,SAA0B;AAAA,EAAC;AAAA,EAEnC,aAAa,OAA0B;AACrC,WAAO,MAAM,UAAU,MAAM,IAAI,IAAI;AAAA,MACnC,QAAQ,MAAM;AAAA,MACd,MAAM,MAAM;AAAA,MACZ,OAAO,MAAM;AAAA,MACb,GAAG,MAAM;AAAA,IACX,CAAC;AAAA,EACH;AACF;",
+  "sourcesContent": ["import type {\n  LogRecord,\n  MetricPoint,\n  Span,\n  SpanOptions,\n  TelemetryProvider,\n  TelemetrySignal,\n  TraceCarrier,\n  TraceContext,\n} from '../types'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { serializeError } from '../facade/serialize'\nimport { runSpan } from './run-span'\n\nconst logger = createLogger('telemetry')\n\n/**\n * Dev backend: prints span timings and metric points to stdout (via the shared\n * logger). It does NOT handle logs \u2014 the facade's logger already writes those to\n * stdout, so `emitLog` is a no-op here to avoid duplication.\n */\nclass ConsoleSpan implements Span {\n  private readonly attributes: Record<string, unknown> = {}\n  private status: 'ok' | 'error' = 'ok'\n  private readonly startedAt = Date.now()\n\n  constructor(private name: string) {}\n\n  setAttribute(key: string, value: string | number | boolean): void {\n    this.attributes[key] = value\n  }\n  setAttributes(attributes: Record<string, string | number | boolean | undefined>): void {\n    Object.assign(this.attributes, attributes)\n  }\n  updateName(name: string): void {\n    this.name = name\n  }\n  recordException(error: unknown): void {\n    this.status = 'error'\n    this.attributes.exception = serializeError(error).message\n  }\n  setStatus(status: 'ok' | 'error'): void {\n    this.status = status\n  }\n  end(): void {\n    logger[this.status === 'error' ? 'error' : 'debug'](`Span ${this.name}`, {\n      span: this.name,\n      durationMs: Date.now() - this.startedAt,\n      status: this.status,\n    })\n  }\n}\n\nexport class ConsoleProvider implements TelemetryProvider {\n  readonly name = 'console'\n  readonly supports: readonly TelemetrySignal[] = ['traces', 'metrics']\n\n  async start(): Promise<void> {}\n  async shutdown(): Promise<void> {}\n\n  runInSpan<T>(name: string, _options: SpanOptions, fn: (span: Span) => T): T {\n    return runSpan(new ConsoleSpan(name), fn)\n  }\n\n  activeSpan(): Span | undefined {\n    return undefined\n  }\n\n  activeTraceContext(): TraceContext | undefined {\n    // ConsoleSpan carries no real trace ids (dev-only timing print).\n    return undefined\n  }\n\n  inject(_carrier: TraceCarrier): void {}\n\n  runInRemoteSpan<T>(_carrier: TraceCarrier, name: string, _options: SpanOptions, fn: (span: Span) => T): T {\n    return runSpan(new ConsoleSpan(name), fn)\n  }\n\n  emitLog(_record: LogRecord): void {}\n\n  recordMetric(point: MetricPoint): void {\n    logger.debug(`Metric ${point.name}`, {\n      metric: point.name,\n      kind: point.kind,\n      value: point.value,\n      ...point.labels,\n    })\n  }\n}\n"],
+  "mappings": "AAUA,SAAS,oBAAoB;AAC7B,SAAS,sBAAsB;AAC/B,SAAS,eAAe;AAExB,MAAM,SAAS,aAAa,WAAW;AAOvC,MAAM,YAA4B;AAAA,EAKhC,YAAoB,MAAc;AAAd;AAJpB,SAAiB,aAAsC,CAAC;AACxD,SAAQ,SAAyB;AACjC,SAAiB,YAAY,KAAK,IAAI;AAAA,EAEH;AAAA,EAEnC,aAAa,KAAa,OAAwC;AAChE,SAAK,WAAW,GAAG,IAAI;AAAA,EACzB;AAAA,EACA,cAAc,YAAyE;AACrF,WAAO,OAAO,KAAK,YAAY,UAAU;AAAA,EAC3C;AAAA,EACA,WAAW,MAAoB;AAC7B,SAAK,OAAO;AAAA,EACd;AAAA,EACA,gBAAgB,OAAsB;AACpC,SAAK,SAAS;AACd,SAAK,WAAW,YAAY,eAAe,KAAK,EAAE;AAAA,EACpD;AAAA,EACA,UAAU,QAA8B;AACtC,SAAK,SAAS;AAAA,EAChB;AAAA,EACA,MAAY;AACV,WAAO,KAAK,WAAW,UAAU,UAAU,OAAO,EAAE,QAAQ,KAAK,IAAI,IAAI;AAAA,MACvE,MAAM,KAAK;AAAA,MACX,YAAY,KAAK,IAAI,IAAI,KAAK;AAAA,MAC9B,QAAQ,KAAK;AAAA,IACf,CAAC;AAAA,EACH;AACF;AAEO,MAAM,gBAA6C;AAAA,EAAnD;AACL,SAAS,OAAO;AAChB,SAAS,WAAuC,CAAC,UAAU,SAAS;AAAA;AAAA,EAEpE,MAAM,QAAuB;AAAA,EAAC;AAAA,EAC9B,MAAM,WAA0B;AAAA,EAAC;AAAA,EAEjC,UAAa,MAAc,UAAuB,IAA0B;AAC1E,WAAO,QAAQ,IAAI,YAAY,IAAI,GAAG,EAAE;AAAA,EAC1C;AAAA,EAEA,aAA+B;AAC7B,WAAO;AAAA,EACT;AAAA,EAEA,qBAA+C;AAE7C,WAAO;AAAA,EACT;AAAA,EAEA,OAAO,UAA8B;AAAA,EAAC;AAAA,EAEtC,gBAAmB,UAAwB,MAAc,UAAuB,IAA0B;AACxG,WAAO,QAAQ,IAAI,YAAY,IAAI,GAAG,EAAE;AAAA,EAC1C;AAAA,EAEA,QAAQ,SAA0B;AAAA,EAAC;AAAA,EAEnC,aAAa,OAA0B;AACrC,WAAO,MAAM,UAAU,MAAM,IAAI,IAAI;AAAA,MACnC,QAAQ,MAAM;AAAA,MACd,MAAM,MAAM;AAAA,MACZ,OAAO,MAAM;AAAA,MACb,GAAG,MAAM;AAAA,IACX,CAAC;AAAA,EACH;AACF;",
   "names": []
 }

package/dist/provider/noop-provider.js

@@ -3,6 +3,8 @@ const NOOP_SPAN = {
   },
   setAttributes() {
   },
+  updateName() {
+  },
   recordException() {
   },
   setStatus() {

package/dist/provider/noop-provider.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/provider/noop-provider.ts"],
-  "sourcesContent": ["import type {\n  LogRecord,\n  MetricPoint,\n  Span,\n  SpanOptions,\n  TelemetryProvider,\n  TelemetrySignal,\n  TraceCarrier,\n  TraceContext,\n} from '../types'\n\n/** A span that does nothing \u2014 used when telemetry is off. */\nexport const NOOP_SPAN: Span = {\n  setAttribute() {},\n  setAttributes() {},\n  recordException() {},\n  setStatus() {},\n  end() {},\n}\n\n/**\n * The default backend: a hard no-op. `runInSpan` still runs `fn` (so app logic\n * is unaffected); everything else is a cheap return. The heavy OTEL SDK is\n * never imported on this path.\n */\nexport class NoopProvider implements TelemetryProvider {\n  readonly name = 'noop'\n  readonly supports: readonly TelemetrySignal[] = []\n\n  async start(): Promise<void> {}\n  async shutdown(): Promise<void> {}\n\n  runInSpan<T>(_name: string, _options: SpanOptions, fn: (span: Span) => T): T {\n    return fn(NOOP_SPAN)\n  }\n\n  activeSpan(): Span | undefined {\n    return undefined\n  }\n\n  activeTraceContext(): TraceContext | undefined {\n    return undefined\n  }\n\n  inject(_carrier: TraceCarrier): void {}\n\n  runInRemoteSpan<T>(_carrier: TraceCarrier, _name: string, _options: SpanOptions, fn: (span: Span) => T): T {\n    return fn(NOOP_SPAN)\n  }\n\n  emitLog(_record: LogRecord): void {}\n  recordMetric(_point: MetricPoint): void {}\n}\n"],
-  "mappings": "AAYO,MAAM,YAAkB;AAAA,EAC7B,eAAe;AAAA,EAAC;AAAA,EAChB,gBAAgB;AAAA,EAAC;AAAA,EACjB,kBAAkB;AAAA,EAAC;AAAA,EACnB,YAAY;AAAA,EAAC;AAAA,EACb,MAAM;AAAA,EAAC;AACT;AAOO,MAAM,aAA0C;AAAA,EAAhD;AACL,SAAS,OAAO;AAChB,SAAS,WAAuC,CAAC;AAAA;AAAA,EAEjD,MAAM,QAAuB;AAAA,EAAC;AAAA,EAC9B,MAAM,WAA0B;AAAA,EAAC;AAAA,EAEjC,UAAa,OAAe,UAAuB,IAA0B;AAC3E,WAAO,GAAG,SAAS;AAAA,EACrB;AAAA,EAEA,aAA+B;AAC7B,WAAO;AAAA,EACT;AAAA,EAEA,qBAA+C;AAC7C,WAAO;AAAA,EACT;AAAA,EAEA,OAAO,UAA8B;AAAA,EAAC;AAAA,EAEtC,gBAAmB,UAAwB,OAAe,UAAuB,IAA0B;AACzG,WAAO,GAAG,SAAS;AAAA,EACrB;AAAA,EAEA,QAAQ,SAA0B;AAAA,EAAC;AAAA,EACnC,aAAa,QAA2B;AAAA,EAAC;AAC3C;",
+  "sourcesContent": ["import type {\n  LogRecord,\n  MetricPoint,\n  Span,\n  SpanOptions,\n  TelemetryProvider,\n  TelemetrySignal,\n  TraceCarrier,\n  TraceContext,\n} from '../types'\n\n/** A span that does nothing \u2014 used when telemetry is off. */\nexport const NOOP_SPAN: Span = {\n  setAttribute() {},\n  setAttributes() {},\n  updateName() {},\n  recordException() {},\n  setStatus() {},\n  end() {},\n}\n\n/**\n * The default backend: a hard no-op. `runInSpan` still runs `fn` (so app logic\n * is unaffected); everything else is a cheap return. The heavy OTEL SDK is\n * never imported on this path.\n */\nexport class NoopProvider implements TelemetryProvider {\n  readonly name = 'noop'\n  readonly supports: readonly TelemetrySignal[] = []\n\n  async start(): Promise<void> {}\n  async shutdown(): Promise<void> {}\n\n  runInSpan<T>(_name: string, _options: SpanOptions, fn: (span: Span) => T): T {\n    return fn(NOOP_SPAN)\n  }\n\n  activeSpan(): Span | undefined {\n    return undefined\n  }\n\n  activeTraceContext(): TraceContext | undefined {\n    return undefined\n  }\n\n  inject(_carrier: TraceCarrier): void {}\n\n  runInRemoteSpan<T>(_carrier: TraceCarrier, _name: string, _options: SpanOptions, fn: (span: Span) => T): T {\n    return fn(NOOP_SPAN)\n  }\n\n  emitLog(_record: LogRecord): void {}\n  recordMetric(_point: MetricPoint): void {}\n}\n"],
+  "mappings": "AAYO,MAAM,YAAkB;AAAA,EAC7B,eAAe;AAAA,EAAC;AAAA,EAChB,gBAAgB;AAAA,EAAC;AAAA,EACjB,aAAa;AAAA,EAAC;AAAA,EACd,kBAAkB;AAAA,EAAC;AAAA,EACnB,YAAY;AAAA,EAAC;AAAA,EACb,MAAM;AAAA,EAAC;AACT;AAOO,MAAM,aAA0C;AAAA,EAAhD;AACL,SAAS,OAAO;AAChB,SAAS,WAAuC,CAAC;AAAA;AAAA,EAEjD,MAAM,QAAuB;AAAA,EAAC;AAAA,EAC9B,MAAM,WAA0B;AAAA,EAAC;AAAA,EAEjC,UAAa,OAAe,UAAuB,IAA0B;AAC3E,WAAO,GAAG,SAAS;AAAA,EACrB;AAAA,EAEA,aAA+B;AAC7B,WAAO;AAAA,EACT;AAAA,EAEA,qBAA+C;AAC7C,WAAO;AAAA,EACT;AAAA,EAEA,OAAO,UAA8B;AAAA,EAAC;AAAA,EAEtC,gBAAmB,UAAwB,OAAe,UAAuB,IAA0B;AACzG,WAAO,GAAG,SAAS;AAAA,EACrB;AAAA,EAEA,QAAQ,SAA0B;AAAA,EAAC;AAAA,EACnC,aAAa,QAA2B;AAAA,EAAC;AAC3C;",
   "names": []
 }

package/dist/provider/otlp-provider.js

@@ -5,6 +5,7 @@ import {
   isSpanContextValid,
   defaultTextMapGetter,
   defaultTextMapSetter,
+  ROOT_CONTEXT,
   SpanStatusCode,
   SpanKind as OtelSpanKind
 } from "@opentelemetry/api";
@@ -72,6 +73,23 @@ const SPAN_KIND = {
   producer: OtelSpanKind.PRODUCER,
   consumer: OtelSpanKind.CONSUMER
 };
+function spanLinks(carriers) {
+  if (!carriers?.length) return void 0;
+  const links = [];
+  for (const carrier of carriers) {
+    const linked = trace.getSpanContext(queuePropagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter));
+    if (linked && isSpanContextValid(linked)) links.push({ context: linked });
+  }
+  return links.length ? links : void 0;
+}
+function toOtelSpanOptions(options) {
+  return {
+    kind: options.kind ? SPAN_KIND[options.kind] : void 0,
+    attributes: cleanAttributes(options.attributes),
+    root: options.root,
+    links: spanLinks(options.links)
+  };
+}
 const SEVERITY = {
   debug: SeverityNumber.DEBUG,
   info: SeverityNumber.INFO,
@@ -89,6 +107,9 @@ class OtelSpan {
   setAttributes(attributes) {
     this.span.setAttributes(cleanAttributes(attributes));
   }
+  updateName(name) {
+    this.span.updateName(name);
+  }
   recordException(error) {
     this.span.recordException(serializeError(error));
   }
@@ -145,7 +166,7 @@ class OtlpProvider {
     const tracer = trace.getTracer(TRACER_NAME);
     return tracer.startActiveSpan(
       name,
-      { kind: options.kind ? SPAN_KIND[options.kind] : void 0, attributes: cleanAttributes(options.attributes) },
+      toOtelSpanOptions(options),
       (otelSpan) => runSpan(new OtelSpan(otelSpan), fn)
     );
   }
@@ -168,7 +189,7 @@ class OtlpProvider {
       parent,
       () => tracer.startActiveSpan(
         name,
-        { kind: options.kind ? SPAN_KIND[options.kind] : void 0, attributes: cleanAttributes(options.attributes) },
+        toOtelSpanOptions(options),
         (otelSpan) => runSpan(new OtelSpan(otelSpan), fn)
       )
     );

package/dist/provider/otlp-provider.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/provider/otlp-provider.ts"],
-  "sourcesContent": ["/**\n * The ONLY file in this package that imports `@opentelemetry/*`. Loaded via\n * dynamic `import()` from `init.ts` (so the heavy SDK never loads when telemetry\n * is off), and the OTEL packages live in `optionalDependencies`.\n *\n * Serves any OTLP backend \u2014 the endpoint + headers come from the standard\n * `OTEL_EXPORTER_OTLP_*` env vars, read by the exporters directly.\n */\nimport {\n  trace,\n  metrics,\n  context,\n  isSpanContextValid,\n  defaultTextMapGetter,\n  defaultTextMapSetter,\n  SpanStatusCode,\n  SpanKind as OtelSpanKind,\n  type Span as OtelApiSpan,\n  type TextMapPropagator,\n  type Counter,\n  type Histogram,\n  type Gauge,\n} from '@opentelemetry/api'\nimport { W3CTraceContextPropagator } from '@opentelemetry/core'\nimport { logs, SeverityNumber } from '@opentelemetry/api-logs'\nimport { NodeSDK } from '@opentelemetry/sdk-node'\nimport type { Instrumentation } from '@opentelemetry/instrumentation'\nimport { resourceFromAttributes } from '@opentelemetry/resources'\nimport { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'\nimport {\n  BatchSpanProcessor,\n  ParentBasedSampler,\n  TraceIdRatioBasedSampler,\n  type SpanProcessor,\n} from '@opentelemetry/sdk-trace-node'\nimport { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'\nimport { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'\nimport { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'\nimport { BatchLogRecordProcessor, type LogRecordProcessor } from '@opentelemetry/sdk-logs'\nimport { PeriodicExportingMetricReader, type IMetricReader } from '@opentelemetry/sdk-metrics'\nimport { PgInstrumentation } from '@opentelemetry/instrumentation-pg'\nimport { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici'\n\nimport type {\n  Attributes,\n  AttributeValue,\n  LogLevel,\n  LogRecord,\n  MetricPoint,\n  Span,\n  SpanKind,\n  SpanOptions,\n  TelemetryProvider,\n  TelemetrySignal,\n  TraceCarrier,\n  TraceContext,\n} from '../types'\nimport { readTelemetryEnv } from '../env'\nimport { redactAttributes, redactPii } from '../facade/redact'\nimport { serializeError } from '../facade/serialize'\nimport { runSpan } from './run-span'\n\nconst TRACER_NAME = 'open-mercato'\n\n/**\n * Queue/event trace propagation rides a dedicated W3C propagator on the payload\n * `_trace` carrier \u2014 deliberately NOT the global propagator below.\n */\nconst queuePropagator = new W3CTraceContextPropagator()\n\nconst W3C_TRACEPARENT = 'traceparent'\nconst W3C_TRACESTATE = 'tracestate'\n// Backup headers that mirror the W3C context but a proxy/LB won't rewrite.\nconst BACKUP_TRACEPARENT = 'x-original-traceparent'\nconst BACKUP_TRACESTATE = 'x-original-tracestate'\n\n/**\n * Global propagator: standard W3C plus a backup copy\n * (`x-original-traceparent`), with explicit inbound trust.\n *\n * The problem: a load balancer (e.g. GCP's) reads the inbound `traceparent`,\n * creates its own span, and **rewrites** `traceparent` to point at that span \u2014\n * which our backend never sees. With plain W3C extraction every request becomes a\n * child of that unexported span: no request is a root, and root-span / trace-group\n * views come up empty.\n *\n * The fix (the industry \"backup header\" pattern): on inject we also write\n * `x-original-traceparent`, which the LB leaves untouched. A backup header is\n * still caller-controlled at an HTTP boundary, so its mere\n * presence is not proof that one of our services created it. Extraction ignores\n * both standard and backup headers by default.\n *\n * `TELEMETRY_TRUST_INBOUND_TRACE=true` enables both extraction paths for a\n * deployment behind a trusted upstream. Our dedicated queue/event carrier is\n * unaffected \u2014 it uses `queuePropagator` directly, not this global one.\n */\nconst backupHeaderPropagator: TextMapPropagator = {\n  inject(ctx, carrier, setter) {\n    // Inject into a plain temp carrier so we can mirror the values regardless of\n    // the real carrier's setter shape, then copy both standard + backup headers.\n    const tmp: Record<string, string> = {}\n    queuePropagator.inject(ctx, tmp, defaultTextMapSetter)\n    for (const [key, value] of Object.entries(tmp)) setter.set(carrier, key, value)\n    if (tmp[W3C_TRACEPARENT]) setter.set(carrier, BACKUP_TRACEPARENT, tmp[W3C_TRACEPARENT])\n    if (tmp[W3C_TRACESTATE]) setter.set(carrier, BACKUP_TRACESTATE, tmp[W3C_TRACESTATE])\n  },\n  extract(ctx, carrier, getter) {\n    // Both the standard and backup headers are caller-controlled at an HTTP\n    // boundary. Trust neither unless the deployment explicitly opts in.\n    if (!readTelemetryEnv().trustInboundTrace) return ctx\n    const first = (value: string | string[] | undefined): string | undefined =>\n      Array.isArray(value) ? value[0] : value\n    const backupTraceparent = first(getter.get(carrier, BACKUP_TRACEPARENT))\n    if (backupTraceparent) {\n      const backupCarrier: Record<string, string> = { [W3C_TRACEPARENT]: backupTraceparent }\n      const backupTracestate = first(getter.get(carrier, BACKUP_TRACESTATE))\n      if (backupTracestate) backupCarrier[W3C_TRACESTATE] = backupTracestate\n      return queuePropagator.extract(ctx, backupCarrier, defaultTextMapGetter)\n    }\n    return queuePropagator.extract(ctx, carrier, getter)\n  },\n  fields: () => [...queuePropagator.fields(), BACKUP_TRACEPARENT, BACKUP_TRACESTATE],\n}\n\nfunction cleanAttributes(attributes?: Attributes): Record<string, AttributeValue> {\n  const out: Record<string, AttributeValue> = {}\n  if (!attributes) return out\n  for (const [key, value] of Object.entries(redactAttributes(attributes))) {\n    if (value !== undefined) out[key] = value\n  }\n  return out\n}\n\nconst SPAN_KIND: Record<SpanKind, OtelSpanKind> = {\n  internal: OtelSpanKind.INTERNAL,\n  server: OtelSpanKind.SERVER,\n  client: OtelSpanKind.CLIENT,\n  producer: OtelSpanKind.PRODUCER,\n  consumer: OtelSpanKind.CONSUMER,\n}\n\nconst SEVERITY: Record<LogLevel, SeverityNumber> = {\n  debug: SeverityNumber.DEBUG,\n  info: SeverityNumber.INFO,\n  warn: SeverityNumber.WARN,\n  error: SeverityNumber.ERROR,\n}\n\n/** Adapts an OTEL span to the vendor-neutral `Span` interface. */\nclass OtelSpan implements Span {\n  constructor(private readonly span: OtelApiSpan) {}\n  setAttribute(key: string, value: AttributeValue): void {\n    const redacted = cleanAttributes({ [key]: value })[key]\n    if (redacted !== undefined) this.span.setAttribute(key, redacted)\n  }\n  setAttributes(attributes: Attributes): void {\n    this.span.setAttributes(cleanAttributes(attributes))\n  }\n  recordException(error: unknown): void {\n    // Redact message + stack before they leave the process (Privacy): the auto\n    // record-on-throw path (run-span) and reportError both pass raw errors here.\n    this.span.recordException(serializeError(error))\n  }\n  setStatus(status: 'ok' | 'error', message?: string): void {\n    this.span.setStatus({\n      code: status === 'error' ? SpanStatusCode.ERROR : SpanStatusCode.OK,\n      message: message ? redactPii(message) : undefined,\n    })\n  }\n  end(): void {\n    this.span.end()\n  }\n}\n\n/**\n * Test seam: override the SDK's exporters/instrumentations so tests can use\n * in-memory exporters (deterministic, no network) instead of the OTLP defaults.\n * Production passes nothing \u2014 the OTLP defaults apply.\n */\nexport type OtlpProviderOptions = {\n  spanProcessors?: SpanProcessor[]\n  logRecordProcessors?: LogRecordProcessor[]\n  metricReaders?: IMetricReader[]\n  instrumentations?: Instrumentation[]\n}\n\n/**\n * PII guard (telemetry spec Privacy / R12). The single source of truth for pg\n * instrumentation config: `enhancedDatabaseReporting: false` means bound SQL\n * parameter VALUES are NOT captured \u2014 only the statement shape ($1, $2). User\n * data lives in those params, so this must never be flipped on. Asserted by a\n * regression test.\n */\nexport const PG_INSTRUMENTATION_OPTIONS = { enhancedDatabaseReporting: false } as const\n\nexport class OtlpProvider implements TelemetryProvider {\n  /** The configured backend name (signoz | newrelic | otlp) \u2014 all OTLP, vendor differs only by endpoint. */\n  readonly name: string\n  readonly supports: readonly TelemetrySignal[] = ['traces', 'metrics', 'logs', 'errors']\n\n  private sdk: NodeSDK | undefined\n  private readonly instruments = new Map<string, Counter | Histogram | Gauge>()\n\n  constructor(private readonly options: OtlpProviderOptions = {}, name = 'otlp') {\n    this.name = name\n  }\n\n  async start(): Promise<void> {\n    if (this.sdk) return\n    const env = readTelemetryEnv()\n\n    this.sdk = new NodeSDK({\n      resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: env.serviceName }),\n      // Global propagation roots requests by default. Both standard and backup\n      // inbound headers are honored only when TELEMETRY_TRUST_INBOUND_TRACE is\n      // explicitly enabled behind trusted infrastructure.\n      textMapPropagator: backupHeaderPropagator,\n      // Parent-based so child spans follow the trace's sampling decision; root\n      // spans sample at the configured ratio.\n      sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(env.samplingRatio) }),\n      spanProcessors: this.options.spanProcessors ?? [new BatchSpanProcessor(new OTLPTraceExporter())],\n      logRecordProcessors: this.options.logRecordProcessors ?? [\n        new BatchLogRecordProcessor({ exporter: new OTLPLogExporter() }),\n      ],\n      metricReaders: this.options.metricReaders ?? [\n        new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() }),\n      ],\n      instrumentations: this.options.instrumentations ?? [\n        new PgInstrumentation(PG_INSTRUMENTATION_OPTIONS),\n        new UndiciInstrumentation(),\n      ],\n    })\n    this.sdk.start()\n  }\n\n  async shutdown(): Promise<void> {\n    if (!this.sdk) return\n    await this.sdk.shutdown()\n    this.sdk = undefined\n  }\n\n  runInSpan<T>(name: string, options: SpanOptions, fn: (span: Span) => T): T {\n    const tracer = trace.getTracer(TRACER_NAME)\n    return tracer.startActiveSpan(\n      name,\n      { kind: options.kind ? SPAN_KIND[options.kind] : undefined, attributes: cleanAttributes(options.attributes) },\n      (otelSpan) => runSpan(new OtelSpan(otelSpan), fn),\n    )\n  }\n\n  activeSpan(): Span | undefined {\n    const active = trace.getActiveSpan()\n    return active ? new OtelSpan(active) : undefined\n  }\n\n  activeTraceContext(): TraceContext | undefined {\n    const ctx = trace.getActiveSpan()?.spanContext()\n    if (!ctx || !isSpanContextValid(ctx)) return undefined\n    return { traceId: ctx.traceId, spanId: ctx.spanId }\n  }\n\n  inject(carrier: TraceCarrier): void {\n    queuePropagator.inject(context.active(), carrier, defaultTextMapSetter)\n  }\n\n  runInRemoteSpan<T>(carrier: TraceCarrier, name: string, options: SpanOptions, fn: (span: Span) => T): T {\n    const parent = queuePropagator.extract(context.active(), carrier, defaultTextMapGetter)\n    const tracer = trace.getTracer(TRACER_NAME)\n    return context.with(parent, () =>\n      tracer.startActiveSpan(\n        name,\n        { kind: options.kind ? SPAN_KIND[options.kind] : undefined, attributes: cleanAttributes(options.attributes) },\n        (otelSpan) => runSpan(new OtelSpan(otelSpan), fn),\n      ),\n    )\n  }\n\n  emitLog(record: LogRecord): void {\n    const attributes: Record<string, AttributeValue> = cleanAttributes(record.attributes)\n    if (record.error) {\n      attributes['exception.type'] = redactPii(record.error.name)\n      attributes['exception.message'] = redactPii(record.error.message)\n      if (record.error.stack) attributes['exception.stacktrace'] = redactPii(record.error.stack)\n    }\n    logs.getLogger(TRACER_NAME).emit({\n      severityNumber: SEVERITY[record.level],\n      severityText: record.level,\n      body: redactPii(record.message),\n      attributes,\n    })\n  }\n\n  recordMetric(point: MetricPoint): void {\n    const labels = cleanAttributes(point.labels)\n    const instrument = this.getInstrument(point)\n    if (point.kind === 'counter') (instrument as Counter).add(point.value, labels)\n    else (instrument as Histogram | Gauge).record(point.value, labels)\n  }\n\n  private getInstrument(point: MetricPoint): Counter | Histogram | Gauge {\n    const key = `${point.kind}:${point.name}`\n    let instrument = this.instruments.get(key)\n    if (!instrument) {\n      const meter = metrics.getMeter(TRACER_NAME)\n      const opts = point.unit ? { unit: point.unit } : undefined\n      instrument =\n        point.kind === 'counter'\n          ? meter.createCounter(point.name, opts)\n          : point.kind === 'histogram'\n            ? meter.createHistogram(point.name, opts)\n            : meter.createGauge(point.name, opts)\n      this.instruments.set(key, instrument)\n    }\n    return instrument\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * The ONLY file in this package that imports `@opentelemetry/*`. Loaded via\n * dynamic `import()` from `init.ts` (so the heavy SDK never loads when telemetry\n * is off), and the OTEL packages live in `optionalDependencies`.\n *\n * Serves any OTLP backend \u2014 the endpoint + headers come from the standard\n * `OTEL_EXPORTER_OTLP_*` env vars, read by the exporters directly.\n */\nimport {\n  trace,\n  metrics,\n  context,\n  isSpanContextValid,\n  defaultTextMapGetter,\n  defaultTextMapSetter,\n  ROOT_CONTEXT,\n  SpanStatusCode,\n  SpanKind as OtelSpanKind,\n  type Link,\n  type Span as OtelApiSpan,\n  type SpanOptions as OtelSpanOptions,\n  type TextMapPropagator,\n  type Counter,\n  type Histogram,\n  type Gauge,\n} from '@opentelemetry/api'\nimport { W3CTraceContextPropagator } from '@opentelemetry/core'\nimport { logs, SeverityNumber } from '@opentelemetry/api-logs'\nimport { NodeSDK } from '@opentelemetry/sdk-node'\nimport type { Instrumentation } from '@opentelemetry/instrumentation'\nimport { resourceFromAttributes } from '@opentelemetry/resources'\nimport { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'\nimport {\n  BatchSpanProcessor,\n  ParentBasedSampler,\n  TraceIdRatioBasedSampler,\n  type SpanProcessor,\n} from '@opentelemetry/sdk-trace-node'\nimport { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'\nimport { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'\nimport { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'\nimport { BatchLogRecordProcessor, type LogRecordProcessor } from '@opentelemetry/sdk-logs'\nimport { PeriodicExportingMetricReader, type IMetricReader } from '@opentelemetry/sdk-metrics'\nimport { PgInstrumentation } from '@opentelemetry/instrumentation-pg'\nimport { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici'\n\nimport type {\n  Attributes,\n  AttributeValue,\n  LogLevel,\n  LogRecord,\n  MetricPoint,\n  Span,\n  SpanKind,\n  SpanOptions,\n  TelemetryProvider,\n  TelemetrySignal,\n  TraceCarrier,\n  TraceContext,\n} from '../types'\nimport { readTelemetryEnv } from '../env'\nimport { redactAttributes, redactPii } from '../facade/redact'\nimport { serializeError } from '../facade/serialize'\nimport { runSpan } from './run-span'\n\nconst TRACER_NAME = 'open-mercato'\n\n/**\n * Queue/event trace propagation rides a dedicated W3C propagator on the payload\n * `_trace` carrier \u2014 deliberately NOT the global propagator below.\n */\nconst queuePropagator = new W3CTraceContextPropagator()\n\nconst W3C_TRACEPARENT = 'traceparent'\nconst W3C_TRACESTATE = 'tracestate'\n// Backup headers that mirror the W3C context but a proxy/LB won't rewrite.\nconst BACKUP_TRACEPARENT = 'x-original-traceparent'\nconst BACKUP_TRACESTATE = 'x-original-tracestate'\n\n/**\n * Global propagator: standard W3C plus a backup copy\n * (`x-original-traceparent`), with explicit inbound trust.\n *\n * The problem: a load balancer (e.g. GCP's) reads the inbound `traceparent`,\n * creates its own span, and **rewrites** `traceparent` to point at that span \u2014\n * which our backend never sees. With plain W3C extraction every request becomes a\n * child of that unexported span: no request is a root, and root-span / trace-group\n * views come up empty.\n *\n * The fix (the industry \"backup header\" pattern): on inject we also write\n * `x-original-traceparent`, which the LB leaves untouched. A backup header is\n * still caller-controlled at an HTTP boundary, so its mere\n * presence is not proof that one of our services created it. Extraction ignores\n * both standard and backup headers by default.\n *\n * `TELEMETRY_TRUST_INBOUND_TRACE=true` enables both extraction paths for a\n * deployment behind a trusted upstream. Our dedicated queue/event carrier is\n * unaffected \u2014 it uses `queuePropagator` directly, not this global one.\n */\nconst backupHeaderPropagator: TextMapPropagator = {\n  inject(ctx, carrier, setter) {\n    // Inject into a plain temp carrier so we can mirror the values regardless of\n    // the real carrier's setter shape, then copy both standard + backup headers.\n    const tmp: Record<string, string> = {}\n    queuePropagator.inject(ctx, tmp, defaultTextMapSetter)\n    for (const [key, value] of Object.entries(tmp)) setter.set(carrier, key, value)\n    if (tmp[W3C_TRACEPARENT]) setter.set(carrier, BACKUP_TRACEPARENT, tmp[W3C_TRACEPARENT])\n    if (tmp[W3C_TRACESTATE]) setter.set(carrier, BACKUP_TRACESTATE, tmp[W3C_TRACESTATE])\n  },\n  extract(ctx, carrier, getter) {\n    // Both the standard and backup headers are caller-controlled at an HTTP\n    // boundary. Trust neither unless the deployment explicitly opts in.\n    if (!readTelemetryEnv().trustInboundTrace) return ctx\n    const first = (value: string | string[] | undefined): string | undefined =>\n      Array.isArray(value) ? value[0] : value\n    const backupTraceparent = first(getter.get(carrier, BACKUP_TRACEPARENT))\n    if (backupTraceparent) {\n      const backupCarrier: Record<string, string> = { [W3C_TRACEPARENT]: backupTraceparent }\n      const backupTracestate = first(getter.get(carrier, BACKUP_TRACESTATE))\n      if (backupTracestate) backupCarrier[W3C_TRACESTATE] = backupTracestate\n      return queuePropagator.extract(ctx, backupCarrier, defaultTextMapGetter)\n    }\n    return queuePropagator.extract(ctx, carrier, getter)\n  },\n  fields: () => [...queuePropagator.fields(), BACKUP_TRACEPARENT, BACKUP_TRACESTATE],\n}\n\nfunction cleanAttributes(attributes?: Attributes): Record<string, AttributeValue> {\n  const out: Record<string, AttributeValue> = {}\n  if (!attributes) return out\n  for (const [key, value] of Object.entries(redactAttributes(attributes))) {\n    if (value !== undefined) out[key] = value\n  }\n  return out\n}\n\nconst SPAN_KIND: Record<SpanKind, OtelSpanKind> = {\n  internal: OtelSpanKind.INTERNAL,\n  server: OtelSpanKind.SERVER,\n  client: OtelSpanKind.CLIENT,\n  producer: OtelSpanKind.PRODUCER,\n  consumer: OtelSpanKind.CONSUMER,\n}\n\n/**\n * Resolve `links` carriers to span contexts. Extraction runs against\n * `ROOT_CONTEXT`, never the active one \u2014 otherwise an empty carrier would\n * silently link a span to its own ambient parent instead of yielding no link.\n */\nfunction spanLinks(carriers?: TraceCarrier[]): Link[] | undefined {\n  if (!carriers?.length) return undefined\n  const links: Link[] = []\n  for (const carrier of carriers) {\n    const linked = trace.getSpanContext(queuePropagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter))\n    if (linked && isSpanContextValid(linked)) links.push({ context: linked })\n  }\n  return links.length ? links : undefined\n}\n\n/**\n * Translate the vendor-neutral options to OTEL's. `root: true` makes OTEL drop\n * the parent from the context it samples against, so the span starts a new trace\n * and the `ParentBasedSampler` falls through to its ratio-based root sampler.\n */\nfunction toOtelSpanOptions(options: SpanOptions): OtelSpanOptions {\n  return {\n    kind: options.kind ? SPAN_KIND[options.kind] : undefined,\n    attributes: cleanAttributes(options.attributes),\n    root: options.root,\n    links: spanLinks(options.links),\n  }\n}\n\nconst SEVERITY: Record<LogLevel, SeverityNumber> = {\n  debug: SeverityNumber.DEBUG,\n  info: SeverityNumber.INFO,\n  warn: SeverityNumber.WARN,\n  error: SeverityNumber.ERROR,\n}\n\n/** Adapts an OTEL span to the vendor-neutral `Span` interface. */\nclass OtelSpan implements Span {\n  constructor(private readonly span: OtelApiSpan) {}\n  setAttribute(key: string, value: AttributeValue): void {\n    const redacted = cleanAttributes({ [key]: value })[key]\n    if (redacted !== undefined) this.span.setAttribute(key, redacted)\n  }\n  setAttributes(attributes: Attributes): void {\n    this.span.setAttributes(cleanAttributes(attributes))\n  }\n  updateName(name: string): void {\n    this.span.updateName(name)\n  }\n  recordException(error: unknown): void {\n    // Redact message + stack before they leave the process (Privacy): the auto\n    // record-on-throw path (run-span) and reportError both pass raw errors here.\n    this.span.recordException(serializeError(error))\n  }\n  setStatus(status: 'ok' | 'error', message?: string): void {\n    this.span.setStatus({\n      code: status === 'error' ? SpanStatusCode.ERROR : SpanStatusCode.OK,\n      message: message ? redactPii(message) : undefined,\n    })\n  }\n  end(): void {\n    this.span.end()\n  }\n}\n\n/**\n * Test seam: override the SDK's exporters/instrumentations so tests can use\n * in-memory exporters (deterministic, no network) instead of the OTLP defaults.\n * Production passes nothing \u2014 the OTLP defaults apply.\n */\nexport type OtlpProviderOptions = {\n  spanProcessors?: SpanProcessor[]\n  logRecordProcessors?: LogRecordProcessor[]\n  metricReaders?: IMetricReader[]\n  instrumentations?: Instrumentation[]\n}\n\n/**\n * PII guard (telemetry spec Privacy / R12). The single source of truth for pg\n * instrumentation config: `enhancedDatabaseReporting: false` means bound SQL\n * parameter VALUES are NOT captured \u2014 only the statement shape ($1, $2). User\n * data lives in those params, so this must never be flipped on. Asserted by a\n * regression test.\n */\nexport const PG_INSTRUMENTATION_OPTIONS = { enhancedDatabaseReporting: false } as const\n\nexport class OtlpProvider implements TelemetryProvider {\n  /** The configured backend name (signoz | newrelic | otlp) \u2014 all OTLP, vendor differs only by endpoint. */\n  readonly name: string\n  readonly supports: readonly TelemetrySignal[] = ['traces', 'metrics', 'logs', 'errors']\n\n  private sdk: NodeSDK | undefined\n  private readonly instruments = new Map<string, Counter | Histogram | Gauge>()\n\n  constructor(private readonly options: OtlpProviderOptions = {}, name = 'otlp') {\n    this.name = name\n  }\n\n  async start(): Promise<void> {\n    if (this.sdk) return\n    const env = readTelemetryEnv()\n\n    this.sdk = new NodeSDK({\n      resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: env.serviceName }),\n      // Global propagation roots requests by default. Both standard and backup\n      // inbound headers are honored only when TELEMETRY_TRUST_INBOUND_TRACE is\n      // explicitly enabled behind trusted infrastructure.\n      textMapPropagator: backupHeaderPropagator,\n      // Parent-based so child spans follow the trace's sampling decision; root\n      // spans sample at the configured ratio.\n      sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(env.samplingRatio) }),\n      spanProcessors: this.options.spanProcessors ?? [new BatchSpanProcessor(new OTLPTraceExporter())],\n      logRecordProcessors: this.options.logRecordProcessors ?? [\n        new BatchLogRecordProcessor({ exporter: new OTLPLogExporter() }),\n      ],\n      metricReaders: this.options.metricReaders ?? [\n        new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() }),\n      ],\n      instrumentations: this.options.instrumentations ?? [\n        new PgInstrumentation(PG_INSTRUMENTATION_OPTIONS),\n        new UndiciInstrumentation(),\n      ],\n    })\n    this.sdk.start()\n  }\n\n  async shutdown(): Promise<void> {\n    if (!this.sdk) return\n    await this.sdk.shutdown()\n    this.sdk = undefined\n  }\n\n  runInSpan<T>(name: string, options: SpanOptions, fn: (span: Span) => T): T {\n    const tracer = trace.getTracer(TRACER_NAME)\n    return tracer.startActiveSpan(name, toOtelSpanOptions(options), (otelSpan) =>\n      runSpan(new OtelSpan(otelSpan), fn),\n    )\n  }\n\n  activeSpan(): Span | undefined {\n    const active = trace.getActiveSpan()\n    return active ? new OtelSpan(active) : undefined\n  }\n\n  activeTraceContext(): TraceContext | undefined {\n    const ctx = trace.getActiveSpan()?.spanContext()\n    if (!ctx || !isSpanContextValid(ctx)) return undefined\n    return { traceId: ctx.traceId, spanId: ctx.spanId }\n  }\n\n  inject(carrier: TraceCarrier): void {\n    queuePropagator.inject(context.active(), carrier, defaultTextMapSetter)\n  }\n\n  runInRemoteSpan<T>(carrier: TraceCarrier, name: string, options: SpanOptions, fn: (span: Span) => T): T {\n    const parent = queuePropagator.extract(context.active(), carrier, defaultTextMapGetter)\n    const tracer = trace.getTracer(TRACER_NAME)\n    return context.with(parent, () =>\n      tracer.startActiveSpan(name, toOtelSpanOptions(options), (otelSpan) =>\n        runSpan(new OtelSpan(otelSpan), fn),\n      ),\n    )\n  }\n\n  emitLog(record: LogRecord): void {\n    const attributes: Record<string, AttributeValue> = cleanAttributes(record.attributes)\n    if (record.error) {\n      attributes['exception.type'] = redactPii(record.error.name)\n      attributes['exception.message'] = redactPii(record.error.message)\n      if (record.error.stack) attributes['exception.stacktrace'] = redactPii(record.error.stack)\n    }\n    logs.getLogger(TRACER_NAME).emit({\n      severityNumber: SEVERITY[record.level],\n      severityText: record.level,\n      body: redactPii(record.message),\n      attributes,\n    })\n  }\n\n  recordMetric(point: MetricPoint): void {\n    const labels = cleanAttributes(point.labels)\n    const instrument = this.getInstrument(point)\n    if (point.kind === 'counter') (instrument as Counter).add(point.value, labels)\n    else (instrument as Histogram | Gauge).record(point.value, labels)\n  }\n\n  private getInstrument(point: MetricPoint): Counter | Histogram | Gauge {\n    const key = `${point.kind}:${point.name}`\n    let instrument = this.instruments.get(key)\n    if (!instrument) {\n      const meter = metrics.getMeter(TRACER_NAME)\n      const opts = point.unit ? { unit: point.unit } : undefined\n      instrument =\n        point.kind === 'counter'\n          ? meter.createCounter(point.name, opts)\n          : point.kind === 'histogram'\n            ? meter.createHistogram(point.name, opts)\n            : meter.createGauge(point.name, opts)\n      this.instruments.set(key, instrument)\n    }\n    return instrument\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/telemetry",
-  "version": "0.6.8-develop.6993.1.3fc50f3409",
+  "version": "0.6.8-develop.7000.1.0ae682bad1",
   "description": "Vendor-neutral spans, metrics, and error reporting backed by a pluggable OTLP provider. Off by default; the telemetry runtime is loaded only when explicitly enabled.",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
     }
   },
   "dependencies": {
-    "@open-mercato/shared": "0.6.8-develop.6993.1.3fc50f3409"
+    "@open-mercato/shared": "0.6.8-develop.7000.1.0ae682bad1"
   },
   "optionalDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/__tests__/otlp-integration.test.ts

@@ -102,6 +102,49 @@ describe('OtlpProvider (in-memory exporters)', () => {
     expect(parentSpanId(child as ReadableSpan)).toBe(parent?.spanContext().spanId)
   })
 
+  it('root: true starts a NEW trace instead of nesting under the active one', () => {
+    withSpan('long-job', () => withSpan('batch', () => undefined, { root: true }))
+    const spans = spanExporter.getFinishedSpans()
+    const job = spans.find((s) => s.name === 'long-job')
+    const batch = spans.find((s) => s.name === 'batch')
+    expect(job && batch).toBeTruthy()
+    expect(batch?.spanContext().traceId).not.toBe(job?.spanContext().traceId)
+    expect(parentSpanId(batch as ReadableSpan)).toBeUndefined()
+  })
+
+  it('links a rooted span back to the trace that caused it', () => {
+    let carrier: Record<string, string> = {}
+    withSpan('run', () => {
+      carrier = captureTraceContext()
+    })
+    const run = spanExporter.getFinishedSpans().find((s) => s.name === 'run')
+
+    withSpan('linked-batch', () => undefined, { root: true, links: [carrier] })
+    const batch = spanExporter.getFinishedSpans().find((s) => s.name === 'linked-batch')
+
+    expect(batch?.spanContext().traceId).not.toBe(run?.spanContext().traceId)
+    expect(batch?.links).toHaveLength(1)
+    expect(batch?.links[0]?.context.traceId).toBe(run?.spanContext().traceId)
+    expect(batch?.links[0]?.context.spanId).toBe(run?.spanContext().spanId)
+  })
+
+  it('drops empty and malformed link carriers instead of emitting invalid links', () => {
+    withSpan('unlinked', () => undefined, {
+      root: true,
+      links: [{}, { traceparent: 'not-a-traceparent' }],
+    })
+    const span = spanExporter.getFinishedSpans().find((s) => s.name === 'unlinked')
+    expect(span?.links).toHaveLength(0)
+  })
+
+  it('does not link a rooted span to its ambient parent when the carrier is empty', () => {
+    // Extraction must run against ROOT_CONTEXT: an empty carrier means "no
+    // link", never "link to whatever happens to be active here".
+    withSpan('ambient', () => withSpan('rooted', () => undefined, { root: true, links: [{}] }))
+    const rooted = spanExporter.getFinishedSpans().find((s) => s.name === 'rooted')
+    expect(rooted?.links).toHaveLength(0)
+  })
+
   it('inject() writes a valid W3C traceparent inside an active span', () => {
     let carrier: Record<string, string> = {}
     withSpan('producer', () => {

package/src/__tests__/otlp-root-sampling.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Regression test for the bug `root` exists to fix.
+ *
+ * `ParentBasedSampler` only rolls the dice at a trace's ROOT; every descendant
+ * inherits that one decision. A sync/backfill job inherits the trace of the
+ * request that triggered it, so below ratio 1.0 an entire multi-day run is a
+ * coin flip taken hours earlier — lose it and the run emits nothing at all, for
+ * its whole life, with no way to intervene from outside.
+ *
+ * Ratio 0 makes that deterministic here: a span nested under a sampled parent is
+ * still recorded (inheritance), while a `root: true` span takes a FRESH decision
+ * and is dropped. A run of rooted batches therefore never rides on one flip.
+ *
+ * Its own file because the sampling ratio is read once at `provider.start()` and
+ * NodeSDK installs process-global tracer state.
+ */
+import { InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
+
+import { OtlpProvider } from '../provider/otlp-provider'
+import { setActiveProvider, resetActiveProvider } from '../provider/registry'
+import { resetTelemetryEnvCache } from '../env'
+import { withSpan, continueTrace } from '../index'
+
+const spanExporter = new InMemorySpanExporter()
+let provider: OtlpProvider
+
+/** A remote parent already marked sampled (trace-flags `01`). */
+const SAMPLED_REMOTE_CARRIER = {
+  traceparent: `00-${'1'.repeat(32)}-${'2'.repeat(16)}-01`,
+}
+
+/** The span processor hands off to the exporter off the microtask queue. */
+const settleExports = () => new Promise((resolve) => setTimeout(resolve, 20))
+
+beforeAll(async () => {
+  process.env.TELEMETRY_BACKEND = 'otlp'
+  process.env.TELEMETRY_SAMPLING_RATIO = '0'
+  resetTelemetryEnvCache()
+  provider = new OtlpProvider({
+    spanProcessors: [new SimpleSpanProcessor(spanExporter)],
+    instrumentations: [],
+  })
+  await provider.start()
+  setActiveProvider(provider)
+  // The first span after NodeSDK.start() can be dropped while the global tracer
+  // provider finishes installing — warm up, settle a tick, then reset.
+  withSpan('warmup', () => undefined)
+  await new Promise((resolve) => setTimeout(resolve, 10))
+  spanExporter.reset()
+})
+
+afterAll(async () => {
+  await provider.shutdown()
+  resetActiveProvider()
+  delete process.env.TELEMETRY_BACKEND
+  delete process.env.TELEMETRY_SAMPLING_RATIO
+  resetTelemetryEnvCache()
+})
+
+describe('root spans take their own sampling decision', () => {
+  it('drops a rooted span at ratio 0 while a nested span still inherits the parent decision', async () => {
+    continueTrace(SAMPLED_REMOTE_CARRIER, 'queue.job', () => {
+      withSpan('nested.batch', () => undefined)
+      withSpan('rooted.batch', () => undefined, { root: true })
+    })
+    await settleExports()
+
+    const names = spanExporter.getFinishedSpans().map((span) => span.name)
+    // Inherited from the sampled remote parent — the status quo for anything
+    // that nests under the triggering request.
+    expect(names).toContain('queue.job')
+    expect(names).toContain('nested.batch')
+    // Re-sampled from scratch against the ratio, so the trigger's decision no
+    // longer governs it.
+    expect(names).not.toContain('rooted.batch')
+  })
+})

package/src/init.ts

@@ -13,6 +13,7 @@ import {
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import { registerTelemetryLogger } from './facade/logger-bridge'
 import { captureTraceContext, continueTrace } from './facade/propagation'
+import { withSpan } from './facade/tracer'
 import { recordHttpDuration } from './facade/http'
 import { reportError } from './facade/report-error'
 
@@ -117,6 +118,7 @@ function createRuntime(provider: TelemetryProvider): TelemetryRuntime {
     captureTraceContext,
     continueTrace: (carrier, name, fn, options) =>
       continueTrace(carrier, name, () => fn(), options),
+    withSpan: (name, fn, options) => withSpan(name, fn, options),
     recordHttpDuration,
     reportError,
     shutdown: shutdownTelemetry,

package/src/provider/console-provider.ts

@@ -24,7 +24,7 @@ class ConsoleSpan implements Span {
   private status: 'ok' | 'error' = 'ok'
   private readonly startedAt = Date.now()
 
-  constructor(private readonly name: string) {}
+  constructor(private name: string) {}
 
   setAttribute(key: string, value: string | number | boolean): void {
     this.attributes[key] = value
@@ -32,6 +32,9 @@ class ConsoleSpan implements Span {
   setAttributes(attributes: Record<string, string | number | boolean | undefined>): void {
     Object.assign(this.attributes, attributes)
   }
+  updateName(name: string): void {
+    this.name = name
+  }
   recordException(error: unknown): void {
     this.status = 'error'
     this.attributes.exception = serializeError(error).message

package/src/provider/noop-provider.ts

@@ -13,6 +13,7 @@ import type {
 export const NOOP_SPAN: Span = {
   setAttribute() {},
   setAttributes() {},
+  updateName() {},
   recordException() {},
   setStatus() {},
   end() {},

package/src/provider/otlp-provider.ts

@@ -13,9 +13,12 @@ import {
   isSpanContextValid,
   defaultTextMapGetter,
   defaultTextMapSetter,
+  ROOT_CONTEXT,
   SpanStatusCode,
   SpanKind as OtelSpanKind,
+  type Link,
   type Span as OtelApiSpan,
+  type SpanOptions as OtelSpanOptions,
   type TextMapPropagator,
   type Counter,
   type Histogram,
@@ -139,6 +142,35 @@ const SPAN_KIND: Record<SpanKind, OtelSpanKind> = {
   consumer: OtelSpanKind.CONSUMER,
 }
 
+/**
+ * Resolve `links` carriers to span contexts. Extraction runs against
+ * `ROOT_CONTEXT`, never the active one — otherwise an empty carrier would
+ * silently link a span to its own ambient parent instead of yielding no link.
+ */
+function spanLinks(carriers?: TraceCarrier[]): Link[] | undefined {
+  if (!carriers?.length) return undefined
+  const links: Link[] = []
+  for (const carrier of carriers) {
+    const linked = trace.getSpanContext(queuePropagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter))
+    if (linked && isSpanContextValid(linked)) links.push({ context: linked })
+  }
+  return links.length ? links : undefined
+}
+
+/**
+ * Translate the vendor-neutral options to OTEL's. `root: true` makes OTEL drop
+ * the parent from the context it samples against, so the span starts a new trace
+ * and the `ParentBasedSampler` falls through to its ratio-based root sampler.
+ */
+function toOtelSpanOptions(options: SpanOptions): OtelSpanOptions {
+  return {
+    kind: options.kind ? SPAN_KIND[options.kind] : undefined,
+    attributes: cleanAttributes(options.attributes),
+    root: options.root,
+    links: spanLinks(options.links),
+  }
+}
+
 const SEVERITY: Record<LogLevel, SeverityNumber> = {
   debug: SeverityNumber.DEBUG,
   info: SeverityNumber.INFO,
@@ -156,6 +188,9 @@ class OtelSpan implements Span {
   setAttributes(attributes: Attributes): void {
     this.span.setAttributes(cleanAttributes(attributes))
   }
+  updateName(name: string): void {
+    this.span.updateName(name)
+  }
   recordException(error: unknown): void {
     // Redact message + stack before they leave the process (Privacy): the auto
     // record-on-throw path (run-span) and reportError both pass raw errors here.
@@ -241,10 +276,8 @@ export class OtlpProvider implements TelemetryProvider {
 
   runInSpan<T>(name: string, options: SpanOptions, fn: (span: Span) => T): T {
     const tracer = trace.getTracer(TRACER_NAME)
-    return tracer.startActiveSpan(
-      name,
-      { kind: options.kind ? SPAN_KIND[options.kind] : undefined, attributes: cleanAttributes(options.attributes) },
-      (otelSpan) => runSpan(new OtelSpan(otelSpan), fn),
+    return tracer.startActiveSpan(name, toOtelSpanOptions(options), (otelSpan) =>
+      runSpan(new OtelSpan(otelSpan), fn),
     )
   }
 
@@ -267,10 +300,8 @@ export class OtlpProvider implements TelemetryProvider {
     const parent = queuePropagator.extract(context.active(), carrier, defaultTextMapGetter)
     const tracer = trace.getTracer(TRACER_NAME)
     return context.with(parent, () =>
-      tracer.startActiveSpan(
-        name,
-        { kind: options.kind ? SPAN_KIND[options.kind] : undefined, attributes: cleanAttributes(options.attributes) },
-        (otelSpan) => runSpan(new OtelSpan(otelSpan), fn),
+      tracer.startActiveSpan(name, toOtelSpanOptions(options), (otelSpan) =>
+        runSpan(new OtelSpan(otelSpan), fn),
       ),
     )
   }

package/src/types.ts

@@ -43,6 +43,29 @@ export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer
 export type SpanOptions = {
   kind?: SpanKind
   attributes?: Attributes
+  /**
+   * Start a NEW trace instead of nesting under the active context, so the
+   * sampler takes a fresh decision for this span.
+   *
+   * Without it a long-lived job (a multi-day import, a reindex) is one trace
+   * under one `ParentBased` decision taken on whatever request triggered it:
+   * below ratio 1.0 a whole run can emit nothing, and at ratio 1.0 it becomes an
+   * unrenderable million-span trace. Rooting the unit of work the analysis
+   * actually reasons about — a batch, a page — bounds both. Pair with `links` so
+   * the causal chain back to the trigger survives.
+   *
+   * Meaningful for `withSpan` only. Passing it through `continueTrace` would
+   * discard the very parent the carrier supplies, defeating that call's purpose;
+   * link to the carrier instead of continuing it if that is what you want.
+   */
+  root?: boolean
+  /**
+   * Causal links to other traces, as W3C carriers — `captureTraceContext()` for
+   * the currently active trace, or the `_trace` carrier off a queue/event
+   * payload for a remote one. Empty or malformed carriers are dropped rather
+   * than emitted as invalid links.
+   */
+  links?: TraceCarrier[]
 }
 
 /**
@@ -52,6 +75,17 @@ export type SpanOptions = {
 export interface Span {
   setAttribute(key: string, value: AttributeValue): void
   setAttributes(attributes: Attributes): void
+  /**
+   * Rename an in-flight span, for work whose identity is only known once it has
+   * run — a read that turns out to have drained its stream rather than produced
+   * a batch. Keeping such a span under the batch name would over-count batches
+   * and add an unlabelled latency sample to every dashboard built on that name.
+   *
+   * Optional so a third-party `TelemetryProvider` predating it still satisfies
+   * the interface. Call it as `span.updateName?.(…)` and treat "not renamed" as
+   * a tolerable degradation, never a correctness requirement.
+   */
+  updateName?(name: string): void
   recordException(error: unknown): void
   setStatus(status: 'ok' | 'error', message?: string): void
   end(): void