@open-mercato/telemetry 0.6.7-develop.6834.1.e76f4b8cbc

package/dist/provider/registry.js

@@ -0,0 +1,40 @@
+import { NoopProvider } from "./noop-provider.js";
+const GLOBAL_KEY = /* @__PURE__ */ Symbol.for("@open-mercato/telemetry.providerRegistry");
+function store() {
+  const g = globalThis;
+  let reg = g[GLOBAL_KEY];
+  if (!reg) {
+    reg = { active: new NoopProvider(), registered: /* @__PURE__ */ new Map() };
+    g[GLOBAL_KEY] = reg;
+  }
+  return reg;
+}
+function registerProvider(provider) {
+  store().registered.set(provider.name, provider);
+}
+function getRegisteredProvider(name) {
+  return store().registered.get(name);
+}
+function getActiveProvider() {
+  return store().active;
+}
+function setActiveProvider(provider) {
+  store().active = provider;
+}
+function clearActiveProvider() {
+  store().active = new NoopProvider();
+}
+function resetActiveProvider() {
+  const reg = store();
+  clearActiveProvider();
+  reg.registered.clear();
+}
+export {
+  clearActiveProvider,
+  getActiveProvider,
+  getRegisteredProvider,
+  registerProvider,
+  resetActiveProvider,
+  setActiveProvider
+};
+//# sourceMappingURL=registry.js.map

package/dist/provider/registry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/provider/registry.ts"],
+  "sourcesContent": ["import type { TelemetryProvider } from '../types'\nimport { NoopProvider } from './noop-provider'\n\n/**\n * The active provider is a PROCESS-WIDE singleton, stored on `globalThis` rather\n * than in a module variable. This is load-bearing: the worker bootstrap\n * esbuild-bundles the generated DI registry into a `.mjs` that can inline a\n * *private copy* of this module, while job handlers are dynamic-imported as\n * source and use the *source copy*. With module-level state, `initTelemetry()`\n * would set the provider on one copy while the handlers read a still-noop other\n * \u2014 so worker logs/spans would never reach the backend. Keying the state on a\n * global symbol makes every copy share one provider. Mirrors the framework's own\n * DI-registrar global.\n */\nconst GLOBAL_KEY = Symbol.for('@open-mercato/telemetry.providerRegistry')\n\ntype ProviderRegistry = {\n  active: TelemetryProvider\n  registered: Map<string, TelemetryProvider>\n}\n\nfunction store(): ProviderRegistry {\n  const g = globalThis as unknown as Record<symbol, ProviderRegistry | undefined>\n  let reg = g[GLOBAL_KEY]\n  if (!reg) {\n    reg = { active: new NoopProvider(), registered: new Map() }\n    g[GLOBAL_KEY] = reg\n  }\n  return reg\n}\n\n/** Plug a custom backend before `initTelemetry()` (e.g. tests or a bespoke sink). */\nexport function registerProvider(provider: TelemetryProvider): void {\n  store().registered.set(provider.name, provider)\n}\n\nexport function getRegisteredProvider(name: string): TelemetryProvider | undefined {\n  return store().registered.get(name)\n}\n\nexport function getActiveProvider(): TelemetryProvider {\n  return store().active\n}\n\n/** Set the active provider. Called by `initTelemetry()`. */\nexport function setActiveProvider(provider: TelemetryProvider): void {\n  store().active = provider\n}\n\n/** Restore only the active provider while preserving custom registrations. */\nexport function clearActiveProvider(): void {\n  store().active = new NoopProvider()\n}\n\n/** Test-only: restore the default no-op provider. */\nexport function resetActiveProvider(): void {\n  const reg = store()\n  clearActiveProvider()\n  reg.registered.clear()\n}\n"],
+  "mappings": "AACA,SAAS,oBAAoB;AAa7B,MAAM,aAAa,uBAAO,IAAI,0CAA0C;AAOxE,SAAS,QAA0B;AACjC,QAAM,IAAI;AACV,MAAI,MAAM,EAAE,UAAU;AACtB,MAAI,CAAC,KAAK;AACR,UAAM,EAAE,QAAQ,IAAI,aAAa,GAAG,YAAY,oBAAI,IAAI,EAAE;AAC1D,MAAE,UAAU,IAAI;AAAA,EAClB;AACA,SAAO;AACT;AAGO,SAAS,iBAAiB,UAAmC;AAClE,QAAM,EAAE,WAAW,IAAI,SAAS,MAAM,QAAQ;AAChD;AAEO,SAAS,sBAAsB,MAA6C;AACjF,SAAO,MAAM,EAAE,WAAW,IAAI,IAAI;AACpC;AAEO,SAAS,oBAAuC;AACrD,SAAO,MAAM,EAAE;AACjB;AAGO,SAAS,kBAAkB,UAAmC;AACnE,QAAM,EAAE,SAAS;AACnB;AAGO,SAAS,sBAA4B;AAC1C,QAAM,EAAE,SAAS,IAAI,aAAa;AACpC;AAGO,SAAS,sBAA4B;AAC1C,QAAM,MAAM,MAAM;AAClB,sBAAoB;AACpB,MAAI,WAAW,MAAM;AACvB;",
+  "names": []
+}

