@open-mercato/telemetry 0.8.1-develop.7297.1.67605e74f9 → 0.8.1-develop.7441.1.b42958b98c

package/README.md

@@ -170,7 +170,13 @@ export async function register(): Promise<void> {
   if (process.env.NEXT_RUNTIME === 'nodejs' && isTelemetryBackendEnabled()) {
     const { registerTelemetryForNextjs } =
       await import('@open-mercato/telemetry/nextjs')
-    await registerTelemetryForNextjs()
+    try {
+      await registerTelemetryForNextjs()
+    } catch (err) {
+      const nodeProcess = process
+      nodeProcess.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`)
+      nodeProcess.exit(1)
+    }
   }
 }
 ```

package/dist/init.js

@@ -13,12 +13,24 @@ 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 { histogram } from "./facade/meter.js";
 import { reportError } from "./facade/report-error.js";
 let initialized = false;
 let activeProvider;
 let disposeLoggerExtension;
 let disposeRuntime;
 const logger = createLogger("telemetry");
+const OTLP_DEPENDENCY_UNAVAILABLE = /* @__PURE__ */ Symbol.for("open-mercato.telemetry.otlp-dependency-unavailable");
+class OtlpDependencyUnavailableError extends Error {
+  constructor(backend, cause) {
+    super(
+      `[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.`,
+      { cause }
+    );
+    this.name = "OtlpDependencyUnavailableError";
+    Object.defineProperty(this, OTLP_DEPENDENCY_UNAVAILABLE, { value: true });
+  }
+}
 async function initTelemetry() {
   if (initialized) return;
   resetTelemetryEnvCache();
@@ -52,15 +64,13 @@ async function resolveProvider(backend) {
   return void 0;
 }
 async function loadOtlpProvider(backend) {
+  let mod;
   try {
-    const mod = await import("./provider/otlp-provider.js");
-    return new mod.OtlpProvider({}, backend);
-  } catch (err) {
-    logger.warn("OTLP provider unavailable; falling back to console", {
-      reason: err instanceof Error ? err.message : String(err)
-    });
-    return new ConsoleProvider();
+    mod = await import("./provider/otlp-provider.js");
+  } catch (error) {
+    throw new OtlpDependencyUnavailableError(backend, error);
   }
+  return new mod.OtlpProvider({}, backend);
 }
 async function shutdownTelemetry() {
   const provider = activeProvider;
@@ -79,6 +89,7 @@ function createRuntime(provider) {
     captureTraceContext,
     continueTrace: (carrier, name, fn, options) => continueTrace(carrier, name, () => fn(), options),
     withSpan: (name, fn, options) => withSpan(name, fn, options),
+    recordHistogram: histogram,
     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 { 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;",
+  "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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",
   "names": []
 }

package/dist/nextjs.js

@@ -3,6 +3,10 @@ import { createLogger } from "@open-mercato/shared/lib/logger";
 import { telemetryServerExternalPackages } from "./nextjs-config.js";
 import { recordHttpDuration } from "./facade/http.js";
 const logger = createLogger("telemetry");
+const OTLP_DEPENDENCY_UNAVAILABLE = /* @__PURE__ */ Symbol.for("open-mercato.telemetry.otlp-dependency-unavailable");
+function isOtlpDependencyUnavailableError(error) {
+  return error instanceof Error && Reflect.get(error, OTLP_DEPENDENCY_UNAVAILABLE) === true;
+}
 async function registerTelemetryForNextjs() {
   if (process.env.NEXT_RUNTIME && process.env.NEXT_RUNTIME !== "nodejs") return;
   if (!isTelemetryBackendEnabled()) return;
@@ -10,6 +14,7 @@ async function registerTelemetryForNextjs() {
   try {
     await initTelemetry();
   } catch (error) {
+    if (isOtlpDependencyUnavailableError(error)) throw error;
     logger.warn("Init from Next.js instrumentation failed", { err: error });
     return;
   }

package/dist/nextjs.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/nextjs.ts"],
-  "sourcesContent": ["/**\n * Next.js wiring helpers for `@open-mercato/telemetry`.\n *\n * Runtime helpers for an enabled Next.js telemetry integration. Build-time\n * config belongs in `@open-mercato/telemetry/nextjs-config`, which has no\n * runtime imports.\n */\nimport { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nexport { telemetryServerExternalPackages } from './nextjs-config'\nexport { recordHttpDuration } from './facade/http'\n\nconst logger = createLogger('telemetry')\n\n/**\n * One-line telemetry bootstrap for a Next.js `instrumentation.ts`. Initializes\n * the active backend (no-op unless `TELEMETRY_BACKEND` is set), degrades to no\n * telemetry on init failure (never bubbles a rejection out of Next's\n * `register()`), and registers a best-effort flush on `SIGTERM`/`SIGINT`. Skips\n * the edge runtime \u2014 the OTEL NodeSDK is Node-only \u2014 so callers may import it\n * unconditionally, though gating the dynamic import on\n * `NEXT_RUNTIME === 'nodejs'` also keeps the SDK off the edge bundle.\n */\nexport async function registerTelemetryForNextjs(): Promise<void> {\n  if (process.env.NEXT_RUNTIME && process.env.NEXT_RUNTIME !== 'nodejs') return\n  if (!isTelemetryBackendEnabled()) return\n  const { initTelemetry, shutdownTelemetry } = await import('./init')\n  try {\n    await initTelemetry()\n  } catch (error) {\n    logger.warn('Init from Next.js instrumentation failed', { err: error })\n    return\n  }\n  // A signal listener suppresses Node's default termination, so after the\n  // best-effort flush the handler re-raises the signal. `once` has already\n  // removed this listener by then, so the re-raise falls through to the default\n  // terminate (or to another component's own handler, e.g. Next's).\n  const flush = (signal: NodeJS.Signals) => {\n    void shutdownTelemetry()\n      .catch(() => {})\n      .finally(() => {\n        process.kill(process.pid, signal)\n      })\n  }\n  process.once('SIGTERM', flush)\n  process.once('SIGINT', flush)\n}\n"],
-  "mappings": "AAOA,SAAS,iCAAiC;AAC1C,SAAS,oBAAoB;AAC7B,SAAS,uCAAuC;AAChD,SAAS,0BAA0B;AAEnC,MAAM,SAAS,aAAa,WAAW;AAWvC,eAAsB,6BAA4C;AAChE,MAAI,QAAQ,IAAI,gBAAgB,QAAQ,IAAI,iBAAiB,SAAU;AACvE,MAAI,CAAC,0BAA0B,EAAG;AAClC,QAAM,EAAE,eAAe,kBAAkB,IAAI,MAAM,OAAO,QAAQ;AAClE,MAAI;AACF,UAAM,cAAc;AAAA,EACtB,SAAS,OAAO;AACd,WAAO,KAAK,4CAA4C,EAAE,KAAK,MAAM,CAAC;AACtE;AAAA,EACF;AAKA,QAAM,QAAQ,CAAC,WAA2B;AACxC,SAAK,kBAAkB,EACpB,MAAM,MAAM;AAAA,IAAC,CAAC,EACd,QAAQ,MAAM;AACb,cAAQ,KAAK,QAAQ,KAAK,MAAM;AAAA,IAClC,CAAC;AAAA,EACL;AACA,UAAQ,KAAK,WAAW,KAAK;AAC7B,UAAQ,KAAK,UAAU,KAAK;AAC9B;",
+  "sourcesContent": ["/**\n * Next.js wiring helpers for `@open-mercato/telemetry`.\n *\n * Runtime helpers for an enabled Next.js telemetry integration. Build-time\n * config belongs in `@open-mercato/telemetry/nextjs-config`, which has no\n * runtime imports.\n */\nimport { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nexport { telemetryServerExternalPackages } from './nextjs-config'\nexport { recordHttpDuration } from './facade/http'\n\nconst logger = createLogger('telemetry')\nconst OTLP_DEPENDENCY_UNAVAILABLE = Symbol.for('open-mercato.telemetry.otlp-dependency-unavailable')\n\nfunction isOtlpDependencyUnavailableError(error: unknown): boolean {\n  return error instanceof Error && Reflect.get(error, OTLP_DEPENDENCY_UNAVAILABLE) === true\n}\n\n/**\n * One-line telemetry bootstrap for a Next.js `instrumentation.ts`. Initializes\n * the active backend (no-op unless `TELEMETRY_BACKEND` is set), propagates an\n * explicit OTLP missing-dependency failure, degrades to no telemetry for other\n * initialization failures, and registers a best-effort flush on\n * `SIGTERM`/`SIGINT`. Skips the edge runtime \u2014 the OTEL NodeSDK is Node-only \u2014\n * so callers may import it unconditionally, though gating the dynamic import on\n * `NEXT_RUNTIME === 'nodejs'` also keeps the SDK off the edge bundle.\n */\nexport async function registerTelemetryForNextjs(): Promise<void> {\n  if (process.env.NEXT_RUNTIME && process.env.NEXT_RUNTIME !== 'nodejs') return\n  if (!isTelemetryBackendEnabled()) return\n  const { initTelemetry, shutdownTelemetry } = await import('./init')\n  try {\n    await initTelemetry()\n  } catch (error) {\n    if (isOtlpDependencyUnavailableError(error)) throw error\n    logger.warn('Init from Next.js instrumentation failed', { err: error })\n    return\n  }\n  // A signal listener suppresses Node's default termination, so after the\n  // best-effort flush the handler re-raises the signal. `once` has already\n  // removed this listener by then, so the re-raise falls through to the default\n  // terminate (or to another component's own handler, e.g. Next's).\n  const flush = (signal: NodeJS.Signals) => {\n    void shutdownTelemetry()\n      .catch(() => {})\n      .finally(() => {\n        process.kill(process.pid, signal)\n      })\n  }\n  process.once('SIGTERM', flush)\n  process.once('SIGINT', flush)\n}\n"],
+  "mappings": "AAOA,SAAS,iCAAiC;AAC1C,SAAS,oBAAoB;AAC7B,SAAS,uCAAuC;AAChD,SAAS,0BAA0B;AAEnC,MAAM,SAAS,aAAa,WAAW;AACvC,MAAM,8BAA8B,uBAAO,IAAI,oDAAoD;AAEnG,SAAS,iCAAiC,OAAyB;AACjE,SAAO,iBAAiB,SAAS,QAAQ,IAAI,OAAO,2BAA2B,MAAM;AACvF;AAWA,eAAsB,6BAA4C;AAChE,MAAI,QAAQ,IAAI,gBAAgB,QAAQ,IAAI,iBAAiB,SAAU;AACvE,MAAI,CAAC,0BAA0B,EAAG;AAClC,QAAM,EAAE,eAAe,kBAAkB,IAAI,MAAM,OAAO,QAAQ;AAClE,MAAI;AACF,UAAM,cAAc;AAAA,EACtB,SAAS,OAAO;AACd,QAAI,iCAAiC,KAAK,EAAG,OAAM;AACnD,WAAO,KAAK,4CAA4C,EAAE,KAAK,MAAM,CAAC;AACtE;AAAA,EACF;AAKA,QAAM,QAAQ,CAAC,WAA2B;AACxC,SAAK,kBAAkB,EACpB,MAAM,MAAM;AAAA,IAAC,CAAC,EACd,QAAQ,MAAM;AACb,cAAQ,KAAK,QAAQ,KAAK,MAAM;AAAA,IAClC,CAAC;AAAA,EACL;AACA,UAAQ,KAAK,WAAW,KAAK;AAC7B,UAAQ,KAAK,UAAU,KAAK;AAC9B;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/telemetry",
-  "version": "0.8.1-develop.7297.1.67605e74f9",
+  "version": "0.8.1-develop.7441.1.b42958b98c",
   "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.8.1-develop.7297.1.67605e74f9"
+    "@open-mercato/shared": "0.8.1-develop.7441.1.b42958b98c"
   },
   "peerDependencies": {
     "react": ">=18.0.0"

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

@@ -25,7 +25,7 @@ function provider(name = 'noop'): TelemetryProvider {
     inject: () => {},
     runInRemoteSpan: (_carrier, _name, _options, fn) => fn(NOOP_SPAN),
     emitLog: () => {},
-    recordMetric: () => {},
+    recordMetric: jest.fn(),
   }
 }
 
@@ -77,4 +77,26 @@ describe('telemetry explicit opt-in boundary', () => {
     expect(getLoggerExtension()).toBeDefined()
     expect(getTelemetryRuntime()).toBeDefined()
   })
+
+  it('wires shared runtime histograms to the active provider', async () => {
+    const customConsole = provider('console')
+    registerProvider(customConsole)
+    process.env.TELEMETRY_BACKEND = 'console'
+
+    await initTelemetry()
+    getTelemetryRuntime()?.recordHistogram?.(
+      'om.enricher.duration',
+      0.25,
+      { 'enricher.id': 'customers.people' },
+      's',
+    )
+
+    expect(customConsole.recordMetric).toHaveBeenCalledWith({
+      kind: 'histogram',
+      name: 'om.enricher.duration',
+      value: 0.25,
+      labels: { 'enricher.id': 'customers.people' },
+      unit: 's',
+    })
+  })
 })

package/src/__tests__/init-otlp-dependency.test.ts

@@ -0,0 +1,208 @@
+import type {
+  Attributes,
+  LogRecord,
+  MetricPoint,
+  Span,
+  SpanOptions,
+  TelemetryProvider,
+  TraceCarrier,
+  TraceContext,
+} from '../types'
+
+function createSpan(): Span {
+  return {
+    setAttribute(_key: string, _value: string | number | boolean): void {},
+    setAttributes(_attributes: Attributes): void {},
+    recordException(_error: unknown): void {},
+    setStatus(_status: 'ok' | 'error', _message?: string): void {},
+    end(): void {},
+  }
+}
+
+function createProvider(name = 'otlp'): TelemetryProvider {
+  const span = createSpan()
+  return {
+    name,
+    supports: ['traces', 'metrics', 'logs', 'errors'],
+    start: jest.fn(async () => {}),
+    shutdown: jest.fn(async () => {}),
+    runInSpan<T>(_name: string, _options: SpanOptions, operation: (activeSpan: Span) => T): T {
+      return operation(span)
+    },
+    activeSpan(): Span | undefined {
+      return span
+    },
+    activeTraceContext(): TraceContext | undefined {
+      return undefined
+    },
+    inject(_carrier: TraceCarrier): void {},
+    runInRemoteSpan<T>(
+      _carrier: TraceCarrier,
+      _name: string,
+      _options: SpanOptions,
+      operation: (activeSpan: Span) => T,
+    ): T {
+      return operation(span)
+    },
+    emitLog(_record: LogRecord): void {},
+    recordMetric(_point: MetricPoint): void {},
+  }
+}
+
+describe('OTLP dependency bootstrap', () => {
+  const originalBackend = process.env.TELEMETRY_BACKEND
+  let shutdownTelemetry: (() => Promise<void>) | undefined
+
+  beforeEach(() => {
+    jest.resetModules()
+    jest.restoreAllMocks()
+    shutdownTelemetry = undefined
+    delete process.env.TELEMETRY_BACKEND
+  })
+
+  afterEach(async () => {
+    await shutdownTelemetry?.()
+    if (originalBackend === undefined) delete process.env.TELEMETRY_BACKEND
+    else process.env.TELEMETRY_BACKEND = originalBackend
+    jest.dontMock('../provider/console-provider')
+    jest.dontMock('../provider/otlp-provider')
+    jest.dontMock('../init')
+    jest.resetModules()
+    jest.restoreAllMocks()
+  })
+
+  it.each(['otlp', 'signoz', 'newrelic'])('fails clearly when %s dependencies cannot load', async (backend) => {
+    const importCause = new Error('simulated missing package at /private/runtime with token=secret-value')
+    const consoleProvider = jest.fn()
+    jest.doMock('../provider/console-provider', () => ({ ConsoleProvider: consoleProvider }))
+    jest.doMock('../provider/otlp-provider', () => {
+      throw importCause
+    })
+    const telemetry = await import('../init')
+    shutdownTelemetry = telemetry.shutdownTelemetry
+    process.env.TELEMETRY_BACKEND = backend
+
+    const failure: unknown = await telemetry.initTelemetry().catch((error: unknown) => error)
+
+    expect(failure).toBeInstanceOf(Error)
+    expect((failure as Error).message).toContain(`OTLP telemetry backend "${backend}" cannot start`)
+    expect((failure as Error).message).toContain('Install optional dependencies')
+    expect((failure as Error).message).not.toContain('/private/runtime')
+    expect((failure as Error).message).not.toContain('secret-value')
+    expect((failure as Error).cause).toBe(importCause)
+    expect(consoleProvider).not.toHaveBeenCalled()
+    const [{ getActiveProvider }, { getLoggerExtension }, { getTelemetryRuntime }] = await Promise.all([
+      import('../provider/registry'),
+      import('@open-mercato/shared/lib/logger'),
+      import('@open-mercato/shared/lib/telemetry/runtime'),
+    ])
+    expect(getActiveProvider().name).toBe('noop')
+    expect(getLoggerExtension()).toBeUndefined()
+    expect(getTelemetryRuntime()).toBeUndefined()
+  })
+
+  it('starts the dynamically loaded provider when OTLP dependencies are available', async () => {
+    const provider = createProvider()
+    const OtlpProvider = jest.fn(() => provider)
+    jest.doMock('../provider/otlp-provider', () => ({ OtlpProvider }))
+    const telemetry = await import('../init')
+    shutdownTelemetry = telemetry.shutdownTelemetry
+    process.env.TELEMETRY_BACKEND = 'otlp'
+
+    await telemetry.initTelemetry()
+
+    expect(OtlpProvider).toHaveBeenCalledWith({}, 'otlp')
+    expect(provider.start).toHaveBeenCalledTimes(1)
+  })
+
+  it.each([undefined, 'noop'])('does not resolve OTLP dependencies when telemetry is %s', async (backend) => {
+    const loadOtlpModule = jest.fn(() => ({ OtlpProvider: jest.fn() }))
+    jest.doMock('../provider/otlp-provider', loadOtlpModule)
+    const telemetry = await import('../init')
+    shutdownTelemetry = telemetry.shutdownTelemetry
+    if (backend === undefined) delete process.env.TELEMETRY_BACKEND
+    else process.env.TELEMETRY_BACKEND = backend
+
+    await telemetry.initTelemetry()
+
+    expect(loadOtlpModule).not.toHaveBeenCalled()
+  })
+
+  it('can retry initialization after a dependency load failure', async () => {
+    const provider = createProvider()
+    const importCause = new Error('simulated first-load failure')
+    let loadAttempts = 0
+    jest.doMock('../provider/otlp-provider', () => {
+      loadAttempts += 1
+      if (loadAttempts === 1) throw importCause
+      return { OtlpProvider: jest.fn(() => provider) }
+    })
+    const telemetry = await import('../init')
+    shutdownTelemetry = telemetry.shutdownTelemetry
+    process.env.TELEMETRY_BACKEND = 'otlp'
+
+    await expect(telemetry.initTelemetry()).rejects.toHaveProperty('cause', importCause)
+    await telemetry.initTelemetry()
+
+    expect(loadAttempts).toBe(2)
+    expect(provider.start).toHaveBeenCalledTimes(1)
+  })
+
+  it('propagates a dependency load failure through the standard Next.js bootstrap', async () => {
+    const importCause = new Error('simulated missing package')
+    jest.doMock('../provider/otlp-provider', () => {
+      throw importCause
+    })
+    const telemetry = await import('../init')
+    shutdownTelemetry = telemetry.shutdownTelemetry
+    const { registerTelemetryForNextjs } = await import('../nextjs')
+    process.env.TELEMETRY_BACKEND = 'otlp'
+
+    await expect(registerTelemetryForNextjs()).rejects.toMatchObject({
+      name: 'OtlpDependencyUnavailableError',
+      cause: importCause,
+    })
+  })
+
+  it('keeps unrelated provider initialization failures best effort in Next.js', async () => {
+    const startupFailure = new Error('collector configuration rejected')
+    const initTelemetry = jest.fn(async () => {
+      throw startupFailure
+    })
+    jest.doMock('../init', () => ({
+      initTelemetry,
+      shutdownTelemetry: jest.fn(async () => {}),
+    }))
+    const { registerTelemetryForNextjs } = await import('../nextjs')
+    process.env.TELEMETRY_BACKEND = 'otlp'
+
+    await expect(registerTelemetryForNextjs()).resolves.toBeUndefined()
+    expect(initTelemetry).toHaveBeenCalledTimes(1)
+  })
+
+  it('preserves a provider startup failure and can retry it without misclassifying dependencies', async () => {
+    const provider = createProvider()
+    const startupFailure = new Error('collector configuration rejected')
+    jest.mocked(provider.start)
+      .mockRejectedValueOnce(startupFailure)
+      .mockResolvedValueOnce(undefined)
+    jest.doMock('../provider/otlp-provider', () => ({
+      OtlpProvider: jest.fn(() => provider),
+    }))
+    const telemetry = await import('../init')
+    shutdownTelemetry = telemetry.shutdownTelemetry
+    process.env.TELEMETRY_BACKEND = 'otlp'
+
+    await expect(telemetry.initTelemetry()).rejects.toBe(startupFailure)
+    const [{ getActiveProvider }, { getTelemetryRuntime }] = await Promise.all([
+      import('../provider/registry'),
+      import('@open-mercato/shared/lib/telemetry/runtime'),
+    ])
+    expect(getActiveProvider().name).toBe('noop')
+    expect(getTelemetryRuntime()).toBeUndefined()
+
+    await telemetry.initTelemetry()
+
+    expect(provider.start).toHaveBeenCalledTimes(2)
+  })
+})

package/src/init.ts

@@ -15,6 +15,7 @@ import { registerTelemetryLogger } from './facade/logger-bridge'
 import { captureTraceContext, continueTrace } from './facade/propagation'
 import { withSpan } from './facade/tracer'
 import { recordHttpDuration } from './facade/http'
+import { histogram } from './facade/meter'
 import { reportError } from './facade/report-error'
 
 let initialized = false
@@ -23,6 +24,18 @@ let disposeLoggerExtension: (() => void) | undefined
 let disposeRuntime: (() => void) | undefined
 
 const logger = createLogger('telemetry')
+const OTLP_DEPENDENCY_UNAVAILABLE = Symbol.for('open-mercato.telemetry.otlp-dependency-unavailable')
+
+class OtlpDependencyUnavailableError extends Error {
+  constructor(backend: TelemetryBackendName, cause: unknown) {
+    super(
+      `[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.`,
+      { cause },
+    )
+    this.name = 'OtlpDependencyUnavailableError'
+    Object.defineProperty(this, OTLP_DEPENDENCY_UNAVAILABLE, { value: true })
+  }
+}
 
 /**
  * One-shot bootstrap, invoked from `apps/mercato/instrumentation.ts` (web) and,
@@ -82,19 +95,18 @@ async function resolveProvider(backend: TelemetryBackendName): Promise<Telemetry
 
 /**
  * Dynamically load the OTLP provider so `@opentelemetry/*` (optionalDependencies)
- * is imported only when an OTLP backend is selected. Falls back to console if
- * the OTEL packages are absent rather than crashing the app.
+ * is imported only when an OTLP backend is selected. An explicit OTLP selection
+ * must fail at startup when those packages are unavailable instead of silently
+ * switching telemetry semantics.
  */
 async function loadOtlpProvider(backend: TelemetryBackendName): Promise<TelemetryProvider> {
+  let mod: typeof import('./provider/otlp-provider')
   try {
-    const mod = await import('./provider/otlp-provider')
-    return new mod.OtlpProvider({}, backend)
-  } catch (err) {
-    logger.warn('OTLP provider unavailable; falling back to console', {
-      reason: err instanceof Error ? err.message : String(err),
-    })
-    return new ConsoleProvider()
+    mod = await import('./provider/otlp-provider')
+  } catch (error) {
+    throw new OtlpDependencyUnavailableError(backend, error)
   }
+  return new mod.OtlpProvider({}, backend)
 }
 
 /** Flush + tear down the active backend (shutdown hook / `after()`). */
@@ -119,6 +131,7 @@ function createRuntime(provider: TelemetryProvider): TelemetryRuntime {
     continueTrace: (carrier, name, fn, options) =>
       continueTrace(carrier, name, () => fn(), options),
     withSpan: (name, fn, options) => withSpan(name, fn, options),
+    recordHistogram: histogram,
     recordHttpDuration,
     reportError,
     shutdown: shutdownTelemetry,

package/src/nextjs.ts

@@ -11,14 +11,19 @@ export { telemetryServerExternalPackages } from './nextjs-config'
 export { recordHttpDuration } from './facade/http'
 
 const logger = createLogger('telemetry')
+const OTLP_DEPENDENCY_UNAVAILABLE = Symbol.for('open-mercato.telemetry.otlp-dependency-unavailable')
+
+function isOtlpDependencyUnavailableError(error: unknown): boolean {
+  return error instanceof Error && Reflect.get(error, OTLP_DEPENDENCY_UNAVAILABLE) === true
+}
 
 /**
  * One-line telemetry bootstrap for a Next.js `instrumentation.ts`. Initializes
- * the active backend (no-op unless `TELEMETRY_BACKEND` is set), degrades to no
- * telemetry on init failure (never bubbles a rejection out of Next's
- * `register()`), and registers a best-effort flush on `SIGTERM`/`SIGINT`. Skips
- * the edge runtime — the OTEL NodeSDK is Node-only — so callers may import it
- * unconditionally, though gating the dynamic import on
+ * the active backend (no-op unless `TELEMETRY_BACKEND` is set), propagates an
+ * explicit OTLP missing-dependency failure, degrades to no telemetry for other
+ * initialization failures, and registers a best-effort flush on
+ * `SIGTERM`/`SIGINT`. Skips the edge runtime — the OTEL NodeSDK is Node-only —
+ * so callers may import it unconditionally, though gating the dynamic import on
  * `NEXT_RUNTIME === 'nodejs'` also keeps the SDK off the edge bundle.
  */
 export async function registerTelemetryForNextjs(): Promise<void> {
@@ -28,6 +33,7 @@ export async function registerTelemetryForNextjs(): Promise<void> {
   try {
     await initTelemetry()
   } catch (error) {
+    if (isOtlpDependencyUnavailableError(error)) throw error
     logger.warn('Init from Next.js instrumentation failed', { err: error })
     return
   }