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

package/src/browser/server.ts

@@ -0,0 +1,170 @@
+/**
+ * Server-only half of browser RUM: resolves the client configuration and the
+ * collector coordinates from the telemetry env the host already sets
+ * (`TELEMETRY_BACKEND`, `OTEL_EXPORTER_OTLP_*`), so enabling RUM is one flag and
+ * no new endpoint plumbing.
+ *
+ * Import from `@open-mercato/telemetry/browser/server` — NOT from
+ * `@open-mercato/telemetry/browser`, which is the client-safe entry. The split is
+ * the point: `resolveCollectorHeaders()` returns the collector credential, which
+ * must never be reachable from a client bundle. The guard below turns a wrong
+ * import into an immediate, loud failure instead of a silent leak.
+ *
+ * Resolved at request time in the backend layout (`force-dynamic`) and passed to
+ * the client as props — deliberately NOT `NEXT_PUBLIC_*`, which would bake the
+ * values into the build and require a rebuild to toggle.
+ */
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { readTelemetryEnv } from '../env'
+import { BROWSER_TRACES_PATH, type BrowserTelemetryConfig } from './config'
+
+if (typeof window !== 'undefined') {
+  throw new Error('[internal] @open-mercato/telemetry/browser/server is server-only; import @open-mercato/telemetry/browser instead')
+}
+
+const logger = createLogger('telemetry').child({ component: 'browser-config' })
+
+/** `deployment.environment=dev,foo=bar` → `dev`. */
+function readDeploymentEnvironment(raw: string | undefined): string | null {
+  if (!raw) return null
+  for (const pair of raw.split(',')) {
+    const idx = pair.indexOf('=')
+    if (idx === -1) continue
+    if (pair.slice(0, idx).trim() !== 'deployment.environment') continue
+    const value = pair.slice(idx + 1).trim()
+    if (value) return value
+  }
+  return null
+}
+
+function readSamplingRatio(raw: string | undefined): number {
+  if (!raw) return 1
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed)) return 1
+  return Math.min(1, Math.max(0, parsed))
+}
+
+let warnedAboutTraceContinuity = false
+
+/**
+ * Browser spans stitch to their server spans only when the server continues the
+ * inbound trace, which is exactly what `TELEMETRY_TRUST_INBOUND_TRACE` gates. RUM
+ * without it still works — it just yields two disconnected traces per page, which
+ * looks like a bug and is the single most likely misconfiguration, so say it once
+ * per process rather than let an operator discover it in the trace view.
+ */
+function warnWhenTracesCannotStitch(): void {
+  if (warnedAboutTraceContinuity) return
+  // Same reader the provider's propagator consults, so the warning can never
+  // disagree with the behaviour it describes.
+  if (readTelemetryEnv().trustInboundTrace) return
+  warnedAboutTraceContinuity = true
+  logger.warn('telemetry.browser.trace_continuity_disabled', {
+    detail:
+      'Browser RUM is enabled but TELEMETRY_TRUST_INBOUND_TRACE is not true, so browser spans and their server spans will land in separate traces. Set it to true when the app is only reachable through trusted infrastructure.',
+  })
+}
+
+/** Test seam: the warn-once latch is process-wide, which a second test case would otherwise miss. */
+export function resetBrowserTelemetryWarnings(): void {
+  warnedAboutTraceContinuity = false
+}
+
+/**
+ * Cookie an integration spec sets to boot RUM for its own page only. See
+ * `resolveTestOptIn` for why a per-request switch is the only way to cover the
+ * enabled path.
+ */
+export const BROWSER_TELEMETRY_TEST_COOKIE = 'om_test_browser_telemetry'
+
+/**
+ * Browser RUM is an environment-wide switch read from `process.env`, so a Playwright spec cannot
+ * turn it on for one page — and turning it on for the whole integration environment would boot the
+ * web SDK on every page of every other spec. This is the same targeted escape hatch the auth and
+ * AI-chat rate limiters use (`OM_TEST_MODE=1` plus a second, explicit `*_MODE=opt-in` variable):
+ * both are absent in production, and only then is the request's cookie consulted at all.
+ *
+ * The synthetic config it returns is deliberately self-contained — no `TELEMETRY_BACKEND`, no
+ * collector endpoint — so enabling it costs the integration environment nothing but the one page
+ * that asked for it. With no collector configured the proxy answers `204`, which is exactly the
+ * accept-and-drop contract the route documents, and the spec asserts on the batch the browser
+ * posted rather than on anything the collector received.
+ */
+function resolveTestOptIn(cookieHeader: string | null | undefined): BrowserTelemetryConfig | null {
+  if (process.env.OM_TEST_MODE !== '1') return null
+  if (process.env.OM_TEST_BROWSER_TELEMETRY_MODE !== 'opt-in') return null
+  if (!cookieHeader) return null
+  const pattern = new RegExp(`(?:^|;)\\s*${BROWSER_TELEMETRY_TEST_COOKIE}=on(?:;|$)`)
+  if (!pattern.test(cookieHeader)) return null
+  return {
+    endpoint: BROWSER_TRACES_PATH,
+    serviceName: `${process.env.OTEL_SERVICE_NAME?.trim() || 'open-mercato'}-browser`,
+    environment: readDeploymentEnvironment(process.env.OTEL_RESOURCE_ATTRIBUTES),
+    samplingRatio: 1,
+  }
+}
+
+/**
+ * Returns `null` when browser telemetry is off — which is the default
+ * everywhere, including local. Requires an active server telemetry backend
+ * *and* an explicit opt-in: RUM without a reachable collector is pure overhead
+ * in the client bundle.
+ *
+ * `options.cookieHeader` is the request's raw `Cookie` header, and is read only by the
+ * integration-test opt-in above; production resolution is env-only and never consults it.
+ */
+export function resolveBrowserTelemetryConfig(
+  options: { cookieHeader?: string | null } = {},
+): BrowserTelemetryConfig | null {
+  const testOptIn = resolveTestOptIn(options.cookieHeader)
+  if (testOptIn) return testOptIn
+
+  if (!parseBooleanWithDefault(process.env.TELEMETRY_BROWSER_ENABLED, false)) return null
+  if (!isTelemetryBackendEnabled()) return null
+  if (!resolveCollectorTracesUrl()) return null
+
+  warnWhenTracesCannotStitch()
+
+  const serviceName =
+    process.env.TELEMETRY_BROWSER_SERVICE_NAME?.trim() ||
+    `${process.env.OTEL_SERVICE_NAME?.trim() || 'open-mercato'}-browser`
+
+  return {
+    endpoint: BROWSER_TRACES_PATH,
+    serviceName,
+    environment: readDeploymentEnvironment(process.env.OTEL_RESOURCE_ATTRIBUTES),
+    samplingRatio: readSamplingRatio(process.env.TELEMETRY_BROWSER_SAMPLING_RATIO),
+  }
+}
+
+/**
+ * Where the proxy forwards to. Per the OTLP spec a signal-specific endpoint is
+ * used verbatim, while the generic one gets `/v1/traces` appended.
+ */
+export function resolveCollectorTracesUrl(): string | null {
+  const signal = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim()
+  if (signal) return signal
+  const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim()
+  if (!generic) return null
+  return `${generic.replace(/\/+$/, '')}/v1/traces`
+}
+
+/**
+ * `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic <b64>,key=value` → header record.
+ * Split on the FIRST `=` only: base64 credentials routinely end in `=` padding.
+ */
+export function resolveCollectorHeaders(): Record<string, string> {
+  const raw = process.env.OTEL_EXPORTER_OTLP_HEADERS?.trim()
+  if (!raw) return {}
+  const headers: Record<string, string> = {}
+  for (const pair of raw.split(',')) {
+    const idx = pair.indexOf('=')
+    if (idx <= 0) continue
+    const key = pair.slice(0, idx).trim()
+    const value = pair.slice(idx + 1).trim()
+    if (key && value) headers[key] = value
+  }
+  return headers
+}

