@open-mercato/telemetry 0.10.1-develop.7833.1.d6cbf0e3ab → 0.10.1-develop.7841.1.af87ac614d

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:telemetry] found 30 entry points
+[build:telemetry] found 31 entry points
 [build:telemetry] built successfully

package/AGENTS.md

@@ -25,7 +25,12 @@ off by default. Spec:
 - 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.
+- Use semantic-convention metric/attribute names when available, unless an
+  auto-instrumentation the OTLP provider registers already emits that name
+  (`PgInstrumentation` owns `db.client.connection.*`); use `om.*` then, since
+  two instruments must never share a name.
+- Keep the built-in metric names, units, and fixed labels synchronized with the
+  catalog in `packages/telemetry/README.md`.
 - Keep metric labels low-cardinality. Tenant, organization, and user IDs belong
   on span attributes, never metric labels.
 - Apply redaction at the provider boundary as well as at facade call sites.
@@ -106,6 +111,8 @@ host/queue shared runtime bridge ── absent while off
 - `src/provider/*`: noop/console/OTLP providers and global provider registry.
 - `src/init.ts`: explicit-enabled initialization and process-wide bridge
   registration.
+- `src/runtime-metrics.ts`: enabled-only process sampler and the single
+  interval that invokes shared periodic metric collectors.
 - `src/nextjs-config.ts`: build-time constants only; no runtime imports.
 - `src/nextjs.ts`: enabled runtime helper.
 - `src/browser/*`: browser RUM. `config.ts` (shared, env-free contract) and

package/README.md

@@ -285,6 +285,50 @@ implementation, where you can decide what a dropped report means.
 `attributes`, so putting it in both `tags` and `extra`, as the snippet above does
 with `tags`, is your choice rather than an accident of the payload.
 
+### Built-in runtime metrics
+
+An active provider starts one process-wide 10-second sampler. Disabled/noop
+telemetry starts no interval or event-loop monitor. The sampler also invokes
+shared metric collectors, which lets the primary PostgreSQL pool report state
+without making `@open-mercato/shared` depend on this package.
+
+| Metric | Kind | Unit | Labels |
+| --- | --- | --- | --- |
+| `om.db.pool.connections` | gauge | `{connection}` | `pool=primary`, `state=idle\|used` |
+| `om.db.pool.pending_requests` | gauge | `{request}` | `pool=primary` |
+| `om.db.pool.max` | gauge | `{connection}` | `pool=primary` |
+| `om.db.pool.wait_time` | histogram | `s` | `pool=primary` |
+| `nodejs.eventloop.utilization` | gauge | `1` | none |
+| `nodejs.eventloop.delay.p50` / `p90` / `p99` | gauge | `s` | none |
+| `process.memory.usage` | gauge | `By` | none |
+| `v8js.memory.heap.used` | gauge | `By` | `v8js.heap.space.name` |
+
+Pool acquisition wait is recorded per `pool.connect` call, including failed
+promise and callback acquisitions, and includes opening a new connection when
+the pool grows. Connection-state values are sampled; sum `idle` and `used` for
+the current open-connection total.
+
+The pool metrics use the `om.db.pool.*` namespace on purpose. Under an OTLP
+backend `@opentelemetry/instrumentation-pg` already emits the semantic-convention
+`db.client.connection.count` and `db.client.connection.pending_requests` as
+UpDownCounters labelled `db.client.connection.state` /
+`db.client.connection.pool.name`. Reusing those names would export two streams
+per name with conflicting types and label keys. Query `om.db.pool.*` for the
+sampled view, which is also available under the `console` backend.
+
+The event-loop delay percentiles come from `monitorEventLoopDelay` with a 20 ms
+resolution, which records the whole timer interval rather than the overshoot.
+An idle process therefore reports about 0.020 s, not 0. Subtract 0.020 s before
+you compare against a real-delay budget: an alert at 0.050 s fires at about
+30 ms of actual blocking.
+
+Under an OTLP backend, every histogram recorded in seconds
+(`om.db.pool.wait_time`, `http.server.request.duration`,
+`om.enricher.duration`) is exported with explicit boundaries of 1 ms, 5 ms, 10 ms, 25 ms, 50 ms, 75 ms, 100 ms, 250 ms,
+500 ms, 750 ms, 1 s, 2.5 s, 5 s, 7.5 s and 10 s, so backends can compute
+percentiles. The SDK default is millisecond-scaled and would put every
+realistic latency in its first bucket.
+
 ### Long-lived jobs: root spans
 
 Trace context propagates from the request that triggered a job through the queue

package/dist/init.js

@@ -15,10 +15,13 @@ import { withSpan } from "./facade/tracer.js";
 import { recordHttpDuration } from "./facade/http.js";
 import { histogram } from "./facade/meter.js";
 import { reportError } from "./facade/report-error.js";
+import { startRuntimeMetrics } from "./runtime-metrics.js";
 let initialized = false;
+let initializing;
 let activeProvider;
 let disposeLoggerExtension;
 let disposeRuntime;
