@open-mercato/telemetry 0.8.1-develop.7275.1.f772b944d4 → 0.8.1-develop.7295.1.d0e0e33014

package/src/browser/BrowserTelemetry.tsx

@@ -0,0 +1,194 @@
+'use client'
+
+/**
+ * Browser RUM. Boots the OpenTelemetry web SDK once per page load and exports
+ * spans through the same-origin proxy (`/api/telemetry/browser-traces`).
+ *
+ * Why this exists: server traces can only prove where the time *isn't*. A page
+ * can render an API answer in 50 ms yet leave the user waiting seconds before
+ * the request is even sent — bundle download, hydration, or a click handler
+ * stuck behind a re-render are all invisible to every server span.
+ *
+ * Two rules this file lives by:
+ *  - **The SDK is `import()`ed, never statically imported.** RUM often
+ *    diagnoses routes suspected to be bundle-bound; shipping the SDK in the
+ *    critical path would be self-defeating. Document-load timings survive the
+ *    late start because they are read back from the PerformanceTimeline.
+ *  - **It can never break the app.** Every failure is swallowed. No
+ *    user-facing surface, no retry.
+ *
+ * This file, `config.ts`, and `propagator.ts` are the only parts of
+ * `@open-mercato/telemetry` a client bundle may reach (via the `/browser` entry).
+ * None of them may import the server facade (`node:async_hooks`) or the
+ * env-reading `browser/server.ts`; the two wirings are independent and meet only
+ * at the collector.
+ */
+
+import * as React from 'react'
+import type { BrowserTelemetryConfig } from './config'
+import { createBackupHeaderPropagator } from './propagator'
+
+/** Module-level so React StrictMode's double-invoke (and any remount) cannot start a second SDK. */
+let bootstrapped = false
+
+/**
+ * Test seam. Production has exactly one bootstrap per page load, so nothing else
+ * may call this — a second bootstrap would double every span.
+ */
+export function resetBrowserTelemetryBootstrap(): void {
+  bootstrapped = false
+}
+
+async function startBrowserTelemetry(config: BrowserTelemetryConfig): Promise<void> {
+  const [
+    { WebTracerProvider },
+    { BatchSpanProcessor, ParentBasedSampler, TraceIdRatioBasedSampler },
+    { OTLPTraceExporter },
+    { resourceFromAttributes },
+    { registerInstrumentations },
+    { DocumentLoadInstrumentation },
+    { FetchInstrumentation },
+    { W3CTraceContextPropagator },
+    { defaultTextMapSetter },
+  ] = await Promise.all([
+    import('@opentelemetry/sdk-trace-web'),
+    import('@opentelemetry/sdk-trace-base'),
+    import('@opentelemetry/exporter-trace-otlp-http'),
+    import('@opentelemetry/resources'),
+    import('@opentelemetry/instrumentation'),
+    import('@opentelemetry/instrumentation-document-load'),
+    import('@opentelemetry/instrumentation-fetch'),
+    import('@opentelemetry/core'),
+    import('@opentelemetry/api'),
+  ])
+
+  const provider = new WebTracerProvider({
+    resource: resourceFromAttributes({
+      'service.name': config.serviceName,
+      // Plain attribute name (not the semconv `deployment.environment.name`) so browser spans sort
+      // alongside the server spans, which use OTEL_RESOURCE_ATTRIBUTES.
+      ...(config.environment ? { 'deployment.environment': config.environment } : {}),
+      'user_agent.original': navigator.userAgent,
+    }),
+    sampler: new ParentBasedSampler({
+      root: new TraceIdRatioBasedSampler(config.samplingRatio),
+    }),
+    spanProcessors: [
+      new BatchSpanProcessor(
+        new OTLPTraceExporter({ url: config.endpoint }),
+        // The interesting spans arrive in bursts around a navigation; a short delay keeps them
+        // close together in the trace view without one request per span.
+        { scheduledDelayMillis: 3_000, maxQueueSize: 512 },
+      ),
+    ],
+  })
+
+  // Standard `traceparent` plus the backup copy the server continues once
+  // TELEMETRY_TRUST_INBOUND_TRACE is on — see `propagator.ts` for why that flag is the supported
+  // way to get one end-to-end trace, and what happens without it.
+  provider.register({
+    propagator: createBackupHeaderPropagator(new W3CTraceContextPropagator(), defaultTextMapSetter),
+  })
+
+  // ── The fetch-patch dance (do not simplify) ────────────────────────────────────────────────
+  // `@open-mercato/ui`'s api utils install a global wrapper at module load so that stray
+  // `fetch()` calls still get the 401 session-refresh / 403 banner behaviour:
+  //     w.__omOriginalFetch = window.fetch            // pristine native fetch
+  //     window.fetch = (i, x) => apiFetch(i, x)
+  // and `apiFetch` then calls `__omOriginalFetch` to avoid recursing into itself. Since the whole
+  // backoffice (DataTable, CrudForm, react-query queryFns…) imports `apiFetch` DIRECTLY, those
+  // calls never touch `window.fetch` — so instrumenting `window.fetch` alone yields document-load
+  // spans and almost no API spans, which is worse than none at all: it looks like it works.
+  //
+  // Fix: let the instrumentation patch the *native* fetch, then hand the patched version back as
+  // the stash. Both paths end up instrumented exactly once:
+  //     apiFetch          → __omOriginalFetch = OTel(native)         ✓
+  //     window.fetch      → apiFetch wrapper → OTel(native)          ✓
+  // Assigning `__omOriginalFetch = window.fetch` instead would loop forever
+  // (apiFetch → wrapper → apiFetch → …). The swap is synchronous — `registerInstrumentations`
+  // calls `enable()` inline — so no caller can observe the intermediate state.
+  const patchTarget = window as Window & { __omOriginalFetch?: typeof window.fetch }
+  const frameworkFetch = patchTarget.__omOriginalFetch ? window.fetch : null
+  if (frameworkFetch && patchTarget.__omOriginalFetch) {
+    window.fetch = patchTarget.__omOriginalFetch
+  }
+
+  // `finally`, not a plain sequence: the instrumentation constructors below are evaluated inside
+  // this window, and a throw from any of them (SDK version skew, a browser missing an API an
+  // instrumentation touches) would otherwise leave `window.fetch` as the raw native fetch stashed
+  // above. `apiFetch` would keep working — it reads `__omOriginalFetch` — but every stray
+  // `window.fetch(...)` would silently bypass the framework wrapper's 401 session-refresh and 403
+  // banner behaviour for the rest of the page's life. This is the one path where the file's
+  // "every failure is swallowed" rule would leave global state degraded.
+  try {
+    registerInstrumentations({
+      tracerProvider: provider,
+      instrumentations: [
+        // Navigation + resource timings: chunk download vs. parse vs. hydrate.
+        new DocumentLoadInstrumentation(),
+        // The client-side START of each API call — the number the server can never see.
+        new FetchInstrumentation({
+          // Never instrument our own export, or each batch would generate the next one.
+          ignoreUrls: [new RegExp(escapeRegExp(config.endpoint))],
+          clearTimingResources: true,
+        }),
+        // No `UserInteractionInstrumentation` here, deliberately. It works by patching
+        // `addEventListener` when `enable()` runs, but React attaches a SINGLE delegated `click`
+        // listener to the root container during `createRoot`/hydration — and this SDK boots from
+        // `useEffect`, which React runs strictly after hydration. The patch would land after the
+        // only listener that will ever see a backoffice click, so it produces no spans at all
+        // (confirmed in manual QA). Booting early enough to beat hydration would mean putting the
+        // SDK back on the critical path, which is the one thing this file refuses to do. An
+        // instrumentation that silently produces nothing is worse than an absent one: an empty
+        // interaction view reads as "nobody clicks" rather than "this is broken".
+      ],
+    })
+  } finally {
+    if (frameworkFetch) {
+      // On the success path `window.fetch` is OTel's patched native fetch; on the throw path it is
+      // the pristine native one. Either way this restores the framework wrapper on top of whatever
+      // the stash should now hold, so the pre-swap contract holds in both.
+      patchTarget.__omOriginalFetch = window.fetch
+      window.fetch = frameworkFetch
+    }
+  }
+
+  // BatchSpanProcessor would otherwise drop whatever is still queued when the user navigates away
+  // — which is exactly when a slow page gets abandoned, i.e. the spans we most want.
+  //
+  // `forceFlush` exports through the OTLP fetch transport, which sets `keepalive: true` on the
+  // request whenever the payload and the number of in-flight requests are within the browser's
+  // limits — so the batch survives the page going away. That is the durable path here;
+  // `sendBeacon` would be the other candidate, but upstream deprecated its export delegate in
+  // favour of the fetch one, so reaching for it would trade a supported API for a doomed one.
+  //
+  // Both events, because neither alone covers every exit: `visibilitychange` misses some bfcache
+  // entries, and `pagehide` does not fire when a tab is merely backgrounded. A second flush with
+  // an empty queue is a no-op, so the overlap costs nothing.
+  const flush = () => void provider.forceFlush().catch(() => {})
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden') flush()
+  })
+  window.addEventListener('pagehide', flush)
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Renders nothing. `config` is resolved server-side (`resolveBrowserTelemetryConfig()`) and is
+ * `null` whenever browser telemetry is disabled for the environment — which is the default, and
+ * keeps the SDK chunk from ever being requested.
+ */
+export function BrowserTelemetry({ config }: { config: BrowserTelemetryConfig | null }) {
+  React.useEffect(() => {
+    if (!config || bootstrapped) return
+    bootstrapped = true
+    void startBrowserTelemetry(config).catch(() => {
+      // Telemetry must never degrade the app it measures: stay silent and stay down (no retry).
+    })
+  }, [config])
+
+  return null
+}