package/src/modules/telemetry/__integration__/TC-TELEMETRY-001.spec.ts

@@ -0,0 +1,50 @@
+import { expect, test } from '@playwright/test'
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-TELEMETRY-001: browser RUM span-ingest proxy contract.
+ *
+ * Route: POST /api/telemetry/browser-traces (requireAuth). The proxy accepts
+ * OTLP/HTTP batches from authenticated backoffice sessions and forwards them
+ * to the configured collector. It is deliberately fire-and-forget: when browser
+ * telemetry is disabled for the environment (the default, and the state of the
+ * integration test env) it accepts and drops with 204 so a stale client never
+ * retries. Oversized payloads are refused with 413 before buffering.
+ */
+test.describe('TC-TELEMETRY-001: browser traces proxy', () => {
+  let token = ''
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test('unauthenticated span ingest is rejected', async ({ request }) => {
+    const res = await request.post('/api/telemetry/browser-traces', {
+      headers: { 'Content-Type': 'application/json' },
+      data: { resourceSpans: [] },
+    })
+    expect(res.status(), 'span ingest must not be an unauthenticated endpoint').toBe(401)
+  })
+
+  test('authenticated batch is accepted', async ({ request }) => {
+    const res = await apiRequest(request, 'POST', '/api/telemetry/browser-traces', {
+      token,
+      data: { resourceSpans: [] },
+    })
+    // 204 = telemetry disabled for the environment (accept-and-drop, the
+    // default here); 202 = forwarded to a configured collector.
+    expect([204, 202], 'an authenticated batch is always accepted').toContain(res.status())
+  })
+
+  test('an oversized payload is refused with 413', async ({ request }) => {
+    const oversized = `{"resourceSpans":["${'x'.repeat(1_100_000)}"]}`
+    const res = await request.post('/api/telemetry/browser-traces', {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      data: oversized,
+    })
+    expect(res.status(), 'payloads above the 1 MB cap are refused').toBe(413)
+  })
+})