+let disposeRuntimeMetrics;
 const logger = createLogger("telemetry");
 const OTLP_DEPENDENCY_UNAVAILABLE = /* @__PURE__ */ Symbol.for("open-mercato.telemetry.otlp-dependency-unavailable");
 class OtlpDependencyUnavailableError extends Error {
@@ -33,6 +36,15 @@ class OtlpDependencyUnavailableError extends Error {
 }
 async function initTelemetry() {
   if (initialized) return;
+  if (initializing) return initializing;
+  let pending;
+  pending = initializeTelemetry().finally(() => {
+    if (initializing === pending) initializing = void 0;
+  });
+  initializing = pending;
+  return pending;
+}
+async function initializeTelemetry() {
   resetTelemetryEnvCache();
   const env = readTelemetryEnv();
   const configuredBackend = process.env.TELEMETRY_BACKEND?.trim().toLowerCase() ?? "";
@@ -50,6 +62,7 @@ async function initTelemetry() {
   activeProvider = provider;
   disposeLoggerExtension = registerTelemetryLogger(provider);
   disposeRuntime = registerTelemetryRuntime(createRuntime(provider));
+  disposeRuntimeMetrics = startRuntimeMetrics();
   initialized = true;
   logger.info("Telemetry initialized", {
     backend: provider.name,
@@ -73,11 +86,27 @@ async function loadOtlpProvider(backend) {
   return new mod.OtlpProvider({}, backend);
 }
 async function shutdownTelemetry() {
+  if (initializing) {
+    try {
+      await initializing;
+    } catch (err) {
+      try {
+        reportError(err, {
+          module: "telemetry",
+          code: "telemetry.initialization_failed"
+        });
+      } catch {
+      }
+      logger.warn("Telemetry initialization failed before shutdown", { err });
+    }
+  }
   const provider = activeProvider;
   activeProvider = void 0;
   initialized = false;
   disposeLoggerExtension?.();
   disposeLoggerExtension = void 0;
+  disposeRuntimeMetrics?.();
+  disposeRuntimeMetrics = void 0;
   disposeRuntime?.();
   disposeRuntime = void 0;
   clearActiveProvider();
@@ -89,6 +118,7 @@ function createRuntime(provider) {
     captureTraceContext,
     continueTrace: (carrier, name, fn, options) => continueTrace(carrier, name, () => fn(), options),
     withSpan: (name, fn, options) => withSpan(name, fn, options),
+    recordMetric: (point) => provider.recordMetric(point),
     recordHistogram: histogram,
     recordHttpDuration,
     reportError,
@@ -97,9 +127,12 @@ function createRuntime(provider) {
 }
 function resetTelemetryInit() {
   initialized = false;
+  initializing = void 0;
   activeProvider = void 0;
   disposeLoggerExtension?.();
   disposeLoggerExtension = void 0;
+  disposeRuntimeMetrics?.();
+  disposeRuntimeMetrics = void 0;
   disposeRuntime?.();
   disposeRuntime = void 0;
 }

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 { withSpan } from './facade/tracer'\nimport { recordHttpDuration } from './facade/http'\nimport { histogram } from './facade/meter'\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')\nconst OTLP_DEPENDENCY_UNAVAILABLE = Symbol.for('open-mercato.telemetry.otlp-dependency-unavailable')\n\nclass OtlpDependencyUnavailableError extends Error {\n  constructor(backend: TelemetryBackendName, cause: unknown) {\n    super(\n      `[internal] OTLP telemetry backend \"${backend}\" cannot start because its OpenTelemetry runtime dependencies are unavailable. Install optional dependencies, set TELEMETRY_BACKEND=console, or unset TELEMETRY_BACKEND to disable telemetry.`,\n      { cause },\n    )\n    this.name = 'OtlpDependencyUnavailableError'\n    Object.defineProperty(this, OTLP_DEPENDENCY_UNAVAILABLE, { value: true })\n  }\n}\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. An explicit OTLP selection\n * must fail at startup when those packages are unavailable instead of silently\n * switching telemetry semantics.\n */\nasync function loadOtlpProvider(backend: TelemetryBackendName): Promise<TelemetryProvider> {\n  let mod: typeof import('./provider/otlp-provider')\n  try {\n    mod = await import('./provider/otlp-provider')\n  } catch (error) {\n    throw new OtlpDependencyUnavailableError(backend, error)\n  }\n  return new mod.OtlpProvider({}, backend)\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    recordHistogram: histogram,\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": "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",
+  "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 { histogram } from './facade/meter'\nimport { reportError } from './facade/report-error'\nimport { startRuntimeMetrics } from './runtime-metrics'\n\nlet initialized = false\nlet initializing: Promise<void> | undefined\nlet activeProvider: TelemetryProvider | undefined\nlet disposeLoggerExtension: (() => void) | undefined\nlet disposeRuntime: (() => void) | undefined\nlet disposeRuntimeMetrics: (() => void) | undefined\n\nconst logger = createLogger('telemetry')\nconst OTLP_DEPENDENCY_UNAVAILABLE = Symbol.for('open-mercato.telemetry.otlp-dependency-unavailable')\n\nclass OtlpDependencyUnavailableError extends Error {\n  constructor(backend: TelemetryBackendName, cause: unknown) {\n    super(\n      `[internal] OTLP telemetry backend \"${backend}\" cannot start because its OpenTelemetry runtime dependencies are unavailable. Install optional dependencies, set TELEMETRY_BACKEND=console, or unset TELEMETRY_BACKEND to disable telemetry.`,\n      { cause },\n    )\n    this.name = 'OtlpDependencyUnavailableError'\n    Object.defineProperty(this, OTLP_DEPENDENCY_UNAVAILABLE, { value: true })\n  }\n}\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  if (initializing) return initializing\n\n  let pending: Promise<void>\n  pending = initializeTelemetry().finally(() => {\n    if (initializing === pending) initializing = undefined\n  })\n  initializing = pending\n  return pending\n}\n\nasync function initializeTelemetry(): Promise<void> {\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  disposeRuntimeMetrics = startRuntimeMetrics()\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. An explicit OTLP selection\n * must fail at startup when those packages are unavailable instead of silently\n * switching telemetry semantics.\n */\nasync function loadOtlpProvider(backend: TelemetryBackendName): Promise<TelemetryProvider> {\n  let mod: typeof import('./provider/otlp-provider')\n  try {\n    mod = await import('./provider/otlp-provider')\n  } catch (error) {\n    throw new OtlpDependencyUnavailableError(backend, error)\n  }\n  return new mod.OtlpProvider({}, backend)\n}\n\n/** Flush + tear down the active backend (shutdown hook / `after()`). */\nexport async function shutdownTelemetry(): Promise<void> {\n  if (initializing) {\n    try {\n      await initializing\n    } catch (err) {\n      try {\n        reportError(err, {\n          module: 'telemetry',\n          code: 'telemetry.initialization_failed',\n        })\n      } catch {}\n      logger.warn('Telemetry initialization failed before shutdown', { err })\n    }\n  }\n  const provider = activeProvider\n  activeProvider = undefined\n  initialized = false\n  disposeLoggerExtension?.()\n  disposeLoggerExtension = undefined\n  disposeRuntimeMetrics?.()\n  disposeRuntimeMetrics = 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    recordMetric: (point) => provider.recordMetric(point),\n    recordHistogram: histogram,\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  initializing = undefined\n  activeProvider = undefined\n  disposeLoggerExtension?.()\n  disposeLoggerExtension = undefined\n  disposeRuntimeMetrics?.()\n  disposeRuntimeMetrics = undefined\n  disposeRuntime?.()\n  disposeRuntime = undefined\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/provider/otlp-provider.js

@@ -125,6 +125,27 @@ class OtelSpan {
   }
 }
 const PG_INSTRUMENTATION_OPTIONS = { enhancedDatabaseReporting: false };
+const SECONDS_HISTOGRAM_BUCKETS = [
+  1e-3,
+  5e-3,
+  0.01,
+  0.025,
+  0.05,
+  0.075,
+  0.1,
+  0.25,
+  0.5,
+  0.75,
+  1,
+  2.5,
+  5,
+  7.5,
+  10
+];
+function histogramOptions(unit) {
+  if (unit !== "s") return unit ? { unit } : void 0;
+  return { unit, advice: { explicitBucketBoundaries: [...SECONDS_HISTOGRAM_BUCKETS] } };
+}
 class OtlpProvider {
   constructor(options = {}, name = "otlp") {
     this.options = options;
@@ -221,7 +242,7 @@ class OtlpProvider {
     if (!instrument) {
       const meter = metrics.getMeter(TRACER_NAME);
       const opts = point.unit ? { unit: point.unit } : void 0;
-      instrument = point.kind === "counter" ? meter.createCounter(point.name, opts) : point.kind === "histogram" ? meter.createHistogram(point.name, opts) : meter.createGauge(point.name, opts);
+      instrument = point.kind === "counter" ? meter.createCounter(point.name, opts) : point.kind === "histogram" ? meter.createHistogram(point.name, histogramOptions(point.unit)) : meter.createGauge(point.name, opts);
       this.instruments.set(key, instrument);
     }
     return instrument;
@@ -229,6 +250,7 @@ class OtlpProvider {
 }
 export {
   OtlpProvider,
-  PG_INSTRUMENTATION_OPTIONS
+  PG_INSTRUMENTATION_OPTIONS,
+  SECONDS_HISTOGRAM_BUCKETS
 };
 //# sourceMappingURL=otlp-provider.js.map

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  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 { BACKUP_TRACEPARENT_HEADER, BACKUP_TRACESTATE_HEADER } from '../trace-headers'\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 = BACKUP_TRACEPARENT_HEADER\nconst BACKUP_TRACESTATE = BACKUP_TRACESTATE_HEADER\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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",
+  "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  type MetricOptions,\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 { BACKUP_TRACEPARENT_HEADER, BACKUP_TRACESTATE_HEADER } from '../trace-headers'\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 = BACKUP_TRACEPARENT_HEADER\nconst BACKUP_TRACESTATE = BACKUP_TRACESTATE_HEADER\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\n/**\n * Bucket boundaries for every histogram recorded in seconds. Without explicit\n * advice the SDK falls back to millisecond-scaled defaults (0, 5, 10 \u2026 10000),\n * which puts every realistic latency in the first bucket and leaves percentiles\n * uncomputable. A superset of the semconv HTTP-duration advice, plus a 1 ms\n * bucket for sub-millisecond pool acquisitions.\n */\nexport const SECONDS_HISTOGRAM_BUCKETS: readonly number[] = [\n  0.001, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,\n]\n\nfunction histogramOptions(unit: string | undefined): MetricOptions | undefined {\n  if (unit !== 's') return unit ? { unit } : undefined\n  return { unit, advice: { explicitBucketBoundaries: [...SECONDS_HISTOGRAM_BUCKETS] } }\n}\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, histogramOptions(point.unit))\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/dist/runtime-metrics.js

@@ -0,0 +1,132 @@
+import { monitorEventLoopDelay, performance } from "node:perf_hooks";
+import { getHeapSpaceStatistics } from "node:v8";
+import {
+  collectTelemetryMetrics,
+  getTelemetryRuntime,
+  recordTelemetryMetric
+} from "@open-mercato/shared/lib/telemetry/runtime";
+import { createLogger } from "@open-mercato/shared/lib/logger";
+const SAMPLE_INTERVAL_MS = 1e4;
+const DELAY_RESOLUTION_MS = 20;
+const NANOSECONDS_PER_SECOND = 1e9;
+const GLOBAL_KEY = /* @__PURE__ */ Symbol.for("@open-mercato/telemetry.runtimeMetrics");
+const logger = createLogger("telemetry").child({ component: "runtime-metrics" });
+const defaultSources = {
+  createEventLoopDelayMonitor: () => monitorEventLoopDelay({ resolution: DELAY_RESOLUTION_MS }),
+  eventLoopUtilization: (first, second) => performance.eventLoopUtilization(first, second),
+  memoryUsage: () => process.memoryUsage(),
+  heapSpaceStatistics: () => getHeapSpaceStatistics(),
+  setInterval: (handler, intervalMs) => setInterval(handler, intervalMs),
+  clearInterval: (interval) => clearInterval(interval)
+};
+function store() {
+  const globalStore = globalThis;
+  let current = globalStore[GLOBAL_KEY];
+  if (!current) {
+    current = {};
+    globalStore[GLOBAL_KEY] = current;
+  }
+  return current;
+}
+function secondsFromNanoseconds(value) {
+  return Number.isFinite(value) ? Math.max(0, value) / NANOSECONDS_PER_SECOND : 0;
+}
+function createRuntimeMetricsSampler(sources = defaultSources) {
+  const delay = sources.createEventLoopDelayMonitor();
+  let previousUtilization = sources.eventLoopUtilization();
+  delay.enable();
+  const sample = () => {
+    try {
+      const currentUtilization = sources.eventLoopUtilization();
+      const intervalUtilization = sources.eventLoopUtilization(
+        currentUtilization,
+        previousUtilization
+      );
+      previousUtilization = currentUtilization;
+      recordTelemetryMetric({
+        kind: "gauge",
+        name: "nodejs.eventloop.utilization",
+        value: intervalUtilization.utilization,
+        unit: "1"
+      });
+      for (const percentile of [50, 90, 99]) {
+        recordTelemetryMetric({
+          kind: "gauge",
+          name: `nodejs.eventloop.delay.p${percentile}`,
+          value: secondsFromNanoseconds(delay.percentile(percentile)),
+          unit: "s"
+        });
+      }
+      recordTelemetryMetric({
+        kind: "gauge",
+        name: "process.memory.usage",
+        value: sources.memoryUsage().rss,
+        unit: "By"
+      });
+      for (const heapSpace of sources.heapSpaceStatistics()) {
+        recordTelemetryMetric({
+          kind: "gauge",
+          name: "v8js.memory.heap.used",
+          value: heapSpace.space_used_size,
+          labels: { "v8js.heap.space.name": heapSpace.space_name },
+          unit: "By"
+        });
+      }
+      collectTelemetryMetrics((err) => {
+        logger.warn("Runtime metric collector failed", { err });
+      });
+    } catch (err) {
+      try {
+        getTelemetryRuntime()?.reportError(err, {
+          module: "telemetry",
+          code: "telemetry.runtime_sampling_failed"
+        });
+      } catch {
+      }
+      logger.warn("Runtime metric sampling failed", { err });
+    } finally {
+      delay.reset();
+    }
+  };
+  const interval = sources.setInterval(sample, SAMPLE_INTERVAL_MS);
+  interval.unref?.();
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    sources.clearInterval(interval);
+    delay.disable();
+  };
+}
+function startRuntimeMetrics(sources = defaultSources) {
+  const current = store();
+  if (!current.active) {
+    current.active = {
+      references: 0,
+      dispose: createRuntimeMetricsSampler(sources)
+    };
+  }
+  const active = current.active;
+  active.references += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    active.references -= 1;
+    if (active.references > 0) return;
+    active.dispose();
+    const latest = store();
+    if (latest.active === active) latest.active = void 0;
+  };
+}
+function resetRuntimeMetrics() {
+  const current = store();
+  current.active?.dispose();
+  current.active = void 0;
+}
+export {
+  createRuntimeMetricsSampler,
+  resetRuntimeMetrics,
+  startRuntimeMetrics
+};
+//# sourceMappingURL=runtime-metrics.js.map

package/dist/runtime-metrics.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/runtime-metrics.ts"],
+  "sourcesContent": ["import { monitorEventLoopDelay, performance, type EventLoopUtilization } from 'node:perf_hooks'\nimport { getHeapSpaceStatistics } from 'node:v8'\nimport {\n  collectTelemetryMetrics,\n  getTelemetryRuntime,\n  recordTelemetryMetric,\n} from '@open-mercato/shared/lib/telemetry/runtime'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\n\nconst SAMPLE_INTERVAL_MS = 10_000\nconst DELAY_RESOLUTION_MS = 20\nconst NANOSECONDS_PER_SECOND = 1_000_000_000\nconst GLOBAL_KEY = Symbol.for('@open-mercato/telemetry.runtimeMetrics')\n\nexport type EventLoopDelayMonitor = {\n  enable(): void\n  disable(): void\n  percentile(percentile: number): number\n  reset(): void\n}\n\nexport type HeapSpaceSample = {\n  space_name: string\n  space_used_size: number\n}\n\nexport type RuntimeMetricSources = {\n  createEventLoopDelayMonitor(): EventLoopDelayMonitor\n  eventLoopUtilization(\n    first?: EventLoopUtilization,\n    second?: EventLoopUtilization,\n  ): EventLoopUtilization\n  memoryUsage(): { rss: number }\n  heapSpaceStatistics(): HeapSpaceSample[]\n  setInterval(handler: () => void, intervalMs: number): ReturnType<typeof setInterval>\n  clearInterval(interval: ReturnType<typeof setInterval>): void\n}\n\ntype ActiveRuntimeSampler = {\n  references: number\n  dispose(): void\n}\n\ntype RuntimeMetricsStore = {\n  active?: ActiveRuntimeSampler\n}\n\nconst logger = createLogger('telemetry').child({ component: 'runtime-metrics' })\n\nconst defaultSources: RuntimeMetricSources = {\n  createEventLoopDelayMonitor: () => monitorEventLoopDelay({ resolution: DELAY_RESOLUTION_MS }),\n  eventLoopUtilization: (first, second) => performance.eventLoopUtilization(first, second),\n  memoryUsage: () => process.memoryUsage(),\n  heapSpaceStatistics: () => getHeapSpaceStatistics(),\n  setInterval: (handler, intervalMs) => setInterval(handler, intervalMs),\n  clearInterval: (interval) => clearInterval(interval),\n}\n\nfunction store(): RuntimeMetricsStore {\n  const globalStore = globalThis as unknown as Record<symbol, RuntimeMetricsStore | undefined>\n  let current = globalStore[GLOBAL_KEY]\n  if (!current) {\n    current = {}\n    globalStore[GLOBAL_KEY] = current\n  }\n  return current\n}\n\nfunction secondsFromNanoseconds(value: number): number {\n  return Number.isFinite(value) ? Math.max(0, value) / NANOSECONDS_PER_SECOND : 0\n}\n\nexport function createRuntimeMetricsSampler(\n  sources: RuntimeMetricSources = defaultSources,\n): () => void {\n  const delay = sources.createEventLoopDelayMonitor()\n  let previousUtilization = sources.eventLoopUtilization()\n  delay.enable()\n\n  const sample = () => {\n    try {\n      const currentUtilization = sources.eventLoopUtilization()\n      const intervalUtilization = sources.eventLoopUtilization(\n        currentUtilization,\n        previousUtilization,\n      )\n      previousUtilization = currentUtilization\n\n      recordTelemetryMetric({\n        kind: 'gauge',\n        name: 'nodejs.eventloop.utilization',\n        value: intervalUtilization.utilization,\n        unit: '1',\n      })\n      for (const percentile of [50, 90, 99]) {\n        recordTelemetryMetric({\n          kind: 'gauge',\n          name: `nodejs.eventloop.delay.p${percentile}`,\n          value: secondsFromNanoseconds(delay.percentile(percentile)),\n          unit: 's',\n        })\n      }\n\n      recordTelemetryMetric({\n        kind: 'gauge',\n        name: 'process.memory.usage',\n        value: sources.memoryUsage().rss,\n        unit: 'By',\n      })\n      for (const heapSpace of sources.heapSpaceStatistics()) {\n        recordTelemetryMetric({\n          kind: 'gauge',\n          name: 'v8js.memory.heap.used',\n          value: heapSpace.space_used_size,\n          labels: { 'v8js.heap.space.name': heapSpace.space_name },\n          unit: 'By',\n        })\n      }\n\n      collectTelemetryMetrics((err) => {\n        logger.warn('Runtime metric collector failed', { err })\n      })\n    } catch (err) {\n      try {\n        getTelemetryRuntime()?.reportError(err, {\n          module: 'telemetry',\n          code: 'telemetry.runtime_sampling_failed',\n        })\n      } catch {}\n      logger.warn('Runtime metric sampling failed', { err })\n    } finally {\n      delay.reset()\n    }\n  }\n\n  const interval = sources.setInterval(sample, SAMPLE_INTERVAL_MS)\n  interval.unref?.()\n\n  let disposed = false\n  return () => {\n    if (disposed) return\n    disposed = true\n    sources.clearInterval(interval)\n    delay.disable()\n  }\n}\n\nexport function startRuntimeMetrics(\n  sources: RuntimeMetricSources = defaultSources,\n): () => void {\n  const current = store()\n  if (!current.active) {\n    current.active = {\n      references: 0,\n      dispose: createRuntimeMetricsSampler(sources),\n    }\n  }\n\n  const active = current.active\n  active.references += 1\n  let released = false\n\n  return () => {\n    if (released) return\n    released = true\n    active.references -= 1\n    if (active.references > 0) return\n    active.dispose()\n    const latest = store()\n    if (latest.active === active) latest.active = undefined\n  }\n}\n\n/** Test-only: tear down the process-wide sampler regardless of reference count. */\nexport function resetRuntimeMetrics(): void {\n  const current = store()\n  current.active?.dispose()\n  current.active = undefined\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/telemetry",
-  "version": "0.10.1-develop.7833.1.d6cbf0e3ab",
+  "version": "0.10.1-develop.7841.1.af87ac614d",
   "license": "MIT",
   "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",
@@ -38,7 +38,7 @@
     }
   },
   "dependencies": {
-    "@open-mercato/shared": "0.10.1-develop.7833.1.d6cbf0e3ab"
+    "@open-mercato/shared": "0.10.1-develop.7841.1.af87ac614d"
   },
   "peerDependencies": {
     "react": ">=18.0.0"

package/src/__tests__/env-load-order.test.ts

@@ -3,7 +3,7 @@ import {
   getTelemetryRuntime,
   resetTelemetryRuntime,
 } from '@open-mercato/shared/lib/telemetry/runtime'
-import { initTelemetry, resetTelemetryInit } from '../init'
+import { initTelemetry, resetTelemetryInit, shutdownTelemetry } from '../init'
 import {
   getActiveProvider,
   registerProvider,
@@ -12,6 +12,7 @@ import {
 import { resetTelemetryEnvCache } from '../env'
 import type { TelemetryProvider } from '../types'
 import { NOOP_SPAN } from '../provider/noop-provider'
+import * as errorReporting from '../facade/report-error'
 
 function provider(name = 'noop'): TelemetryProvider {
   return {
@@ -31,6 +32,7 @@ function provider(name = 'noop'): TelemetryProvider {
 
 describe('telemetry explicit opt-in boundary', () => {
   beforeEach(() => {
+    jest.useFakeTimers()
     delete process.env.TELEMETRY_BACKEND
     resetTelemetryEnvCache()
     resetTelemetryInit()
@@ -39,6 +41,12 @@ describe('telemetry explicit opt-in boundary', () => {
     resetTelemetryRuntime()
   })
 
+  afterEach(() => {
+    jest.restoreAllMocks()
+    resetTelemetryInit()
+    jest.useRealTimers()
+  })
+
   it('does not resolve a custom provider or register runtime hooks while off', async () => {
     const customNoop = provider()
     registerProvider(customNoop)
@@ -49,6 +57,7 @@ describe('telemetry explicit opt-in boundary', () => {
     expect(getActiveProvider().name).toBe('noop')
     expect(getLoggerExtension()).toBeUndefined()
     expect(getTelemetryRuntime()).toBeUndefined()
+    expect(jest.getTimerCount()).toBe(0)
   })
 
   it('can initialize after dotenv sets an enabled backend following an off call', async () => {
@@ -63,6 +72,7 @@ describe('telemetry explicit opt-in boundary', () => {
     expect(getActiveProvider()).toBe(customConsole)
     expect(getLoggerExtension()).toBeDefined()
     expect(getTelemetryRuntime()).toBeDefined()
+    expect(jest.getTimerCount()).toBe(1)
   })
 
   it('initializes an explicitly registered custom backend', async () => {
@@ -78,6 +88,69 @@ describe('telemetry explicit opt-in boundary', () => {
     expect(getTelemetryRuntime()).toBeDefined()
   })
 
+  it('shares concurrent initialization and releases the sampler on shutdown', async () => {
+    const customConsole = provider('console')
+    registerProvider(customConsole)
+    process.env.TELEMETRY_BACKEND = 'console'
+
+    await Promise.all([initTelemetry(), initTelemetry()])
+
+    expect(customConsole.start).toHaveBeenCalledTimes(1)
+    expect(jest.getTimerCount()).toBe(1)
+
+    await shutdownTelemetry()
+
+    expect(customConsole.shutdown).toHaveBeenCalledTimes(1)
+    expect(getTelemetryRuntime()).toBeUndefined()
+    expect(jest.getTimerCount()).toBe(0)
+  })
+
+  it.each([false, true])('reports rejected initialization during shutdown and permits recovery (reporting throws: %s)', async (reportingThrows) => {
+    const failure = new Error('[internal] telemetry provider startup failed')
+    let rejectStart!: (reason: unknown) => void
+    const startup = new Promise<void>((_resolve, reject) => { rejectStart = reject })
+    const customConsole = provider('console')
+    customConsole.start = jest.fn(() => startup)
+    registerProvider(customConsole)
+    process.env.TELEMETRY_BACKEND = 'console'
+    const reportError = jest.spyOn(errorReporting, 'reportError')
+    if (reportingThrows) {
+      reportError.mockImplementation(() => { throw new Error('[internal] reporting unavailable') })
+    }
+
+    const initialization = initTelemetry()
+    const initializationFailure = expect(initialization).rejects.toBe(failure)
+    const shutdown = shutdownTelemetry()
+    expect(customConsole.start).toHaveBeenCalledTimes(1)
+    expect(reportError).not.toHaveBeenCalled()
+
+    rejectStart(failure)
+    await initializationFailure
+    await expect(shutdown).resolves.toBeUndefined()
+
+    expect(reportError).toHaveBeenCalledTimes(1)
+    expect(reportError).toHaveBeenCalledWith(failure, {
+      module: 'telemetry',
+      code: 'telemetry.initialization_failed',
+    })
+    expect(customConsole.shutdown).not.toHaveBeenCalled()
+    expect(getActiveProvider().name).toBe('noop')
+    expect(getLoggerExtension()).toBeUndefined()
+    expect(getTelemetryRuntime()).toBeUndefined()
+    expect(jest.getTimerCount()).toBe(0)
+
+    const recoveredProvider = provider('console')
+    registerProvider(recoveredProvider)
+    await initTelemetry()
+    expect(recoveredProvider.start).toHaveBeenCalledTimes(1)
+    expect(jest.getTimerCount()).toBe(1)
+    await shutdownTelemetry()
+    expect(recoveredProvider.shutdown).toHaveBeenCalledTimes(1)
+    expect(getLoggerExtension()).toBeUndefined()
+    expect(getTelemetryRuntime()).toBeUndefined()
+    expect(jest.getTimerCount()).toBe(0)
+  })
+
   it('wires shared runtime histograms to the active provider', async () => {
     const customConsole = provider('console')
     registerProvider(customConsole)

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

@@ -8,9 +8,15 @@ import { SpanStatusCode, propagation, trace, context, defaultTextMapSetter, ROOT
 import { W3CTraceContextPropagator } from '@opentelemetry/core'
 import { InMemorySpanExporter, SimpleSpanProcessor, type ReadableSpan } from '@opentelemetry/sdk-trace-base'
 import { InMemoryLogRecordExporter, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs'
-import { InMemoryMetricExporter, PeriodicExportingMetricReader, AggregationTemporality } from '@opentelemetry/sdk-metrics'
-
-import { OtlpProvider } from '../provider/otlp-provider'
+import {
+  InMemoryMetricExporter,
+  PeriodicExportingMetricReader,
+  AggregationTemporality,
+  DataPointType,
+  type Histogram,
+} from '@opentelemetry/sdk-metrics'
+
+import { OtlpProvider, SECONDS_HISTOGRAM_BUCKETS } from '../provider/otlp-provider'
 import { createBackupHeaderPropagator } from '../browser/propagator'
 import {
   createLogger,
@@ -20,7 +26,7 @@ import {
 import { setActiveProvider, resetActiveProvider } from '../provider/registry'
 import { resetTelemetryEnvCache } from '../env'
 import { registerTelemetryLogger } from '../facade/logger-bridge'
-import { withSpan, captureTraceContext, continueTrace, reportError, counter } from '../index'
+import { withSpan, captureTraceContext, continueTrace, reportError, counter, histogram } from '../index'
 
 const spanExporter = new InMemorySpanExporter()
 const logExporter = new InMemoryLogRecordExporter()
@@ -357,4 +363,28 @@ describe('OtlpProvider (in-memory exporters)', () => {
       .flatMap((rm) => rm.scopeMetrics.flatMap((sm) => sm.metrics.map((m) => m.descriptor.name)))
     expect(metricNames).toContain('om.errors')
   })
+
+  it('aggregates second-unit histograms with second-scaled buckets', async () => {
+    histogram('om.test.wait_time', 0.003, { pool: 'primary' }, 's')
+    histogram('om.test.wait_time', 0.0002, { pool: 'primary' }, 's')
+    histogram('om.test.payload_size', 3, undefined, 'By')
+    await metricReader.forceFlush()
+
+    const histogramPoint = (name: string) => {
+      const metric = metricExporter
+        .getMetrics()
+        .flatMap((rm) => rm.scopeMetrics.flatMap((sm) => sm.metrics))
+        .find((candidate) => candidate.descriptor.name === name)
+      expect(metric?.dataPointType).toBe(DataPointType.HISTOGRAM)
+      return metric?.dataPoints[0]?.value as Histogram | undefined
+    }
+
+    const seconds = histogramPoint('om.test.wait_time')
+    expect(seconds?.buckets.boundaries).toEqual([...SECONDS_HISTOGRAM_BUCKETS])
+    expect(seconds?.buckets.counts.slice(0, 3)).toEqual([1, 1, 0])
+    expect(seconds?.count).toBe(2)
+
+    const bytes = histogramPoint('om.test.payload_size')
+    expect(bytes?.buckets.boundaries).not.toEqual([...SECONDS_HISTOGRAM_BUCKETS])
+  })
 })

package/src/__tests__/runtime-metrics.test.ts

@@ -0,0 +1,239 @@
+import {
+  registerTelemetryMetricCollector,
+  registerTelemetryRuntime,
+  resetTelemetryMetricCollectors,
+  resetTelemetryRuntime,
+  type TelemetryMetricPoint,
+  type TelemetryRuntime,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+import {
+  createRuntimeMetricsSampler,
+  resetRuntimeMetrics,
+  startRuntimeMetrics,
+  type EventLoopDelayMonitor,
+  type RuntimeMetricSources,
+} from '../runtime-metrics'
+import type { EventLoopUtilization } from 'node:perf_hooks'
+
+function createRuntime(recordMetric: (point: TelemetryMetricPoint) => void): TelemetryRuntime {
+  return {
+    canUseGlobalTracePropagation: () => false,
+    captureTraceContext: () => ({}),
+    continueTrace: (_carrier, _name, fn) => fn(),
+    recordMetric,
+    recordHttpDuration: () => {},
+    reportError: () => {},
+    shutdown: async () => {},
+  }
+}
+
+describe('runtime metrics sampler', () => {
+  afterEach(() => {
+    resetRuntimeMetrics()
+    resetTelemetryMetricCollectors()
+    resetTelemetryRuntime()
+  })
+
+  it('records interval runtime values and invokes shared metric collectors', () => {
+    const points: TelemetryMetricPoint[] = []
+    registerTelemetryRuntime(createRuntime((point) => points.push(point)))
+    const collectPool = jest.fn()
+    registerTelemetryMetricCollector(collectPool)
+
+    const delay: EventLoopDelayMonitor = {
+      enable: jest.fn(),
+      disable: jest.fn(),
+      percentile: jest.fn((percentile) => percentile * 1_000_000),
+      reset: jest.fn(),
+    }
+    const utilization: EventLoopUtilization[] = [
+      { idle: 10, active: 10, utilization: 0.5 },
+      { idle: 15, active: 25, utilization: 0.625 },
+      { idle: 5, active: 15, utilization: 0.75 },
+    ]
+    let sample = () => {}
+    const interval = { unref: jest.fn() } as unknown as ReturnType<typeof setInterval>
+    const sources: RuntimeMetricSources = {
+      createEventLoopDelayMonitor: () => delay,
+      eventLoopUtilization: jest.fn(() => utilization.shift() ?? {
+        idle: 0,
+        active: 0,
+        utilization: 0,
+      }),
+      memoryUsage: () => ({ rss: 123_456 }),
+      heapSpaceStatistics: () => [{
+        space_name: 'old_space',
+        space_used_size: 78_900,
+      }],
+      setInterval: (handler, intervalMs) => {
+        expect(intervalMs).toBe(10_000)
+        sample = handler
+        return interval
+      },
+      clearInterval: jest.fn(),
+    }
+
+    const dispose = createRuntimeMetricsSampler(sources)
+    sample()
+
+    expect(delay.enable).toHaveBeenCalledTimes(1)
+    expect(interval.unref).toHaveBeenCalledTimes(1)
+    expect(points).toEqual([
+      {
+        kind: 'gauge',
+        name: 'nodejs.eventloop.utilization',
+        value: 0.75,
+        unit: '1',
+      },
+      {
+        kind: 'gauge',
+        name: 'nodejs.eventloop.delay.p50',
+        value: 0.05,
+        unit: 's',
+      },
+      {
+        kind: 'gauge',
+        name: 'nodejs.eventloop.delay.p90',
+        value: 0.09,
+        unit: 's',
+      },
+      {
+        kind: 'gauge',
+        name: 'nodejs.eventloop.delay.p99',
+        value: 0.099,
+        unit: 's',
+      },
+      {
+        kind: 'gauge',
+        name: 'process.memory.usage',
+        value: 123_456,
+        unit: 'By',
+      },
+      {
+        kind: 'gauge',
+        name: 'v8js.memory.heap.used',
+        value: 78_900,
+        labels: { 'v8js.heap.space.name': 'old_space' },
+        unit: 'By',
+      },
+    ])
+    expect(collectPool).toHaveBeenCalledTimes(1)
+    expect(delay.reset).toHaveBeenCalledTimes(1)
+
+    dispose()
+
+    expect(sources.clearInterval).toHaveBeenCalledWith(interval)
+    expect(delay.disable).toHaveBeenCalledTimes(1)
+  })
+
+  it('normalizes non-finite delay percentiles to zero', () => {
+    const points: TelemetryMetricPoint[] = []
+    registerTelemetryRuntime(createRuntime((point) => points.push(point)))
+    let sample = () => {}
+    const interval = { unref: jest.fn() } as unknown as ReturnType<typeof setInterval>
+    const delay: EventLoopDelayMonitor = {
+      enable: jest.fn(),
+      disable: jest.fn(),
+      percentile: () => Number.NaN,
+      reset: jest.fn(),
+    }
+    const sources: RuntimeMetricSources = {
+      createEventLoopDelayMonitor: () => delay,
+      eventLoopUtilization: () => ({ idle: 0, active: 0, utilization: 0 }),
+      memoryUsage: () => ({ rss: 0 }),
+      heapSpaceStatistics: () => [],
+      setInterval: (handler) => {
+        sample = handler
+        return interval
+      },
+      clearInterval: jest.fn(),
+    }
+
+    const dispose = createRuntimeMetricsSampler(sources)
+    sample()
+    dispose()
+
+    expect(points.filter((point) => point.name.startsWith('nodejs.eventloop.delay.')))
+      .toEqual([
+        { kind: 'gauge', name: 'nodejs.eventloop.delay.p50', value: 0, unit: 's' },
+        { kind: 'gauge', name: 'nodejs.eventloop.delay.p90', value: 0, unit: 's' },
+        { kind: 'gauge', name: 'nodejs.eventloop.delay.p99', value: 0, unit: 's' },
+      ])
+  })
+
+  it.each([false, true])('reports sampling failures, recovers, and disposes once (reporting throws: %s)', (reportingThrows) => {
+    const failure = new Error('[internal] memory sample failed')
+    const reportError = jest.fn(() => {
+      if (reportingThrows) throw new Error('[internal] reporting sink failed')
+    })
+    const points: TelemetryMetricPoint[] = []
+    registerTelemetryRuntime({ ...createRuntime((point) => points.push(point)), reportError })
+    let sample = () => {}
+    const interval = { unref: jest.fn() } as unknown as ReturnType<typeof setInterval>
+    const delay: EventLoopDelayMonitor = {
+      enable: jest.fn(),
+      disable: jest.fn(),
+      percentile: () => 0,
+      reset: jest.fn(),
+    }
+    const sources: RuntimeMetricSources = {
+      createEventLoopDelayMonitor: () => delay,
+      eventLoopUtilization: () => ({ idle: 0, active: 0, utilization: 0 }),
+      memoryUsage: jest.fn().mockImplementationOnce(() => { throw failure }).mockReturnValue({ rss: 123 }),
+      heapSpaceStatistics: () => [],
+      setInterval: (handler) => {
+        sample = handler
+        return interval
+      },
+      clearInterval: jest.fn(),
+    }
+
+    const dispose = createRuntimeMetricsSampler(sources)
+    expect(sample).not.toThrow()
+    expect(sample).not.toThrow()
+    dispose()
+    dispose()
+
+    expect(reportError).toHaveBeenCalledWith(failure, {
+      module: 'telemetry',
+      code: 'telemetry.runtime_sampling_failed',
+    })
+    expect(points).toContainEqual({ kind: 'gauge', name: 'process.memory.usage', value: 123, unit: 'By' })
+    expect(delay.reset).toHaveBeenCalledTimes(2)
+    expect(delay.disable).toHaveBeenCalledTimes(1)
+    expect(sources.clearInterval).toHaveBeenCalledTimes(1)
+  })
+
+  it('shares one process sampler until every owner releases it', () => {
+    const interval = { unref: jest.fn() } as unknown as ReturnType<typeof setInterval>
+    const delay: EventLoopDelayMonitor = {
+      enable: jest.fn(),
+      disable: jest.fn(),
+      percentile: () => 0,
+      reset: jest.fn(),
+    }
+    const sources: RuntimeMetricSources = {
+      createEventLoopDelayMonitor: jest.fn(() => delay),
+      eventLoopUtilization: () => ({ idle: 0, active: 0, utilization: 0 }),
+      memoryUsage: () => ({ rss: 0 }),
+      heapSpaceStatistics: () => [],
+      setInterval: jest.fn(() => interval),
+      clearInterval: jest.fn(),
+    }
+
+    const releaseFirst = startRuntimeMetrics(sources)
+    const releaseSecond = startRuntimeMetrics(sources)
+
+    expect(sources.createEventLoopDelayMonitor).toHaveBeenCalledTimes(1)
+    expect(sources.setInterval).toHaveBeenCalledTimes(1)
+
+    releaseFirst()
+    expect(sources.clearInterval).not.toHaveBeenCalled()
+
+    releaseSecond()
+    releaseSecond()
+
+    expect(sources.clearInterval).toHaveBeenCalledTimes(1)
+    expect(delay.disable).toHaveBeenCalledTimes(1)
+  })
+})

package/src/init.ts

@@ -17,11 +17,14 @@ import { withSpan } from './facade/tracer'
 import { recordHttpDuration } from './facade/http'
 import { histogram } from './facade/meter'
 import { reportError } from './facade/report-error'
+import { startRuntimeMetrics } from './runtime-metrics'
 
 let initialized = false
+let initializing: Promise<void> | undefined
 let activeProvider: TelemetryProvider | undefined
 let disposeLoggerExtension: (() => void) | undefined
 let disposeRuntime: (() => void) | undefined
+let disposeRuntimeMetrics: (() => void) | undefined
 
 const logger = createLogger('telemetry')
 const OTLP_DEPENDENCY_UNAVAILABLE = Symbol.for('open-mercato.telemetry.otlp-dependency-unavailable')
@@ -46,7 +49,17 @@ class OtlpDependencyUnavailableError extends Error {
  */
 export async function initTelemetry(): Promise<void> {
   if (initialized) return
+  if (initializing) return initializing
 
+  let pending: Promise<void>
+  pending = initializeTelemetry().finally(() => {
+    if (initializing === pending) initializing = undefined
+  })
+  initializing = pending
+  return pending
+}
+
+async function initializeTelemetry(): Promise<void> {
   // Drop any env snapshot memoized BEFORE the host loaded its `.env` (the CLI
   // binary imports this package before dotenv runs) so init resolves the backend
   // from the actual, fully-loaded environment.
@@ -75,6 +88,7 @@ export async function initTelemetry(): Promise<void> {
   activeProvider = provider
   disposeLoggerExtension = registerTelemetryLogger(provider)
   disposeRuntime = registerTelemetryRuntime(createRuntime(provider))
+  disposeRuntimeMetrics = startRuntimeMetrics()
   initialized = true
 
   logger.info('Telemetry initialized', {
@@ -111,11 +125,26 @@ async function loadOtlpProvider(backend: TelemetryBackendName): Promise<Telemetr
 
 /** Flush + tear down the active backend (shutdown hook / `after()`). */
 export async function shutdownTelemetry(): Promise<void> {
+  if (initializing) {
+    try {
+      await initializing
+    } catch (err) {
+      try {
+        reportError(err, {
+          module: 'telemetry',
+          code: 'telemetry.initialization_failed',
+        })
+      } catch {}
+      logger.warn('Telemetry initialization failed before shutdown', { err })
+    }
+  }
   const provider = activeProvider
   activeProvider = undefined
   initialized = false
   disposeLoggerExtension?.()
   disposeLoggerExtension = undefined
+  disposeRuntimeMetrics?.()
+  disposeRuntimeMetrics = undefined
   disposeRuntime?.()
   disposeRuntime = undefined
   clearActiveProvider()
@@ -131,6 +160,7 @@ function createRuntime(provider: TelemetryProvider): TelemetryRuntime {
     continueTrace: (carrier, name, fn, options) =>
       continueTrace(carrier, name, () => fn(), options),
     withSpan: (name, fn, options) => withSpan(name, fn, options),
+    recordMetric: (point) => provider.recordMetric(point),
     recordHistogram: histogram,
     recordHttpDuration,
     reportError,
@@ -141,9 +171,12 @@ function createRuntime(provider: TelemetryProvider): TelemetryRuntime {
 /** Test-only: allow re-init in jest. */
 export function resetTelemetryInit(): void {
   initialized = false
+  initializing = undefined
   activeProvider = undefined
   disposeLoggerExtension?.()
   disposeLoggerExtension = undefined
+  disposeRuntimeMetrics?.()
+  disposeRuntimeMetrics = undefined
   disposeRuntime?.()
   disposeRuntime = undefined
 }

package/src/provider/otlp-provider.ts

@@ -23,6 +23,7 @@ import {
   type Counter,
   type Histogram,
   type Gauge,
+  type MetricOptions,
 } from '@opentelemetry/api'
 import { W3CTraceContextPropagator } from '@opentelemetry/core'
 import { logs, SeverityNumber } from '@opentelemetry/api-logs'
@@ -229,6 +230,22 @@ export type OtlpProviderOptions = {
  */
 export const PG_INSTRUMENTATION_OPTIONS = { enhancedDatabaseReporting: false } as const
 
+/**
+ * Bucket boundaries for every histogram recorded in seconds. Without explicit
+ * advice the SDK falls back to millisecond-scaled defaults (0, 5, 10 … 10000),
+ * which puts every realistic latency in the first bucket and leaves percentiles
+ * uncomputable. A superset of the semconv HTTP-duration advice, plus a 1 ms
+ * bucket for sub-millisecond pool acquisitions.
+ */
+export const SECONDS_HISTOGRAM_BUCKETS: readonly number[] = [
+  0.001, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,
+]
+
+function histogramOptions(unit: string | undefined): MetricOptions | undefined {
+  if (unit !== 's') return unit ? { unit } : undefined
+  return { unit, advice: { explicitBucketBoundaries: [...SECONDS_HISTOGRAM_BUCKETS] } }
+}
+
 export class OtlpProvider implements TelemetryProvider {
   /** The configured backend name (signoz | newrelic | otlp) — all OTLP, vendor differs only by endpoint. */
   readonly name: string
@@ -339,7 +356,7 @@ export class OtlpProvider implements TelemetryProvider {
         point.kind === 'counter'
           ? meter.createCounter(point.name, opts)
           : point.kind === 'histogram'
-            ? meter.createHistogram(point.name, opts)
+            ? meter.createHistogram(point.name, histogramOptions(point.unit))
             : meter.createGauge(point.name, opts)
       this.instruments.set(key, instrument)
     }

package/src/runtime-metrics.ts

@@ -0,0 +1,179 @@
+import { monitorEventLoopDelay, performance, type EventLoopUtilization } from 'node:perf_hooks'
+import { getHeapSpaceStatistics } from 'node:v8'
+import {
+  collectTelemetryMetrics,
+  getTelemetryRuntime,
+  recordTelemetryMetric,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const SAMPLE_INTERVAL_MS = 10_000
+const DELAY_RESOLUTION_MS = 20
+const NANOSECONDS_PER_SECOND = 1_000_000_000
+const GLOBAL_KEY = Symbol.for('@open-mercato/telemetry.runtimeMetrics')
+
+export type EventLoopDelayMonitor = {
+  enable(): void
+  disable(): void
+  percentile(percentile: number): number
+  reset(): void
+}
+
+export type HeapSpaceSample = {
+  space_name: string
+  space_used_size: number
+}
+
+export type RuntimeMetricSources = {
+  createEventLoopDelayMonitor(): EventLoopDelayMonitor
+  eventLoopUtilization(
+    first?: EventLoopUtilization,
+    second?: EventLoopUtilization,
+  ): EventLoopUtilization
+  memoryUsage(): { rss: number }
+  heapSpaceStatistics(): HeapSpaceSample[]
+  setInterval(handler: () => void, intervalMs: number): ReturnType<typeof setInterval>
+  clearInterval(interval: ReturnType<typeof setInterval>): void
+}
+
+type ActiveRuntimeSampler = {
+  references: number
+  dispose(): void
+}
+
+type RuntimeMetricsStore = {
+  active?: ActiveRuntimeSampler
+}
+
+const logger = createLogger('telemetry').child({ component: 'runtime-metrics' })
+
+const defaultSources: RuntimeMetricSources = {
+  createEventLoopDelayMonitor: () => monitorEventLoopDelay({ resolution: DELAY_RESOLUTION_MS }),
+  eventLoopUtilization: (first, second) => performance.eventLoopUtilization(first, second),
+  memoryUsage: () => process.memoryUsage(),
+  heapSpaceStatistics: () => getHeapSpaceStatistics(),
+  setInterval: (handler, intervalMs) => setInterval(handler, intervalMs),
+  clearInterval: (interval) => clearInterval(interval),
+}
+
+function store(): RuntimeMetricsStore {
+  const globalStore = globalThis as unknown as Record<symbol, RuntimeMetricsStore | undefined>
+  let current = globalStore[GLOBAL_KEY]
+  if (!current) {
+    current = {}
+    globalStore[GLOBAL_KEY] = current
+  }
+  return current
+}
+
+function secondsFromNanoseconds(value: number): number {
+  return Number.isFinite(value) ? Math.max(0, value) / NANOSECONDS_PER_SECOND : 0
+}
+
+export function createRuntimeMetricsSampler(
+  sources: RuntimeMetricSources = defaultSources,
+): () => void {
+  const delay = sources.createEventLoopDelayMonitor()
+  let previousUtilization = sources.eventLoopUtilization()
+  delay.enable()
+
+  const sample = () => {
+    try {
+      const currentUtilization = sources.eventLoopUtilization()
+      const intervalUtilization = sources.eventLoopUtilization(
+        currentUtilization,
+        previousUtilization,
+      )
+      previousUtilization = currentUtilization
+
+      recordTelemetryMetric({
+        kind: 'gauge',
+        name: 'nodejs.eventloop.utilization',
+        value: intervalUtilization.utilization,
+        unit: '1',
+      })
+      for (const percentile of [50, 90, 99]) {
+        recordTelemetryMetric({
+          kind: 'gauge',
+          name: `nodejs.eventloop.delay.p${percentile}`,
+          value: secondsFromNanoseconds(delay.percentile(percentile)),
+          unit: 's',
+        })
+      }
+
+      recordTelemetryMetric({
+        kind: 'gauge',
+        name: 'process.memory.usage',
+        value: sources.memoryUsage().rss,
+        unit: 'By',
+      })
+      for (const heapSpace of sources.heapSpaceStatistics()) {
+        recordTelemetryMetric({
+          kind: 'gauge',
+          name: 'v8js.memory.heap.used',
+          value: heapSpace.space_used_size,
+          labels: { 'v8js.heap.space.name': heapSpace.space_name },
+          unit: 'By',
+        })
+      }
+
+      collectTelemetryMetrics((err) => {
+        logger.warn('Runtime metric collector failed', { err })
+      })
+    } catch (err) {
+      try {
+        getTelemetryRuntime()?.reportError(err, {
+          module: 'telemetry',
+          code: 'telemetry.runtime_sampling_failed',
+        })
+      } catch {}
+      logger.warn('Runtime metric sampling failed', { err })
+    } finally {
+      delay.reset()
+    }
+  }
+
+  const interval = sources.setInterval(sample, SAMPLE_INTERVAL_MS)
+  interval.unref?.()
+
+  let disposed = false
+  return () => {
+    if (disposed) return
+    disposed = true
+    sources.clearInterval(interval)
+    delay.disable()
+  }
+}
+
+export function startRuntimeMetrics(
+  sources: RuntimeMetricSources = defaultSources,
+): () => void {
+  const current = store()
+  if (!current.active) {
+    current.active = {
+      references: 0,
+      dispose: createRuntimeMetricsSampler(sources),
+    }
+  }
+
+  const active = current.active
+  active.references += 1
+  let released = false
+
+  return () => {
+    if (released) return
+    released = true
+    active.references -= 1
+    if (active.references > 0) return
+    active.dispose()
+    const latest = store()
+    if (latest.active === active) latest.active = undefined
+  }
+}
+
+/** Test-only: tear down the process-wide sampler regardless of reference count. */
+export function resetRuntimeMetrics(): void {
+  const current = store()
+  current.active?.dispose()
+  current.active = undefined
+}