package/dist/provider/run-span.js

@@ -0,0 +1,34 @@
+function isThenable(value) {
+  return value != null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+function runSpan(span, fn) {
+  let result;
+  try {
+    result = fn(span);
+  } catch (error) {
+    span.recordException(error);
+    span.setStatus("error");
+    span.end();
+    throw error;
+  }
+  if (isThenable(result)) {
+    return result.then(
+      (value) => {
+        span.end();
+        return value;
+      },
+      (error) => {
+        span.recordException(error);
+        span.setStatus("error");
+        span.end();
+        throw error;
+      }
+    );
+  }
+  span.end();
+  return result;
+}
+export {
+  runSpan
+};
+//# sourceMappingURL=run-span.js.map

package/dist/provider/run-span.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/provider/run-span.ts"],
+  "sourcesContent": ["import type { Span } from '../types'\n\nfunction isThenable(value: unknown): value is Promise<unknown> {\n  return (\n    value != null &&\n    (typeof value === 'object' || typeof value === 'function') &&\n    typeof (value as { then?: unknown }).then === 'function'\n  )\n}\n\n/**\n * Run `fn(span)` and end `span` when it settles \u2014 synchronously for sync\n * returns, on resolve/reject for promises. Exceptions (sync throw or rejected\n * promise) are recorded on the span and re-thrown. Shared by the console and\n * OTLP providers so async spans get correct durations.\n */\nexport function runSpan<T>(span: Span, fn: (span: Span) => T): T {\n  let result: T\n  try {\n    result = fn(span)\n  } catch (error) {\n    span.recordException(error)\n    span.setStatus('error')\n    span.end()\n    throw error\n  }\n\n  if (isThenable(result)) {\n    return result.then(\n      (value) => {\n        span.end()\n        return value\n      },\n      (error) => {\n        span.recordException(error)\n        span.setStatus('error')\n        span.end()\n        throw error\n      },\n    ) as T\n  }\n\n  span.end()\n  return result\n}\n"],
+  "mappings": "AAEA,SAAS,WAAW,OAA2C;AAC7D,SACE,SAAS,SACR,OAAO,UAAU,YAAY,OAAO,UAAU,eAC/C,OAAQ,MAA6B,SAAS;AAElD;AAQO,SAAS,QAAW,MAAY,IAA0B;AAC/D,MAAI;AACJ,MAAI;AACF,aAAS,GAAG,IAAI;AAAA,EAClB,SAAS,OAAO;AACd,SAAK,gBAAgB,KAAK;AAC1B,SAAK,UAAU,OAAO;AACtB,SAAK,IAAI;AACT,UAAM;AAAA,EACR;AAEA,MAAI,WAAW,MAAM,GAAG;AACtB,WAAO,OAAO;AAAA,MACZ,CAAC,UAAU;AACT,aAAK,IAAI;AACT,eAAO;AAAA,MACT;AAAA,MACA,CAAC,UAAU;AACT,aAAK,gBAAgB,KAAK;AAC1B,aAAK,UAAU,OAAO;AACtB,aAAK,IAAI;AACT,cAAM;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,OAAK,IAAI;AACT,SAAO;AACT;",
+  "names": []
+}

package/dist/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/jest.config.cjs