package/src/browser/__tests__/browser-telemetry.test.tsx

@@ -0,0 +1,325 @@
+/**
+ * @jest-environment jsdom
+ */
+
+/**
+ * The browser runtime itself: what actually loads the SDK, what patches global
+ * fetch, and what must never happen while RUM is off. The OTel web SDK is mocked
+ * — the point here is our wiring, not OpenTelemetry's. Trace continuity against
+ * the real server extractor is covered in `__tests__/otlp-integration.test.ts`.
+ */
+import * as React from 'react'
+import { act, render } from '@testing-library/react'
+import { BrowserTelemetry, resetBrowserTelemetryBootstrap } from '../BrowserTelemetry'
+import { BROWSER_TRACES_PATH, type BrowserTelemetryConfig } from '../config'
+import { BACKUP_TRACEPARENT_HEADER, BACKUP_TRACESTATE_HEADER } from '../../trace-headers'
+import type { TextMapPropagator } from '@opentelemetry/api'
+
+/** Which SDK modules were dynamically imported — the "zero client cost while off" claim. */
+const mockLoadedModules: string[] = []
+const mockProviderInstances: Array<{
+  options: Record<string, unknown>
+  register: jest.Mock
+  forceFlush: jest.Mock
+}> = []
+const mockFetchInstrumentationConfigs: Array<{ ignoreUrls?: RegExp[] }> = []
+/**
+ * Arms the next `new FetchInstrumentation(...)` to throw. The constructors are evaluated as
+ * arguments to `registerInstrumentations`, i.e. while the native fetch is swapped in — so this is
+ * the seam that reproduces a throw landing mid-swap (SDK version skew, a missing browser API).
+ */
+const mockFetchInstrumentationFailure: { next: Error | null } = { next: null }
+const mockExporterConfigs: Array<{ url?: string }> = []
+const mockRegisterInstrumentations = jest.fn()
+/** Stands in for the fetch OTel's FetchInstrumentation.enable() installs, synchronously. */
+const mockOtelPatchedFetch = jest.fn() as unknown as typeof window.fetch
+
+function record<T>(moduleName: string, exports: T): T {
+  mockLoadedModules.push(moduleName)
+  return exports
+}
+
+jest.mock('@opentelemetry/sdk-trace-web', () =>
+  record('@opentelemetry/sdk-trace-web', {
+    WebTracerProvider: class {
+      register = jest.fn()
+      forceFlush = jest.fn(async () => {})
+      constructor(options: Record<string, unknown>) {
+        mockProviderInstances.push({ options, register: this.register, forceFlush: this.forceFlush })
+      }
+    },
+  }),
+)
+
+jest.mock('@opentelemetry/sdk-trace-base', () =>
+  record('@opentelemetry/sdk-trace-base', {
+    BatchSpanProcessor: class {},
+    ParentBasedSampler: class {},
+    TraceIdRatioBasedSampler: class {},
+  }),
+)
+
+jest.mock('@opentelemetry/exporter-trace-otlp-http', () =>
+  record('@opentelemetry/exporter-trace-otlp-http', {
+    OTLPTraceExporter: class {
+      constructor(config: { url?: string }) {
+        mockExporterConfigs.push(config)
+      }
+    },
+  }),
+)
+
+jest.mock('@opentelemetry/resources', () =>
+  record('@opentelemetry/resources', {
+    resourceFromAttributes: (attributes: Record<string, unknown>) => attributes,
+  }),
+)
+
+jest.mock('@opentelemetry/instrumentation', () =>
+  record('@opentelemetry/instrumentation', {
+    registerInstrumentations: (...args: unknown[]) => {
+      // The real call enables each instrumentation inline, and FetchInstrumentation's enable()
+      // replaces whatever `window.fetch` is at that moment. Reproducing that here is the whole
+      // point of the fetch-swap assertions below.
+      window.fetch = mockOtelPatchedFetch
+      mockRegisterInstrumentations(...args)
+    },
+  }),
+)
+
+jest.mock('@opentelemetry/instrumentation-document-load', () =>
+  record('@opentelemetry/instrumentation-document-load', { DocumentLoadInstrumentation: class {} }),
+)
+
+jest.mock('@opentelemetry/instrumentation-fetch', () =>
+  record('@opentelemetry/instrumentation-fetch', {
+    FetchInstrumentation: class {
+      constructor(config: { ignoreUrls?: RegExp[] }) {
+        if (mockFetchInstrumentationFailure.next) {
+          const failure = mockFetchInstrumentationFailure.next
+          mockFetchInstrumentationFailure.next = null
+          throw failure
+        }
+        mockFetchInstrumentationConfigs.push(config)
+      }
+    },
+  }),
+)
+
+/**
+ * Nothing imports this any more — the mock stays so that a re-introduction shows up in
+ * `mockLoadedModules` (and is caught by the regression test below) instead of failing as a missing
+ * dependency with the reason lost. `virtual` because the package is no longer installed.
+ */
+jest.mock(
+  '@opentelemetry/instrumentation-user-interaction',
+  () => record('@opentelemetry/instrumentation-user-interaction', { UserInteractionInstrumentation: class {} }),
+  { virtual: true },
+)
+
+jest.mock('@opentelemetry/core', () =>
+  record('@opentelemetry/core', {
+    W3CTraceContextPropagator: class {
+      inject(_ctx: unknown, carrier: Record<string, string>, setter: { set(c: unknown, k: string, v: string): void }) {
+        setter.set(carrier, 'traceparent', '00-11111111111111111111111111111111-2222222222222222-01')
+        setter.set(carrier, 'tracestate', 'om=1')
+      }
+      fields() {
+        return ['traceparent', 'tracestate']
+      }
+    },
+  }),
+)
+
+jest.mock('@opentelemetry/api', () =>
+  record('@opentelemetry/api', {
+    defaultTextMapSetter: {
+      set: (carrier: Record<string, string>, key: string, value: string) => {
+        carrier[key] = value
+      },
+    },
+  }),
+)
+
+const CONFIG: BrowserTelemetryConfig = {
+  endpoint: BROWSER_TRACES_PATH,
+  serviceName: 'acme-oms-browser',
+  environment: 'production',
+  samplingRatio: 0.25,
+}
+
+/** The effect chains a dynamic import; one macrotask turn is enough to settle it. */
+async function renderAndSettle(element: React.ReactElement): Promise<void> {
+  render(element)
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0))
+  })
+}
+
+describe('BrowserTelemetry', () => {
+  const nativeFetch = window.fetch
+
+  beforeEach(() => {
+    resetBrowserTelemetryBootstrap()
+    mockLoadedModules.length = 0
+    mockProviderInstances.length = 0
+    mockFetchInstrumentationConfigs.length = 0
+    mockExporterConfigs.length = 0
+    mockRegisterInstrumentations.mockClear()
+    mockFetchInstrumentationFailure.next = null
+    window.fetch = nativeFetch
+    delete (window as { __omOriginalFetch?: unknown }).__omOriginalFetch
+  })
+
+  it('loads nothing at all while telemetry is disabled — RUM must cost a disabled app zero bytes', async () => {
+    await renderAndSettle(<BrowserTelemetry config={null} />)
+
+    expect(mockLoadedModules).toEqual([])
+    expect(mockProviderInstances).toHaveLength(0)
+  })
+
+  it('boots the web SDK exactly once under StrictMode, which double-invokes every effect', async () => {
+    await renderAndSettle(
+      <React.StrictMode>
+        <BrowserTelemetry config={CONFIG} />
+      </React.StrictMode>,
+    )
+
+    // A second provider would double every span and every export.
+    expect(mockProviderInstances).toHaveLength(1)
+    expect(mockRegisterInstrumentations).toHaveBeenCalledTimes(1)
+  })
+
+  it('stays down after a remount, because a page load gets one SDK', async () => {
+    await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+    await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+
+    expect(mockProviderInstances).toHaveLength(1)
+  })
+
+  it('exports through the same-origin proxy and never instruments that export', async () => {
+    await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+
+    expect(mockExporterConfigs[0]?.url).toBe(BROWSER_TRACES_PATH)
+    const ignoreUrls = mockFetchInstrumentationConfigs[0]?.ignoreUrls ?? []
+    // Without this the exporter's own POST produces a span, which produces the next batch, forever.
+    expect(ignoreUrls.some((pattern) => pattern.test(`http://localhost${BROWSER_TRACES_PATH}`))).toBe(true)
+    expect(ignoreUrls.some((pattern) => pattern.test('http://localhost/api/customers'))).toBe(false)
+  })
+
+  it('never loads the user-interaction instrumentation — it cannot see a React click and would emit nothing', async () => {
+    await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+
+    // React attaches its single delegated `click` listener to the root during hydration, which is
+    // strictly before this SDK boots from `useEffect`. The instrumentation patches
+    // `addEventListener` on `enable()`, so it would land too late to ever see a backoffice click
+    // and would ship an interaction view that reads "nobody clicks" instead of "this is broken".
+    expect(mockLoadedModules).not.toContain('@opentelemetry/instrumentation-user-interaction')
+    const registered = mockRegisterInstrumentations.mock.calls[0][0] as { instrumentations: unknown[] }
+    expect(registered.instrumentations).toHaveLength(2)
+  })
+
+  it('carries the resolved service identity onto the resource', async () => {
+    await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+
+    expect(mockProviderInstances[0]?.options.resource).toMatchObject({
+      'service.name': 'acme-oms-browser',
+      'deployment.environment': 'production',
+    })
+  })
+
+  it('injects the backup trace headers alongside the standard ones', async () => {
+    await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+
+    const registerArg = mockProviderInstances[0]?.register.mock.calls[0][0] as {
+      propagator: TextMapPropagator
+    }
+    const carrier: Record<string, string> = {}
+    registerArg.propagator.inject({} as never, carrier, {
+      set: (target: Record<string, string>, key: string, value: string) => {
+        target[key] = value
+      },
+    })
+
+    // The backup copy is what survives a load balancer rewriting `traceparent`.
+    expect(carrier[BACKUP_TRACEPARENT_HEADER]).toBe(carrier.traceparent)
+    expect(carrier[BACKUP_TRACESTATE_HEADER]).toBe(carrier.tracestate)
+    expect(registerArg.propagator.fields()).toEqual(
+      expect.arrayContaining([BACKUP_TRACEPARENT_HEADER, BACKUP_TRACESTATE_HEADER]),
+    )
+  })
+
+  describe('global fetch instrumentation', () => {
+    it('instruments the native fetch behind the framework wrapper, without recursing', async () => {
+      // What `@open-mercato/ui`'s api utils install at module load: the pristine fetch stashed
+      // aside, and a wrapper in its place. (jsdom ships no `fetch`, hence the explicit stub.)
+      const pristineFetch = jest.fn() as unknown as typeof window.fetch
+      const frameworkFetch = jest.fn() as unknown as typeof window.fetch
+      ;(window as { __omOriginalFetch?: typeof window.fetch }).__omOriginalFetch = pristineFetch
+      window.fetch = frameworkFetch
+
+      await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+
+      // The framework wrapper stays the public entry point, so 401/403 handling is untouched…
+      expect(window.fetch).toBe(frameworkFetch)
+      // …and the fetch it delegates to is now the instrumented one, so direct apiFetch callers
+      // (DataTable, CrudForm, react-query) produce spans too.
+      expect((window as { __omOriginalFetch?: typeof window.fetch }).__omOriginalFetch).toBe(mockOtelPatchedFetch)
+      // Handing the wrapper back to itself would loop forever on the first request.
+      expect((window as { __omOriginalFetch?: typeof window.fetch }).__omOriginalFetch).not.toBe(frameworkFetch)
+    })
+
+    it('instruments window.fetch directly when the framework wrapper is absent', async () => {
+      await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+
+      expect(window.fetch).toBe(mockOtelPatchedFetch)
+      expect((window as { __omOriginalFetch?: typeof window.fetch }).__omOriginalFetch).toBeUndefined()
+    })
+
+    it('puts the framework wrapper back when instrumentation setup throws mid-swap', async () => {
+      const pristineFetch = jest.fn() as unknown as typeof window.fetch
+      const frameworkFetch = jest.fn() as unknown as typeof window.fetch
+      ;(window as { __omOriginalFetch?: typeof window.fetch }).__omOriginalFetch = pristineFetch
+      window.fetch = frameworkFetch
+      mockFetchInstrumentationFailure.next = new Error('SDK version skew')
+
+      await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+
+      // Without the `finally`, `window.fetch` would stay the raw native fetch for the rest of the
+      // page's life and every stray caller would silently lose the 401 session-refresh and 403
+      // banner behaviour the framework wrapper exists for. Nothing logs, so it would be invisible.
+      expect(window.fetch).toBe(frameworkFetch)
+      expect((window as { __omOriginalFetch?: typeof window.fetch }).__omOriginalFetch).toBe(pristineFetch)
+      expect(mockRegisterInstrumentations).not.toHaveBeenCalled()
+    })
+  })
+
+  it('flushes queued spans when the tab is hidden — an abandoned slow page is the one worth keeping', async () => {
+    await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+    const { forceFlush } = mockProviderInstances[0]
+
+    Object.defineProperty(document, 'visibilityState', { value: 'visible', configurable: true })
+    document.dispatchEvent(new Event('visibilitychange'))
+    expect(forceFlush).not.toHaveBeenCalled()
+
+    Object.defineProperty(document, 'visibilityState', { value: 'hidden', configurable: true })
+    document.dispatchEvent(new Event('visibilitychange'))
+    expect(forceFlush).toHaveBeenCalledTimes(1)
+  })
+
+  it('also flushes on pagehide, which is the exit visibilitychange can miss', async () => {
+    await renderAndSettle(<BrowserTelemetry config={CONFIG} />)
+    const { forceFlush } = mockProviderInstances[0]
+
+    window.dispatchEvent(new Event('pagehide'))
+    expect(forceFlush).toHaveBeenCalledTimes(1)
+  })
+
+  it('stays silent when the SDK fails to boot — telemetry may never degrade the app it measures', async () => {
+    mockRegisterInstrumentations.mockImplementationOnce(() => {
+      throw new Error('SDK exploded')
+    })
+
+    await expect(renderAndSettle(<BrowserTelemetry config={CONFIG} />)).resolves.toBeUndefined()
+  })
+})