package/src/modules/telemetry/__integration__/TC-TELEMETRY-002.spec.ts

@@ -0,0 +1,179 @@
+import { expect, test, type Page, type Request as PlaywrightRequest } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+
+/**
+ * TC-TELEMETRY-002: browser RUM in a real browser.
+ *
+ * TC-TELEMETRY-001 drives the proxy route with `request.post` — a useful API contract test that
+ * never opens a page. This spec covers what only a browser can: that the SDK actually boots, that
+ * the `__omOriginalFetch` patch dance leaves both fetch paths working (a recursion here hangs every
+ * API call in the backoffice), that batches reach the proxy, and — the mirror image — that a
+ * default environment ships none of it.
+ *
+ * Browser RUM is normally an environment-wide env switch, which a spec cannot flip for one page.
+ * The integration environment therefore sets `OM_TEST_BROWSER_TELEMETRY_MODE=opt-in` on top of
+ * `OM_TEST_MODE=1`, and only then does the server honour an `om_test_browser_telemetry=on` cookie.
+ * Both variables are absent in production. Same escape hatch the auth rate limiter already uses.
+ *
+ * No collector is configured here, so the proxy answers 204 (accept-and-drop) rather than 202 —
+ * which is why the span assertions read the batch the *browser posted* instead of anything a sink
+ * received. That is the stronger assertion anyway: it is the browser's output under test.
+ */
+
+const TRACES_PATH = '/api/telemetry/browser-traces'
+const OPT_IN_COOKIE = 'om_test_browser_telemetry'
+
+type IngestRecord = { status: number; body: string }
+
+/** Records every proxy call the page makes, with the payload the exporter actually produced. */
+function recordIngest(page: Page): IngestRecord[] {
+  const records: IngestRecord[] = []
+  page.on('response', async (response) => {
+    if (!response.url().includes(TRACES_PATH)) return
+    const request: PlaywrightRequest = response.request()
+    if (request.method() !== 'POST') return
+    records.push({ status: response.status(), body: request.postData() ?? '' })
+  })
+  return records
+}
+
+/**
+ * Records the same-origin API GETs the backoffice itself made and that answered 200. Replaying a
+ * real one beats naming an endpoint here: the set of routes is not this spec's business, and a
+ * path that quietly stops existing would fail the test for the wrong reason.
+ */
+function recordApiGets(page: Page): string[] {
+  const urls: string[] = []
+  page.on('response', (response) => {
+    const request = response.request()
+    if (request.method() !== 'GET') return
+    if (response.status() !== 200) return
+    try {
+      const { pathname } = new URL(response.url())
+      if (!pathname.startsWith('/api/') || pathname.startsWith(TRACES_PATH)) return
+      urls.push(response.url())
+    } catch {
+      // A non-absolute or exotic URL is simply not a candidate for replay.
+    }
+  })
+  return urls
+}
+
+/** The web SDK registers itself on this global symbol; its presence is the "SDK booted" signal. */
+async function otelApiIsRegistered(page: Page): Promise<boolean> {
+  return page.evaluate(() =>
+    Object.getOwnPropertySymbols(globalThis).some((symbol) => symbol.toString().includes('opentelemetry.js.api')),
+  )
+}
+
+test.describe('TC-TELEMETRY-002: browser RUM runtime', () => {
+  test('exports document-load and fetch spans without breaking either fetch path', async ({ page, baseURL }) => {
+    const origin = new URL(baseURL ?? 'http://localhost:3000').origin
+    await page.context().addCookies([{ name: OPT_IN_COOKIE, value: 'on', url: origin }])
+    const ingest = recordIngest(page)
+    const apiGets = recordApiGets(page)
+
+    await login(page, 'admin')
+    await page.goto('/backend')
+    await expect.poll(() => otelApiIsRegistered(page), {
+      message: 'the web SDK must boot once the server hands the layout a non-null config',
+      timeout: 15_000,
+    }).toBe(true)
+
+    // The patch dance, asserted where it actually runs. `@open-mercato/ui`'s api utils stash the
+    // pristine fetch on `__omOriginalFetch` and put a wrapper on `window.fetch`; the SDK has to
+    // instrument the stash rather than the wrapper, or direct `apiFetch` callers (DataTable,
+    // CrudForm, react-query) produce no spans at all.
+    const patchState = await page.evaluate(() => {
+      const w = window as Window & { __omOriginalFetch?: typeof window.fetch }
+      return {
+        hasStash: typeof w.__omOriginalFetch === 'function',
+        // Identical would mean the wrapper was handed back to itself — an infinite recursion on
+        // the first request through `apiFetch`.
+        stashIsWrapper: w.__omOriginalFetch === window.fetch,
+      }
+    })
+    expect(patchState.hasStash, '@open-mercato/ui installs the fetch wrapper on every backoffice page').toBe(true)
+    expect(patchState.stashIsWrapper, 'instrumenting the wrapper instead of the native fetch recurses forever').toBe(false)
+
+    // A DataTable page drives `apiFetch` (which reads the instrumented stash) end to end. Waiting
+    // on the API call it makes, rather than on a DOM role, keeps this assertion about the thing
+    // under test: that the swap left `apiFetch` able to reach the API at all.
+    await expect.poll(() => apiGets.length, {
+      message: 'the backoffice must still reach its own API through the patched fetch',
+      timeout: 30_000,
+    }).toBeGreaterThan(0)
+    await page.goto('/backend/customers/people')
+    await expect(page.locator('table, [role="grid"]').first()).toBeVisible({ timeout: 30_000 })
+
+    // Replay one of the page's OWN successful GETs down both paths. A hang here IS the recursion
+    // bug, hence the tight budget; a non-200 means the swap broke the wrapper's auth handling.
+    const replayUrl = apiGets[apiGets.length - 1]
+    const replay = await page.evaluate(async (url: string) => {
+      const w = window as Window & { __omOriginalFetch?: typeof window.fetch }
+      const withTimeout = async (call: Promise<Response>) => {
+        const timeout = new Promise<never>((_, reject) => setTimeout(() => reject(new Error('timeout')), 10_000))
+        return (await Promise.race([call, timeout])).status
+      }
+      return {
+        viaWindow: await withTimeout(window.fetch(url)),
+        viaStash: await withTimeout(w.__omOriginalFetch!(url)),
+      }
+    }, replayUrl)
+    expect(replay.viaWindow, `window.fetch must still reach ${replayUrl} through the framework wrapper`).toBe(200)
+    expect(replay.viaStash, `the instrumented native fetch must still reach ${replayUrl}`).toBe(200)
+
+    // Exports are batched on a 3s delay, and a flush is forced when the page is hidden.
+    await page.evaluate(() => {
+      Object.defineProperty(document, 'visibilityState', { value: 'hidden', configurable: true })
+      document.dispatchEvent(new Event('visibilitychange'))
+    })
+    await expect.poll(() => ingest.length, {
+      message: 'the exporter must post its batches to the same-origin proxy',
+      timeout: 20_000,
+    }).toBeGreaterThan(0)
+
+    // Every answer must be one the OTLP exporter does NOT retry (429/502/503/504 would storm).
+    for (const record of ingest) {
+      expect([202, 204], `unexpected ingest status ${record.status}`).toContain(record.status)
+    }
+
+    const spanNames = ingest.flatMap((record) => {
+      try {
+        const payload = JSON.parse(record.body) as {
+          resourceSpans?: Array<{
+            resource?: { attributes?: Array<{ key: string; value?: { stringValue?: string } }> }
+            scopeSpans?: Array<{ spans?: Array<{ name: string }> }>
+          }>
+        }
+        for (const resourceSpan of payload.resourceSpans ?? []) {
+          const serviceName = resourceSpan.resource?.attributes?.find((a) => a.key === 'service.name')
+          expect(
+            serviceName?.value?.stringValue,
+            'browser spans must carry their own service name so they sort apart from server spans',
+          ).toMatch(/-browser$/)
+        }
+        return (payload.resourceSpans ?? []).flatMap((r) => (r.scopeSpans ?? []).flatMap((s) => s.spans ?? [])).map((s) => s.name)
+      } catch {
+        return []
+      }
+    })
+    expect(spanNames, 'document-load instrumentation must produce the navigation span').toContain('documentLoad')
+    expect(spanNames, 'document-load instrumentation must produce the document fetch span').toContain('documentFetch')
+  })
+
+  test('ships nothing at all without the opt-in — the default path must cost a disabled app zero bytes', async ({ page }) => {
+    // No cookie: this is the shipped default, and the mirror image of the case above. It is the
+    // assertion that protects the "zero client-bundle cost while off" promise from regressing.
+    const ingest = recordIngest(page)
+
+    await login(page, 'admin')
+    await page.goto('/backend')
+    await page.goto('/backend/customers/people')
+    await expect(page.locator('table, [role="grid"]').first()).toBeVisible({ timeout: 30_000 })
+    await page.waitForTimeout(5_000)
+
+    expect(await otelApiIsRegistered(page), 'the web SDK chunk must never be requested while RUM is off').toBe(false)
+    expect(ingest, 'a disabled app must not post a single batch').toHaveLength(0)
+  })
+})