@@ -0,0 +1,27 @@
+/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.cjs')
+
+module.exports = {
+  ...base,
+  testEnvironment: 'node',
+  watchman: false,
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      '<rootDir>/../../scripts/jest-mikroorm-transformer.cjs',
+      {
+        tsconfig: {
+          jsx: 'react-jsx',
+          rootDir: '.',
+          ignoreDeprecations: '6.0',
+        },
+      },
+    ],
+  },
+  transformIgnorePatterns: [
+    'node_modules/(?!(@mikro-orm|kysely)/)',
+  ],
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@open-mercato/telemetry",
+  "version": "0.6.7-develop.6834.1.e76f4b8cbc",
+  "description": "Vendor-neutral spans, metrics, and error reporting backed by a pluggable OTLP provider. Off by default; the telemetry runtime is loaded only when explicitly enabled.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": [
+        "./src/*.ts"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts"
+      ],
+      "default": "./dist/*/*.js"
+    }
+  },
+  "dependencies": {
+    "@open-mercato/shared": "0.6.7-develop.6834.1.e76f4b8cbc"
+  },
+  "optionalDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.220.0",
+    "@opentelemetry/core": "^2.9.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.220.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.220.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
+    "@opentelemetry/instrumentation": "^0.220.0",
+    "@opentelemetry/instrumentation-pg": "^0.71.0",
+    "@opentelemetry/instrumentation-undici": "^0.29.0",
+    "@opentelemetry/resources": "^2.9.0",
+    "@opentelemetry/sdk-logs": "^0.220.0",
+    "@opentelemetry/sdk-metrics": "^2.9.0",
+    "@opentelemetry/sdk-node": "^0.220.0",
+    "@opentelemetry/sdk-trace-node": "^2.9.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1"
+  },
+  "devDependencies": {
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.1.2",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.12",
+    "typescript": "7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/telemetry"
+  },
+  "stableVersion": "0.6.6"
+}

package/src/__tests__/default-unloaded.test.ts