package/src/browser/config.ts

@@ -0,0 +1,21 @@
+/**
+ * The browser-RUM contract shared by both halves of the feature: the shape the
+ * server resolves (`browser/server.ts`) and the shape the client component
+ * consumes (`browser/BrowserTelemetry.tsx`).
+ *
+ * Deliberately dependency-free and env-free so it can sit in a client bundle.
+ * Everything that reads `process.env` lives in `browser/server.ts`, which is a
+ * server-only module and is never reachable from the `/browser` entry.
+ */
+
+/** Same-origin path the browser exporter posts to; served by the `telemetry` module's API route. */
+export const BROWSER_TRACES_PATH = '/api/telemetry/browser-traces'
+
+export type BrowserTelemetryConfig = {
+  /** Same-origin OTLP endpoint (the proxy route). */
+  endpoint: string
+  serviceName: string
+  /** `deployment.environment` — kept as a plain attribute name to match existing server spans. */
+  environment: string | null
+  samplingRatio: number
+}

package/src/browser/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser RUM entry — the ONLY part of `@open-mercato/telemetry` a client
+ * bundle may reach. Import from `@open-mercato/telemetry/browser`.
+ *
+ * Everything here is env-free. The server half — `resolveBrowserTelemetryConfig()`
+ * plus the collector endpoint/credential readers — lives behind
+ * `@open-mercato/telemetry/browser/server`, which refuses to load in a browser.
+ * A server component resolves the config there and passes it to
+ * `<BrowserTelemetry />`, a `'use client'` boundary that dynamically loads the
+ * OTel web SDK only when the config is non-null.
+ */
+export { BrowserTelemetry } from './BrowserTelemetry'
+export { BROWSER_TRACES_PATH } from './config'
+export type { BrowserTelemetryConfig } from './config'
+export { BACKUP_TRACEPARENT_HEADER, BACKUP_TRACESTATE_HEADER } from '../trace-headers'