package/src/modules/telemetry/api/browser-traces/route.ts

@@ -0,0 +1,206 @@
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { RateLimiterService } from '@open-mercato/shared/lib/ratelimit/service'
+import type { RateLimitConfig } from '@open-mercato/shared/lib/ratelimit/types'
+import {
+  resolveBrowserTelemetryConfig,
+  resolveCollectorHeaders,
+  resolveCollectorTracesUrl,
+} from '../../../../browser/server'
+
+const logger = createLogger('telemetry').child({ component: 'browser-traces' })
+
+export const metadata = {
+  // Sending a span is not a privileged action — every authenticated backoffice user may do it, so
+  // no feature grant. `requireAuth: true` is what keeps an unauthenticated span-ingest endpoint off
+  // a public host.
+  //
+  // Deliberately NO dispatcher-level `rateLimit`. That limiter keys on the client IP and falls back
+  // to a single `'global'` bucket whenever `RATE_LIMIT_TRUST_PROXY_DEPTH` is 0 (the default), so one
+  // flat budget would be shared by every browser in the deployment — and it answers `429`, which is
+  // in the OTLP exporter's retryable set (`429 || 502 || 503 || 504`). That combination would make
+  // a handful of busy tabs trigger the retry storm the handler below exists to prevent, under
+  // normal load rather than during an outage. The budget is enforced per authenticated user inside
+  // the handler instead, where it can answer with a non-retryable status.
+  POST: {
+    requireAuth: true,
+  },
+}
+
+/**
+ * Per-user ingest budget, sized from the export cadence rather than picked round: the
+ * `BatchSpanProcessor` in `BrowserTelemetry.tsx` uses `scheduledDelayMillis: 3_000`, i.e. at most
+ * 20 export requests per minute per open tab. 400/min therefore covers ~20 concurrent backoffice
+ * tabs for one user before anything is shed, and a user who exceeds it can only ever starve
+ * themselves — never the rest of the deployment, which the shared IP bucket could.
+ */
+const INGEST_BUDGET: RateLimitConfig = {
+  points: 400,
+  duration: 60,
+  keyPrefix: 'telemetry_browser_traces',
+}
+
+export const openApi = {
+  tags: ['Telemetry'],
+  summary: 'Same-origin OTLP/HTTP trace ingest for browser RUM spans — forwards to the collector',
+}
+
+/** Batched browser exports are a few KB; 1 MB is a generous ceiling that still refuses abuse. */
+const MAX_BODY_BYTES = 1_000_000
+/** The collector is expected to be one hop away (in-cluster or a tunnel). */
+const COLLECTOR_TIMEOUT_MS = 5_000
+
+/**
+ * Proxies a browser OTLP/HTTP trace payload to the environment's collector, adding the
+ * credential server-side.
+ *
+ * Deliberately fire-and-forget: a telemetry pipeline must never be able to degrade the app it
+ * measures, so every failure path returns a success-ish status and is logged instead. Dropped spans
+ * are cheaper than a retry storm from every open browser tab.
+ *
+ * That is why a collector failure answers 202 rather than 502: 502 is in the OTLP exporter's
+ * retryable set (`429 || 502 || 503 || 504`), so a collector outage would make every open tab
+ * retry each batch with backoff — the exact amplification this contract rules out — and surface a
+ * failed request in the user's devtools on every attempt. The outage is observable in the server
+ * log instead, where it belongs.
+ *
+ * Raw `fetch` is correct here (the AGENTS.md rule targets app-to-own-API calls that have a framework
+ * primitive) — this is a server-to-collector hop over plain OTLP/HTTP with no DI-provided client.
+ */
+export async function POST(req: Request, ctx?: { auth?: AuthContext | null }): Promise<Response> {
+  // Refuse on the declared size BEFORE anything else: App Router route handlers have no default
+  // body limit, so reading first would let an authenticated client force a large allocation. A
+  // caller can lie or omit content-length, hence the second check inside the read — but the honest
+  // path (the OTel exporter always sets it) never allocates. Checked even while disabled so the
+  // size cap is an unconditional contract of the endpoint.
+  const declaredLength = Number(req.headers.get('content-length'))
+  if (Number.isFinite(declaredLength) && declaredLength > MAX_BODY_BYTES) {
+    return new Response(null, { status: 413 })
+  }
+
+  // Not configured / disabled for this environment: accept and drop, so a stale client that still
+  // has the SDK loaded doesn't retry or surface errors.
+  if (!resolveBrowserTelemetryConfig({ cookieHeader: req.headers.get('cookie') })) {
+    return new Response(null, { status: 204 })
+  }
+
+  // Over the per-user budget: drop the batch with the same non-retryable accept-and-drop status a
+  // disabled environment uses. A `429` here would be read as retryable by the exporter and turn a
+  // single looping tab into a backoff storm.
+  if (await isOverIngestBudget(ctx?.auth?.sub)) return new Response(null, { status: 204 })
+
+  const target = resolveCollectorTracesUrl()
+  if (!target) return new Response(null, { status: 204 })
+
+  const body = await readCappedBody(req)
+  if (body === null) return new Response(null, { status: 413 })
+  if (body.byteLength === 0) return new Response(null, { status: 202 })
+
+  try {
+    const res = await fetch(target, {
+      method: 'POST',
+      headers: {
+        // Credential and operator headers first, so the forwarded content headers below always
+        // win: an operator whose OTEL_EXPORTER_OTLP_HEADERS happens to carry a `content-type` must
+        // not silently relabel the body the browser actually sent.
+        ...resolveCollectorHeaders(),
+        // The browser exporter posts JSON; keep whatever it declared so a future switch to the
+        // protobuf exporter needs no change here.
+        'content-type': req.headers.get('content-type') ?? 'application/json',
+        // Forward compression verbatim — dropping it would hand the collector a gzip blob
+        // labelled as plain JSON the moment the exporter enables compression.
+        ...(req.headers.get('content-encoding')
+          ? { 'content-encoding': req.headers.get('content-encoding') as string }
+          : {}),
+      },
+      body,
+      signal: AbortSignal.timeout(COLLECTOR_TIMEOUT_MS),
+      cache: 'no-store',
+    })
+    if (!res.ok) {
+      logger.warn('telemetry.browser.export.rejected', {
+        status: res.status,
+        bytes: body.byteLength,
+      })
+      return new Response(null, { status: 202 })
+    }
+  } catch (err) {
+    logger.warn('telemetry.browser.export.failed', {
+      error: err instanceof Error ? err.message : String(err),
+      bytes: body.byteLength,
+    })
+    return new Response(null, { status: 202 })
+  }
+
+  return new Response(null, { status: 202 })
+}
+
+/**
+ * Consumes one point of the authenticated user's ingest budget and reports whether the batch
+ * should be shed.
+ *
+ * Fails open in every degraded case — no user id, no limiter registered, a limiter whose backing
+ * store is unreachable, or a throw on the way there. An unenforced telemetry budget is strictly
+ * better than a telemetry endpoint that starts refusing traffic because its limiter is sick.
+ */
+async function isOverIngestBudget(userId: string | null | undefined): Promise<boolean> {
+  if (!userId) return false
+  try {
+    const container = await createRequestContainer()
+    const limiter = tryResolve<RateLimiterService>(container, 'rateLimiterService')
+    if (!limiter) return false
+    const result = await limiter.consume(userId, INGEST_BUDGET)
+    if (result.allowed || result.degraded) return false
+    logger.warn('telemetry.browser.export.throttled', {
+      userId,
+      budgetPerMinute: INGEST_BUDGET.points,
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function tryResolve<T>(container: { resolve: (name: string) => unknown }, name: string): T | null {
+  try {
+    return (container.resolve(name) as T) ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Reads the body but abandons it the moment it exceeds the cap, so a client that omits or
+ * understates `content-length` still cannot make us buffer an arbitrary payload. Returns `null`
+ * when the cap is breached.
+ */
+async function readCappedBody(req: Request): Promise<ArrayBuffer | null> {
+  if (!req.body) return new ArrayBuffer(0)
+  const reader = req.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > MAX_BODY_BYTES) {
+        await reader.cancel()
+        return null
+      }
+      chunks.push(value)
+    }
+  } catch {
+    return null
+  }
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  // `.buffer` is exactly the allocation above, so the cast is sound and keeps `fetch` happy
+  // (a generic Uint8Array is not assignable to BodyInit under this TS lib).
+  return out.buffer as ArrayBuffer
+}

package/src/modules/telemetry/index.ts

@@ -0,0 +1,15 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+
+// Browser RUM support. The browser usually cannot reach the OTLP collector
+// directly (in-cluster service, auth in front of it), so this module owns the
+// same-origin proxy the browser exporter posts to. Server-side telemetry stays
+// with the `@open-mercato/telemetry` facade — this module never initializes it.
+export const metadata: ModuleInfo = {
+  name: 'telemetry',
+  title: 'Telemetry',
+  version: '0.1.0',
+  description:
+    'Same-origin OTLP proxy for browser RUM spans (document load, fetch, user interaction), ' +
+    'forwarding to the collector configured for the environment.',
+  author: 'Open Mercato Team',
+}

package/src/provider/otlp-provider.ts

@@ -59,6 +59,7 @@ import type {
   TraceContext,
 } from '../types'
 import { readTelemetryEnv } from '../env'
+import { BACKUP_TRACEPARENT_HEADER, BACKUP_TRACESTATE_HEADER } from '../trace-headers'
 import { redactAttributes, redactPii } from '../facade/redact'
 import { serializeError } from '../facade/serialize'
 import { runSpan } from './run-span'
@@ -74,8 +75,8 @@ const queuePropagator = new W3CTraceContextPropagator()
 const W3C_TRACEPARENT = 'traceparent'
 const W3C_TRACESTATE = 'tracestate'
 // Backup headers that mirror the W3C context but a proxy/LB won't rewrite.
-const BACKUP_TRACEPARENT = 'x-original-traceparent'
-const BACKUP_TRACESTATE = 'x-original-tracestate'
+const BACKUP_TRACEPARENT = BACKUP_TRACEPARENT_HEADER
+const BACKUP_TRACESTATE = BACKUP_TRACESTATE_HEADER
 
 /**
  * Global propagator: standard W3C plus a backup copy

package/src/trace-headers.ts

@@ -0,0 +1,16 @@
+/**
+ * Backup trace headers shared by the server propagator (`provider/otlp-provider.ts`)
+ * and the browser RUM wiring (`browser/`). Kept in a dependency-free module so the
+ * client bundle can import the names without pulling any server-only code.
+ *
+ * The "backup header" pattern: our own callers inject `x-original-traceparent`
+ * alongside the standard `traceparent`, so the original context survives a proxy
+ * that rewrites `traceparent` in between. The backup header is *not* itself a
+ * trust signal — at an HTTP boundary it is caller-controlled exactly like the
+ * standard one, so the server ignores both and starts a fresh root unless
+ * `TELEMETRY_TRUST_INBOUND_TRACE=true`. That flag is the supported way to stitch
+ * a browser span to its server span; see `browser/propagator.ts` and the
+ * extractor in `provider/otlp-provider.ts`.
+ */
+export const BACKUP_TRACEPARENT_HEADER = 'x-original-traceparent'
+export const BACKUP_TRACESTATE_HEADER = 'x-original-tracestate'