@@ -0,0 +1,58 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'
+
+const repoRoot = path.resolve(__dirname, '../../../..')
+
+const runtimeHosts = [
+  'apps/mercato/src/instrumentation.ts',
+  'apps/mercato/src/app/api/[...slug]/route.ts',
+  'packages/create-app/template/src/instrumentation.ts',
+  'packages/create-app/template/src/app/api/[...slug]/route.ts',
+  'packages/cli/src/bin.ts',
+  'packages/queue/src/tracing.ts',
+  'packages/queue/src/strategies/async.ts',
+  'packages/queue/src/worker/runner.ts',
+]
+
+describe('default-unloaded host wiring', () => {
+  const originalBackend = process.env.TELEMETRY_BACKEND
+
+  beforeAll(() => {
+    delete process.env.TELEMETRY_BACKEND
+  })
+
+  afterAll(() => {
+    if (originalBackend === undefined) delete process.env.TELEMETRY_BACKEND
+    else process.env.TELEMETRY_BACKEND = originalBackend
+  })
+
+  it.each([
+    [undefined, false],
+    ['', false],
+    ['noop', false],
+    ['unknown', false],
+    ['console', true],
+    ['otlp', true],
+    ['signoz', true],
+    ['newrelic', true],
+  ])('resolves backend %s to enabled=%s', (raw, expected) => {
+    expect(isTelemetryBackendEnabled(raw)).toBe(expected)
+  })
+
+  it.each(runtimeHosts)('%s has no static telemetry runtime import', (relativePath) => {
+    const source = fs.readFileSync(path.join(repoRoot, relativePath), 'utf8')
+    expect(source).not.toMatch(/\bfrom\s+['"]@open-mercato\/telemetry(?:['"/])/)
+  })
+
+  it('Next config imports only the runtime-free telemetry config entrypoint', () => {
+    for (const relativePath of [
+      'apps/mercato/next.config.ts',
+      'packages/create-app/template/next.config.ts',
+    ]) {
+      const source = fs.readFileSync(path.join(repoRoot, relativePath), 'utf8')
+      expect(source).toContain("from '@open-mercato/telemetry/nextjs-config'")
+      expect(source).not.toContain("from '@open-mercato/telemetry/nextjs'")
+    }
+  })
+})

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

@@ -0,0 +1,80 @@
+import { getLoggerExtension, resetLoggerExtension } from '@open-mercato/shared/lib/logger'
+import {
+  getTelemetryRuntime,
+  resetTelemetryRuntime,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+import { initTelemetry, resetTelemetryInit } from '../init'
+import {
+  getActiveProvider,
+  registerProvider,
+  resetActiveProvider,
+} from '../provider/registry'
+import { resetTelemetryEnvCache } from '../env'
+import type { TelemetryProvider } from '../types'
+import { NOOP_SPAN } from '../provider/noop-provider'
+
+function provider(name = 'noop'): TelemetryProvider {
+  return {
+    name,
+    supports: [],
+    start: jest.fn(async () => {}),
+    shutdown: jest.fn(async () => {}),
+    runInSpan: (_name, _options, fn) => fn(NOOP_SPAN),
+    activeSpan: () => undefined,
+    activeTraceContext: () => undefined,
+    inject: () => {},
+    runInRemoteSpan: (_carrier, _name, _options, fn) => fn(NOOP_SPAN),
+    emitLog: () => {},
+    recordMetric: () => {},
+  }
+}
+
+describe('telemetry explicit opt-in boundary', () => {
+  beforeEach(() => {
+    delete process.env.TELEMETRY_BACKEND
+    resetTelemetryEnvCache()
+    resetTelemetryInit()
+    resetActiveProvider()
+    resetLoggerExtension()
+    resetTelemetryRuntime()
+  })
+
+  it('does not resolve a custom provider or register runtime hooks while off', async () => {
+    const customNoop = provider()
+    registerProvider(customNoop)
+
+    await initTelemetry()
+
+    expect(customNoop.start).not.toHaveBeenCalled()
+    expect(getActiveProvider().name).toBe('noop')
+    expect(getLoggerExtension()).toBeUndefined()
+    expect(getTelemetryRuntime()).toBeUndefined()
+  })
+
+  it('can initialize after dotenv sets an enabled backend following an off call', async () => {
+    const customConsole = provider('console')
+    registerProvider(customConsole)
+
+    await initTelemetry()
+    process.env.TELEMETRY_BACKEND = 'console'
+    await initTelemetry()
+
+    expect(customConsole.start).toHaveBeenCalledTimes(1)
+    expect(getActiveProvider()).toBe(customConsole)
+    expect(getLoggerExtension()).toBeDefined()
+    expect(getTelemetryRuntime()).toBeDefined()
+  })
+
+  it('initializes an explicitly registered custom backend', async () => {
+    const customProvider = provider('custom-observability')
+    registerProvider(customProvider)
+    process.env.TELEMETRY_BACKEND = 'custom-observability'
+
+    await initTelemetry()
+
+    expect(customProvider.start).toHaveBeenCalledTimes(1)
+    expect(getActiveProvider()).toBe(customProvider)
+    expect(getLoggerExtension()).toBeDefined()
+    expect(getTelemetryRuntime()).toBeDefined()
+  })
+})

package/src/__tests__/env.test.ts

@@ -0,0 +1,72 @@
+import { isOtlpBackend, readTelemetryEnv, resetTelemetryEnvCache } from '../env'
+
+const SAVED = { ...process.env }
+
+function setEnv(vars: Record<string, string | undefined>): void {
+  for (const [k, v] of Object.entries(vars)) {
+    if (v === undefined) delete process.env[k]
+    else process.env[k] = v
+  }
+  resetTelemetryEnvCache()
+}
+
+afterEach(() => {
+  process.env = { ...SAVED }
+  resetTelemetryEnvCache()
+})
+
+describe('readTelemetryEnv', () => {
+  it('defaults to the noop backend (off) when TELEMETRY_BACKEND is unset', () => {
+    setEnv({ TELEMETRY_BACKEND: undefined })
+    const env = readTelemetryEnv()
+    expect(env.backend).toBe('noop')
+    expect(env.enabled).toBe(false)
+  })
+
+  it('treats an unknown backend as noop', () => {
+    setEnv({ TELEMETRY_BACKEND: 'datadog-lol' })
+    expect(readTelemetryEnv().backend).toBe('noop')
+  })
+
+  it('accepts signoz/console and marks them enabled', () => {
+    setEnv({ TELEMETRY_BACKEND: 'signoz' })
+    expect(readTelemetryEnv()).toMatchObject({ backend: 'signoz', enabled: true })
+    setEnv({ TELEMETRY_BACKEND: 'console' })
+    expect(readTelemetryEnv()).toMatchObject({ backend: 'console', enabled: true })
+  })
+
+  it('accepts newrelic/otlp as OTLP backends (same seam, vendor by endpoint)', () => {
+    setEnv({ TELEMETRY_BACKEND: 'newrelic' })
+    expect(readTelemetryEnv()).toMatchObject({ backend: 'newrelic', enabled: true })
+    setEnv({ TELEMETRY_BACKEND: 'otlp' })
+    expect(readTelemetryEnv()).toMatchObject({ backend: 'otlp', enabled: true })
+    expect(isOtlpBackend('newrelic')).toBe(true)
+    expect(isOtlpBackend('otlp')).toBe(true)
+    expect(isOtlpBackend('signoz')).toBe(true)
+    expect(isOtlpBackend('console')).toBe(false)
+    expect(isOtlpBackend('noop')).toBe(false)
+  })
+
+  it('parses sampling ratio and falls back / clamps invalid values', () => {
+    setEnv({ TELEMETRY_SAMPLING_RATIO: '0.25', NODE_ENV: 'development' })
+    expect(readTelemetryEnv().samplingRatio).toBe(0.25)
+    setEnv({ TELEMETRY_SAMPLING_RATIO: '5', NODE_ENV: 'development' })
+    expect(readTelemetryEnv().samplingRatio).toBe(1.0) // out of range -> dev default
+    setEnv({ TELEMETRY_SAMPLING_RATIO: undefined, NODE_ENV: 'development' })
+    expect(readTelemetryEnv().samplingRatio).toBe(1.0)
+  })
+
+  it('trust-inbound-trace defaults off (root-per-request), explicit values parse', () => {
+    setEnv({ TELEMETRY_TRUST_INBOUND_TRACE: undefined })
+    expect(readTelemetryEnv().trustInboundTrace).toBe(false)
+    setEnv({ TELEMETRY_TRUST_INBOUND_TRACE: 'true' })
+    expect(readTelemetryEnv().trustInboundTrace).toBe(true)
+    setEnv({ TELEMETRY_TRUST_INBOUND_TRACE: '1' })
+    expect(readTelemetryEnv().trustInboundTrace).toBe(true)
+    setEnv({ TELEMETRY_TRUST_INBOUND_TRACE: 'false' })
+    expect(readTelemetryEnv().trustInboundTrace).toBe(false)
+    setEnv({ TELEMETRY_TRUST_INBOUND_TRACE: 'garbage' })
+    expect(readTelemetryEnv().trustInboundTrace).toBe(false)
+  })
+
+})

package/src/__tests__/logger-level.test.ts

@@ -0,0 +1,64 @@
+import {
+  createLogger,
+  resetLogLevelCache,
+  resetLoggerExtension,
+  resetLoggerRegistry,
+} from '@open-mercato/shared/lib/logger'
+import { resetTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { initTelemetry, resetTelemetryInit } from '../init'
+import { registerProvider, resetActiveProvider } from '../provider/registry'
+import { resetTelemetryEnvCache } from '../env'
+import { NOOP_SPAN } from '../provider/noop-provider'
+import type { LogRecord, TelemetryProvider } from '../types'
+
+function recordingProvider(logs: LogRecord[]): TelemetryProvider {
+  return {
+    name: 'console',
+    supports: ['logs'],
+    async start() {},
+    async shutdown() {},
+    runInSpan: (_name, _options, fn) => fn(NOOP_SPAN),
+    activeSpan: () => undefined,
+    activeTraceContext: () => undefined,
+    inject: () => {},
+    runInRemoteSpan: (_carrier, _name, _options, fn) => fn(NOOP_SPAN),
+    emitLog: (record) => logs.push(record),
+    recordMetric: () => {},
+  }
+}
+
+describe('unified logger telemetry export', () => {
+  beforeEach(() => {
+    process.env.TELEMETRY_BACKEND = 'console'
+    process.env.OM_LOG_LEVEL = 'warn'
+    resetLogLevelCache()
+    resetLoggerRegistry()
+    resetLoggerExtension()
+    resetTelemetryRuntime()
+    resetTelemetryInit()
+    resetActiveProvider()
+    resetTelemetryEnvCache()
+  })
+
+  afterEach(() => {
+    delete process.env.TELEMETRY_BACKEND
+    delete process.env.OM_LOG_LEVEL
+  })
+
+  it('uses the shared level gate for local and remote output', async () => {
+    const logs: LogRecord[] = []
+    registerProvider(recordingProvider(logs))
+    await initTelemetry()
+    const logger = createLogger('orders')
+
+    logger.debug('quiet')
+    logger.info('quiet')
+    logger.warn('visible')
+    logger.error('failed', { err: new Error('boom') })
+
+    expect(logs.map((record) => record.level)).toEqual(['warn', 'error'])
+    expect(logs.map((record) => record.message)).toEqual(['visible', 'failed'])
+    expect(logs[1].error?.message).toBe('boom')
+    expect(logs[1].attributes?.['logger.name']).toBe('orders')
+  })
+})

package/src/__tests__/nextjs-shutdown.test.ts

@@ -0,0 +1,71 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Regression: registerTelemetryForNextjs()'s SIGTERM/SIGINT flush handler used
+ * to only call shutdownTelemetry() without re-raising the signal. A signal
+ * listener suppresses Node's default termination, so a web process that
+ * received SIGTERM on deploy flushed telemetry and then stayed alive until the
+ * orchestrator force-killed it. The handler must re-raise after the flush so
+ * the process still terminates.
+ *
+ * Runs in a real child process: only a real signal against a real event loop
+ * proves the process dies — in-process listener assertions cannot.
+ */
+const distNextjs = path.resolve(__dirname, '../../dist/nextjs.js')
+const pkgRoot = path.resolve(__dirname, '../..')
+
+const CHILD_SCRIPT = `
+const { registerTelemetryForNextjs } = await import('@open-mercato/telemetry/nextjs')
+await registerTelemetryForNextjs()
+setInterval(() => {}, 1000) // keep the event loop alive, like a server would
+console.log('READY')
+`
+
+// The build output must exist (the child imports the compiled helper). Runs in
+// CI after build:packages; skip locally when the package hasn't been built yet.
+const maybe = fs.existsSync(distNextjs) ? describe : describe.skip
+
+maybe('registerTelemetryForNextjs shutdown semantics', () => {
+  it('a SIGTERM after registration still terminates the process', async () => {
+    const scriptFile = path.join(pkgRoot, `.nextjs-shutdown-probe.${process.pid}.mjs`)
+    fs.writeFileSync(scriptFile, CHILD_SCRIPT)
+    try {
+      const child = spawn(process.execPath, [scriptFile], {
+        cwd: pkgRoot,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, TELEMETRY_BACKEND: 'console' },
+      })
+      await new Promise<void>((resolve, reject) => {
+        const bailout = setTimeout(() => reject(new Error('child never printed READY')), 15_000)
+        child.stdout.on('data', (chunk: Buffer) => {
+          if (chunk.toString().includes('READY')) {
+            clearTimeout(bailout)
+            resolve()
+          }
+        })
+        child.on('error', reject)
+      })
+
+      child.kill('SIGTERM')
+
+      const outcome = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(
+        (resolve, reject) => {
+          const bailout = setTimeout(() => {
+            child.kill('SIGKILL')
+            reject(new Error('process stayed alive after SIGTERM — the flush handler suppressed termination'))
+          }, 10_000)
+          child.on('exit', (code, signal) => {
+            clearTimeout(bailout)
+            resolve({ code, signal })
+          })
+        },
+      )
+      // The re-raised signal terminates the process with default semantics.
+      expect(outcome.signal).toBe('SIGTERM')
+    } finally {
+      fs.rmSync(scriptFile, { force: true })
+    }
+  }, 35_000)
+})

package/src/__tests__/nextjs.test.ts

@@ -0,0 +1,122 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { telemetryServerExternalPackages, recordHttpDuration, registerTelemetryForNextjs } from '../nextjs'
+import { resetTelemetryInit } from '../init'
+import { registerProvider, resetActiveProvider } from '../provider/registry'
+import { resetTelemetryEnvCache } from '../env'
+import { runSpan } from '../provider/run-span'
+import type { MetricPoint, Span, SpanOptions, TelemetryProvider } from '../types'
+
+class RecordingSpan implements Span {
+  setAttribute(): void {}
+  setAttributes(): void {}
+  recordException(): void {}
+  setStatus(): void {}
+  end(): void {}
+}
+
+function otelSpecifiersInSource(): string[] {
+  // Scan every source file except nextjs.ts itself (it contains the list under
+  // test) and the tests, so the expected set is derived from what the provider
+  // actually imports rather than a second hand-maintained copy.
+  const specifiers = new Set<string>()
+  const visit = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === '__tests__') continue
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        visit(full)
+      } else if (entry.name.endsWith('.ts') && full !== path.resolve(__dirname, '../nextjs-config.ts')) {
+        for (const match of fs.readFileSync(full, 'utf8').matchAll(/['"](@opentelemetry\/[a-z0-9-]+)['"]/g)) {
+          specifiers.add(match[1])
+        }
+      }
+    }
+  }
+  visit(path.resolve(__dirname, '..'))
+  return [...specifiers].sort()
+}
+
+function recordingProvider() {
+  const metrics: MetricPoint[] = []
+  let starts = 0
+  const span = new RecordingSpan()
+  const provider: TelemetryProvider = {
+    name: 'console',
+    supports: ['traces', 'metrics', 'logs', 'errors'],
+    async start() {
+      starts += 1
+    },
+    async shutdown() {},
+    runInSpan<T>(_name: string, _options: SpanOptions, fn: (s: Span) => T): T {
+      return runSpan(span, fn)
+    },
+    activeSpan: () => undefined,
+    inject: () => {},
+    runInRemoteSpan<T>(_carrier, _name: string, _options: SpanOptions, fn: (s: Span) => T): T {
+      return runSpan(span, fn)
+    },
+    emitLog: () => {},
+    recordMetric: (point) => metrics.push(point),
+  }
+  return { provider, metrics, startCount: () => starts }
+}
+
+describe('telemetry/nextjs helpers', () => {
+  beforeEach(() => {
+    resetActiveProvider()
+    resetTelemetryInit()
+    resetTelemetryEnvCache()
+    delete process.env.TELEMETRY_BACKEND
+    delete process.env.NEXT_RUNTIME
+  })
+
+  it('externals list is the full OTEL set the provider loads (no partial-copy footgun)', () => {
+    // Every @opentelemetry/* package the provider imports must be listed, or the
+    // bundler re-bundles a patched module and telemetry silently emits nothing.
+    // Set-equality both ways: a new provider import without a list entry fails,
+    // and so does a stale list entry nothing imports anymore.
+    expect([...telemetryServerExternalPackages].sort()).toEqual(otelSpecifiersInSource())
+    expect(telemetryServerExternalPackages.every((p) => p.startsWith('@opentelemetry/'))).toBe(true)
+  })
+
+  it('recordHttpDuration emits the semconv histogram; error.type only on 5xx', async () => {
+    const { provider, metrics } = recordingProvider()
+    process.env.TELEMETRY_BACKEND = 'console'
+    registerProvider(provider)
+    await registerTelemetryForNextjs()
+
+    recordHttpDuration('GET', '/api/[...slug]', 200, Date.now())
+    recordHttpDuration('POST', '/api/[...slug]', 500, Date.now())
+
+    const points = metrics.filter((m) => m.name === 'http.server.request.duration')
+    expect(points).toHaveLength(2)
+    expect(points[0].kind).toBe('histogram')
+    expect(points[0].unit).toBe('s')
+    expect(points[0].labels).toMatchObject({
+      'http.request.method': 'GET',
+      'http.route': '/api/[...slug]',
+      'http.response.status_code': 200,
+    })
+    expect(points[0].labels?.['error.type']).toBeUndefined()
+    expect(points[1].labels?.['error.type']).toBe('500')
+  })
+
+  it('registerTelemetryForNextjs is a safe no-op when telemetry is off', async () => {
+    await expect(registerTelemetryForNextjs()).resolves.toBeUndefined()
+  })
+
+  it('skips initialization on the edge runtime (NodeSDK is Node-only)', async () => {
+    const { provider, startCount } = recordingProvider()
+    registerProvider(provider)
+    process.env.TELEMETRY_BACKEND = 'console'
+
+    process.env.NEXT_RUNTIME = 'edge'
+    await registerTelemetryForNextjs()
+    expect(startCount()).toBe(0)
+
+    process.env.NEXT_RUNTIME = 'nodejs'
+    await registerTelemetryForNextjs()
+    expect(startCount()).toBe(1)
+  })
+})