package/src/browser/propagator.ts

@@ -0,0 +1,40 @@
+/**
+ * The browser's outbound trace propagator: standard W3C plus the backup copy
+ * (`x-original-traceparent`) that a load balancer will not rewrite — the mirror
+ * image of `provider/otlp-provider.ts`'s `backupHeaderPropagator`.
+ *
+ * Injecting these headers is necessary but NOT sufficient for one end-to-end
+ * trace. The server ignores every inbound trace header — standard and backup
+ * alike — unless `TELEMETRY_TRUST_INBOUND_TRACE=true`, because at an HTTP
+ * boundary they are caller-controlled. That flag is therefore the supported way
+ * to stitch a browser span to its server span; the backup header is what
+ * survives a proxy in between. Without the flag RUM still works, it just yields
+ * two disconnected traces per page (the server warns about that once).
+ *
+ * The W3C propagator is passed in rather than imported: the web SDK is only ever
+ * loaded through a dynamic `import()` inside `BrowserTelemetry.tsx`. Keeping the
+ * logic here — free of any runtime OTel import — is also what lets a test drive
+ * the real injector against the real server extractor.
+ */
+import type { TextMapPropagator, TextMapSetter } from '@opentelemetry/api'
+import { BACKUP_TRACEPARENT_HEADER, BACKUP_TRACESTATE_HEADER } from '../trace-headers'
+
+export function createBackupHeaderPropagator(
+  w3c: TextMapPropagator,
+  defaultTextMapSetter: TextMapSetter<Record<string, string>>,
+): TextMapPropagator {
+  return {
+    inject(ctx, carrier, setter) {
+      w3c.inject(ctx, carrier, setter)
+      // Inject into a plain temp carrier so the values can be mirrored regardless
+      // of the real carrier's setter shape.
+      const mirror: Record<string, string> = {}
+      w3c.inject(ctx, mirror, defaultTextMapSetter)
+      if (mirror.traceparent) setter.set(carrier, BACKUP_TRACEPARENT_HEADER, mirror.traceparent)
+      if (mirror.tracestate) setter.set(carrier, BACKUP_TRACESTATE_HEADER, mirror.tracestate)
+    },
+    // A browser is always the root of its own trace — nothing inbound to extract.
+    extract: (ctx) => ctx,
+    fields: () => [...w3c.fields(), BACKUP_TRACEPARENT_HEADER, BACKUP_TRACESTATE_HEADER],
+  }
+}