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

package/src/__tests__/browser-server-config.test.ts

@@ -0,0 +1,265 @@
+import {
+  registerLoggerExtension,
+  resetLoggerExtension,
+  type LoggerExtensionRecord,
+} from '@open-mercato/shared/lib/logger'
+import { BROWSER_TRACES_PATH } from '../browser/config'
+import {
+  BROWSER_TELEMETRY_TEST_COOKIE,
+  resetBrowserTelemetryWarnings,
+  resolveBrowserTelemetryConfig,
+  resolveCollectorHeaders,
+  resolveCollectorTracesUrl,
+} from '../browser/server'
+import { resetTelemetryEnvCache } from '../env'
+
+// The env keys this module reads. Cleared before each case so a leaked value from the developer's
+// own .env cannot make a test pass for the wrong reason.
+const TELEMETRY_ENV_KEYS = [
+  'TELEMETRY_BROWSER_ENABLED',
+  'TELEMETRY_BROWSER_SAMPLING_RATIO',
+  'TELEMETRY_BROWSER_SERVICE_NAME',
+  'TELEMETRY_BACKEND',
+  'TELEMETRY_TRUST_INBOUND_TRACE',
+  'OTEL_EXPORTER_OTLP_ENDPOINT',
+  'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT',
+  'OTEL_EXPORTER_OTLP_HEADERS',
+  'OTEL_SERVICE_NAME',
+  'OTEL_RESOURCE_ATTRIBUTES',
+  'OM_TEST_MODE',
+  'OM_TEST_BROWSER_TELEMETRY_MODE',
+] as const
+
+describe('browser telemetry config', () => {
+  const original: Record<string, string | undefined> = {}
+
+  beforeEach(() => {
+    for (const key of TELEMETRY_ENV_KEYS) {
+      original[key] = process.env[key]
+      delete process.env[key]
+    }
+    resetTelemetryEnvCache()
+    resetBrowserTelemetryWarnings()
+  })
+
+  afterEach(() => {
+    for (const key of TELEMETRY_ENV_KEYS) {
+      if (original[key] === undefined) delete process.env[key]
+      else process.env[key] = original[key]
+    }
+    resetTelemetryEnvCache()
+  })
+
+  describe('resolveBrowserTelemetryConfig', () => {
+    it('is off unless explicitly enabled — the SDK chunk must never load by accident', () => {
+      process.env.TELEMETRY_BACKEND = 'signoz'
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://collector:4318'
+
+      expect(resolveBrowserTelemetryConfig()).toBeNull()
+    })
+
+    it('stays off when the server telemetry backend is absent or a no-op', () => {
+      process.env.TELEMETRY_BROWSER_ENABLED = 'true'
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://collector:4318'
+
+      expect(resolveBrowserTelemetryConfig()).toBeNull()
+
+      process.env.TELEMETRY_BACKEND = 'noop'
+      expect(resolveBrowserTelemetryConfig()).toBeNull()
+    })
+
+    it('stays off with a backend but no collector endpoint — RUM with nowhere to export is pure client overhead', () => {
+      process.env.TELEMETRY_BROWSER_ENABLED = 'true'
+      process.env.TELEMETRY_BACKEND = 'signoz'
+
+      expect(resolveBrowserTelemetryConfig()).toBeNull()
+    })
+
+    it('derives service name and deployment.environment from the existing server telemetry env', () => {
+      process.env.TELEMETRY_BROWSER_ENABLED = 'true'
+      process.env.TELEMETRY_BACKEND = 'signoz'
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://collector:4318'
+      process.env.OTEL_SERVICE_NAME = 'acme-oms'
+      process.env.OTEL_RESOURCE_ATTRIBUTES = 'deployment.environment=production,foo=bar'
+
+      const config = resolveBrowserTelemetryConfig()
+
+      // Separate service so RUM latency does not distort the server service's charts.
+      expect(config?.serviceName).toBe('acme-oms-browser')
+      expect(config?.environment).toBe('production')
+      // Same-origin proxy — never the collector itself.
+      expect(config?.endpoint).toBe(BROWSER_TRACES_PATH)
+    })
+
+    it('honors an explicit browser service name override', () => {
+      process.env.TELEMETRY_BROWSER_ENABLED = 'true'
+      process.env.TELEMETRY_BACKEND = 'signoz'
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://collector:4318'
+      process.env.TELEMETRY_BROWSER_SERVICE_NAME = 'storefront-rum'
+
+      expect(resolveBrowserTelemetryConfig()?.serviceName).toBe('storefront-rum')
+    })
+
+    it('tolerates OTEL_RESOURCE_ATTRIBUTES without deployment.environment', () => {
+      process.env.TELEMETRY_BROWSER_ENABLED = 'true'
+      process.env.TELEMETRY_BACKEND = 'signoz'
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://collector:4318'
+      process.env.OTEL_RESOURCE_ATTRIBUTES = 'foo=bar'
+
+      expect(resolveBrowserTelemetryConfig()?.environment).toBeNull()
+    })
+
+    it('defaults sampling to 1.0 and clamps out-of-range or garbage values', () => {
+      process.env.TELEMETRY_BROWSER_ENABLED = 'true'
+      process.env.TELEMETRY_BACKEND = 'signoz'
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://collector:4318'
+
+      expect(resolveBrowserTelemetryConfig()?.samplingRatio).toBe(1)
+
+      process.env.TELEMETRY_BROWSER_SAMPLING_RATIO = '0.25'
+      expect(resolveBrowserTelemetryConfig()?.samplingRatio).toBe(0.25)
+
+      process.env.TELEMETRY_BROWSER_SAMPLING_RATIO = '7'
+      expect(resolveBrowserTelemetryConfig()?.samplingRatio).toBe(1)
+
+      process.env.TELEMETRY_BROWSER_SAMPLING_RATIO = '-1'
+      expect(resolveBrowserTelemetryConfig()?.samplingRatio).toBe(0)
+
+      process.env.TELEMETRY_BROWSER_SAMPLING_RATIO = 'garbage'
+      expect(resolveBrowserTelemetryConfig()?.samplingRatio).toBe(1)
+    })
+  })
+
+  describe('trace-continuity warning', () => {
+    function enableRum(): void {
+      process.env.TELEMETRY_BROWSER_ENABLED = 'true'
+      process.env.TELEMETRY_BACKEND = 'signoz'
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://collector:4318'
+    }
+
+    function captureWarnings(): { records: LoggerExtensionRecord[]; dispose: () => void } {
+      const records: LoggerExtensionRecord[] = []
+      const dispose = registerLoggerExtension({ emit: (record) => records.push(record) })
+      return { records, dispose }
+    }
+
+    afterEach(() => {
+      resetLoggerExtension()
+    })
+
+    it('warns once when RUM is enabled without TELEMETRY_TRUST_INBOUND_TRACE — the spans would not stitch', () => {
+      enableRum()
+      const { records } = captureWarnings()
+
+      resolveBrowserTelemetryConfig()
+      resolveBrowserTelemetryConfig()
+
+      const warnings = records.filter((record) => record.message === 'telemetry.browser.trace_continuity_disabled')
+      // Once per process, not once per request: the layout resolves this on every page render.
+      expect(warnings).toHaveLength(1)
+      expect(warnings[0].level).toBe('warn')
+    })
+
+    it('stays quiet once the deployment opts into continuing the inbound trace', () => {
+      enableRum()
+      process.env.TELEMETRY_TRUST_INBOUND_TRACE = 'true'
+      resetTelemetryEnvCache()
+      const { records } = captureWarnings()
+
+      expect(resolveBrowserTelemetryConfig()).not.toBeNull()
+      expect(records.filter((record) => record.message === 'telemetry.browser.trace_continuity_disabled')).toHaveLength(0)
+    })
+
+    it('stays quiet while RUM is off — a disabled feature has nothing to misconfigure', () => {
+      const { records } = captureWarnings()
+
+      expect(resolveBrowserTelemetryConfig()).toBeNull()
+      expect(records).toHaveLength(0)
+    })
+  })
+
+  describe('resolveCollectorTracesUrl', () => {
+    it('appends /v1/traces to the generic endpoint, tolerating a trailing slash', () => {
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'https://collector.example.com'
+      expect(resolveCollectorTracesUrl()).toBe('https://collector.example.com/v1/traces')
+
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'https://collector.example.com/'
+      expect(resolveCollectorTracesUrl()).toBe('https://collector.example.com/v1/traces')
+    })
+
+    it('uses a signal-specific endpoint verbatim, as the OTLP spec requires', () => {
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'https://collector.example.com'
+      process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = 'https://collector.example.com/custom/traces'
+
+      expect(resolveCollectorTracesUrl()).toBe('https://collector.example.com/custom/traces')
+    })
+
+    it('returns null when nothing is configured', () => {
+      expect(resolveCollectorTracesUrl()).toBeNull()
+    })
+  })
+
+  describe('integration-test cookie opt-in', () => {
+    const ON = `${BROWSER_TELEMETRY_TEST_COOKIE}=on`
+
+    function armTestMode(): void {
+      process.env.OM_TEST_MODE = '1'
+      process.env.OM_TEST_BROWSER_TELEMETRY_MODE = 'opt-in'
+    }
+
+    it('boots RUM for a request carrying the cookie, with no telemetry env set at all', () => {
+      armTestMode()
+
+      // The point of the escape hatch: a Playwright spec can cover the enabled path for its own
+      // page without turning the web SDK on for every other spec in the environment.
+      expect(resolveBrowserTelemetryConfig({ cookieHeader: `foo=1; ${ON}; bar=2` })).toEqual({
+        endpoint: BROWSER_TRACES_PATH,
+        serviceName: 'open-mercato-browser',
+        environment: null,
+        samplingRatio: 1,
+      })
+    })
+
+    it('ignores the cookie in production, where neither test-mode variable is set', () => {
+      expect(resolveBrowserTelemetryConfig({ cookieHeader: ON })).toBeNull()
+    })
+
+    it('ignores the cookie when OM_TEST_MODE is set but the feature was not explicitly opted in', () => {
+      process.env.OM_TEST_MODE = '1'
+
+      // Two gates, not one: OM_TEST_MODE is on across the whole integration environment.
+      expect(resolveBrowserTelemetryConfig({ cookieHeader: ON })).toBeNull()
+    })
+
+    it('ignores a request without the cookie even with both gates armed', () => {
+      armTestMode()
+
+      expect(resolveBrowserTelemetryConfig({ cookieHeader: 'session=abc' })).toBeNull()
+      expect(resolveBrowserTelemetryConfig()).toBeNull()
+    })
+
+    it('does not match a cookie whose name merely ends with the opt-in name', () => {
+      armTestMode()
+
+      expect(resolveBrowserTelemetryConfig({ cookieHeader: `not_${BROWSER_TELEMETRY_TEST_COOKIE}=on` })).toBeNull()
+    })
+  })
+
+  describe('resolveCollectorHeaders', () => {
+    it('splits on the FIRST = so base64 padding in a BasicAuth credential survives', () => {
+      process.env.OTEL_EXPORTER_OTLP_HEADERS = 'Authorization=Basic b3RlbDpzZWNyZXQ='
+
+      expect(resolveCollectorHeaders()).toEqual({ Authorization: 'Basic b3RlbDpzZWNyZXQ=' })
+    })
+
+    it('parses multiple comma-separated pairs and ignores malformed ones', () => {
+      process.env.OTEL_EXPORTER_OTLP_HEADERS = 'api-key=abc123, x-tenant = t1 ,broken,=novalue'
+
+      expect(resolveCollectorHeaders()).toEqual({ 'api-key': 'abc123', 'x-tenant': 't1' })
+    })
+
+    it('returns an empty record when unset — an in-cluster collector may need no credential', () => {
+      expect(resolveCollectorHeaders()).toEqual({})
+    })
+  })
+})

package/src/__tests__/browser-traces-route.test.ts

@@ -0,0 +1,234 @@
+import { POST } from '../modules/telemetry/api/browser-traces/route'
+
+/** Stands in for the DI-registered `rateLimiterService`; `null` means none is registered. */
+const mockConsume = jest.fn(async () => ({ allowed: true, remainingPoints: 399, msBeforeNext: 0, consumedPoints: 1 }))
+let mockRateLimiter: { consume: typeof mockConsume } | null = null
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: async () => ({
+    resolve: (name: string) => {
+      if (name === 'rateLimiterService' && mockRateLimiter) return mockRateLimiter
+      throw new Error(`[internal] not registered: ${name}`)
+    },
+  }),
+}))
+
+/** The dispatcher hands the handler the resolved auth context; `sub` is the budget key. */
+const AUTHED = { auth: { sub: 'user-1' } } as Parameters<typeof POST>[1]
+
+const ENV_KEYS = [
+  'TELEMETRY_BROWSER_ENABLED',
+  'TELEMETRY_BACKEND',
+  'OTEL_EXPORTER_OTLP_ENDPOINT',
+  'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT',
+  'OTEL_EXPORTER_OTLP_HEADERS',
+] as const
+
+function enableBrowserTelemetry(): void {
+  process.env.TELEMETRY_BROWSER_ENABLED = 'true'
+  process.env.TELEMETRY_BACKEND = 'otlp'
+  process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://collector:4318'
+}
+
+/**
+ * The statuses `@opentelemetry/otlp-exporter-base/is-export-retryable` treats as retryable. Any of
+ * them on a failure path turns a collector outage into a retry storm from every open tab, which is
+ * exactly what the route's fire-and-forget contract exists to prevent.
+ */
+const EXPORTER_RETRYABLE_STATUSES = [429, 502, 503, 504]
+
+function traceRequest(init?: RequestInit & { headers?: Record<string, string> }): Request {
+  return new Request('http://localhost/api/telemetry/browser-traces', {
+    method: 'POST',
+    body: '{"resourceSpans":[]}',
+    headers: { 'content-type': 'application/json' },
+    ...init,
+  })
+}
+
+describe('browser-traces proxy route', () => {
+  const original: Record<string, string | undefined> = {}
+  const realFetch = global.fetch
+
+  beforeEach(() => {
+    for (const key of ENV_KEYS) {
+      original[key] = process.env[key]
+      delete process.env[key]
+    }
+    mockConsume.mockClear()
+    mockRateLimiter = { consume: mockConsume }
+  })
+
+  afterEach(() => {
+    for (const key of ENV_KEYS) {
+      if (original[key] === undefined) delete process.env[key]
+      else process.env[key] = original[key]
+    }
+    global.fetch = realFetch
+  })
+
+  it('accepts and drops with 204 when browser telemetry is disabled — a stale client must not retry', async () => {
+    const fetchSpy = jest.fn()
+    global.fetch = fetchSpy as typeof fetch
+
+    const res = await POST(traceRequest())
+
+    expect(res.status).toBe(204)
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+
+  it('forwards the payload to the collector with server-side credentials and returns 202', async () => {
+    enableBrowserTelemetry()
+    process.env.OTEL_EXPORTER_OTLP_HEADERS = 'api-key=secret123'
+    const fetchSpy = jest.fn(async () => new Response(null, { status: 200 }))
+    global.fetch = fetchSpy as unknown as typeof fetch
+
+    const res = await POST(traceRequest())
+
+    expect(res.status).toBe(202)
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    const [target, init] = fetchSpy.mock.calls[0] as unknown as [string, RequestInit]
+    expect(target).toBe('http://collector:4318/v1/traces')
+    expect((init.headers as Record<string, string>)['api-key']).toBe('secret123')
+    expect((init.headers as Record<string, string>)['content-type']).toBe('application/json')
+  })
+
+  it('drops the batch with a non-retryable 202 when the collector rejects it, without throwing', async () => {
+    enableBrowserTelemetry()
+    global.fetch = jest.fn(async () => new Response(null, { status: 500 })) as unknown as typeof fetch
+
+    const res = await POST(traceRequest())
+
+    expect(res.status).toBe(202)
+    expect(EXPORTER_RETRYABLE_STATUSES).not.toContain(res.status)
+  })
+
+  it('drops the batch with a non-retryable 202 when the collector is unreachable, without throwing', async () => {
+    enableBrowserTelemetry()
+    global.fetch = jest.fn(async () => {
+      throw new Error('connect ECONNREFUSED')
+    }) as unknown as typeof fetch
+
+    const res = await POST(traceRequest())
+
+    expect(res.status).toBe(202)
+    expect(EXPORTER_RETRYABLE_STATUSES).not.toContain(res.status)
+  })
+
+  it('refuses an oversized declared content-length before buffering', async () => {
+    enableBrowserTelemetry()
+    const fetchSpy = jest.fn()
+    global.fetch = fetchSpy as typeof fetch
+
+    const res = await POST(
+      traceRequest({ headers: { 'content-type': 'application/json', 'content-length': '2000000' } }),
+    )
+
+    expect(res.status).toBe(413)
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+
+  it('keeps the declared-size cap even when telemetry is disabled — the cap is an unconditional contract', async () => {
+    const res = await POST(
+      traceRequest({ headers: { 'content-type': 'application/json', 'content-length': '2000000' } }),
+    )
+
+    expect(res.status).toBe(413)
+  })
+
+  it('refuses a body that exceeds the cap even when content-length lies', async () => {
+    enableBrowserTelemetry()
+    const fetchSpy = jest.fn()
+    global.fetch = fetchSpy as typeof fetch
+
+    const oversized = 'x'.repeat(1_000_001)
+    const res = await POST(traceRequest({ body: oversized }))
+
+    expect(res.status).toBe(413)
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+
+  it('acknowledges an empty batch with 202 without calling the collector', async () => {
+    enableBrowserTelemetry()
+    const fetchSpy = jest.fn()
+    global.fetch = fetchSpy as typeof fetch
+
+    const res = await POST(traceRequest({ body: null }))
+
+    expect(res.status).toBe(202)
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+
+  it('lets operator collector headers be overridden by the content headers the browser actually sent', async () => {
+    enableBrowserTelemetry()
+    // An operator whose OTEL_EXPORTER_OTLP_HEADERS happens to carry a content-type must not silently
+    // relabel a gzipped protobuf batch as JSON.
+    process.env.OTEL_EXPORTER_OTLP_HEADERS = 'api-key=secret123,content-type=text/plain'
+    const fetchSpy = jest.fn(async () => new Response(null, { status: 200 }))
+    global.fetch = fetchSpy as unknown as typeof fetch
+
+    await POST(traceRequest({ headers: { 'content-type': 'application/x-protobuf' } }))
+
+    const [, init] = fetchSpy.mock.calls[0] as unknown as [string, RequestInit]
+    expect((init.headers as Record<string, string>)['content-type']).toBe('application/x-protobuf')
+    expect((init.headers as Record<string, string>)['api-key']).toBe('secret123')
+  })
+
+  describe('per-user ingest budget', () => {
+    it('charges the budget to the authenticated user, not to a shared bucket', async () => {
+      enableBrowserTelemetry()
+      global.fetch = jest.fn(async () => new Response(null, { status: 200 })) as unknown as typeof fetch
+
+      await POST(traceRequest(), AUTHED)
+
+      // An IP-keyed limiter collapses to one 'global' bucket at the default trust-proxy depth, so
+      // one looping tab would starve telemetry for the whole deployment.
+      expect(mockConsume).toHaveBeenCalledWith('user-1', expect.objectContaining({ points: 400, duration: 60 }))
+    })
+
+    it('drops an over-budget batch with 204 — never a status the exporter would retry', async () => {
+      enableBrowserTelemetry()
+      const fetchSpy = jest.fn()
+      global.fetch = fetchSpy as typeof fetch
+      mockConsume.mockResolvedValueOnce({ allowed: false, remainingPoints: 0, msBeforeNext: 1_000, consumedPoints: 401 })
+
+      const res = await POST(traceRequest(), AUTHED)
+
+      expect(res.status).toBe(204)
+      // 429 is in the exporter's retryable set, so throttling with it would produce exactly the
+      // backoff storm this route's status contract exists to prevent.
+      expect(EXPORTER_RETRYABLE_STATUSES).not.toContain(res.status)
+      expect(fetchSpy).not.toHaveBeenCalled()
+    })
+
+    it('fails open when the limiter is degraded — an unenforced budget beats refusing traffic', async () => {
+      enableBrowserTelemetry()
+      const fetchSpy = jest.fn(async () => new Response(null, { status: 200 }))
+      global.fetch = fetchSpy as unknown as typeof fetch
+      mockConsume.mockResolvedValueOnce({
+        allowed: false,
+        degraded: true,
+        remainingPoints: 400,
+        msBeforeNext: 0,
+        consumedPoints: 0,
+      } as Awaited<ReturnType<typeof mockConsume>>)
+
+      const res = await POST(traceRequest(), AUTHED)
+
+      expect(res.status).toBe(202)
+      expect(fetchSpy).toHaveBeenCalledTimes(1)
+    })
+
+    it('fails open when no limiter is registered at all', async () => {
+      enableBrowserTelemetry()
+      mockRateLimiter = null
+      const fetchSpy = jest.fn(async () => new Response(null, { status: 200 }))
+      global.fetch = fetchSpy as unknown as typeof fetch
+
+      const res = await POST(traceRequest(), AUTHED)
+
+      expect(res.status).toBe(202)
+      expect(fetchSpy).toHaveBeenCalledTimes(1)
+    })
+  })
+})

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

@@ -4,12 +4,14 @@
  * span shape, the delegation/nesting model, cross-boundary trace propagation
  * (same traceId), root-per-request, log correlation, and metrics.
  */
-import { SpanStatusCode, propagation, trace, context, ROOT_CONTEXT } from '@opentelemetry/api'
+import { SpanStatusCode, propagation, trace, context, defaultTextMapSetter, ROOT_CONTEXT } from '@opentelemetry/api'
+import { W3CTraceContextPropagator } from '@opentelemetry/core'
 import { InMemorySpanExporter, SimpleSpanProcessor, type ReadableSpan } from '@opentelemetry/sdk-trace-base'
 import { InMemoryLogRecordExporter, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs'
 import { InMemoryMetricExporter, PeriodicExportingMetricReader, AggregationTemporality } from '@opentelemetry/sdk-metrics'
 
 import { OtlpProvider } from '../provider/otlp-provider'
+import { createBackupHeaderPropagator } from '../browser/propagator'
 import {
   createLogger,
   resetLoggerExtension,
@@ -231,6 +233,57 @@ describe('OtlpProvider (in-memory exporters)', () => {
     expect(trace.getSpanContext(extracted)).toBeUndefined()
   })
 
+  /**
+   * Browser RUM's end-to-end promise: a span the browser started and the server span it caused
+   * share one trace. Drives the REAL browser injector (`createBackupHeaderPropagator`, the same
+   * factory `BrowserTelemetry.tsx` registers) against the REAL server extractor, with a proxy
+   * rewriting `traceparent` in between — the case the backup header exists for.
+   */
+  describe('browser RUM trace continuity', () => {
+    const browserPropagator = createBackupHeaderPropagator(
+      new W3CTraceContextPropagator(),
+      defaultTextMapSetter,
+    )
+
+    /** Headers as the browser exporter's fetch instrumentation would send them, then an LB rewrite. */
+    function browserRequestHeaders(): { headers: Record<string, string>; browserTraceId: string } {
+      const headers: Record<string, string> = {}
+      let browserTraceId = ''
+      withSpan('browser-fetch', () => {
+        browserPropagator.inject(context.active(), headers, defaultTextMapSetter)
+        browserTraceId = trace.getActiveSpan()?.spanContext().traceId ?? ''
+      })
+      // The proxy in front of the app points `traceparent` at its own unexported span.
+      headers.traceparent = `00-${'a'.repeat(32)}-${'b'.repeat(16)}-01`
+      return { headers, browserTraceId }
+    }
+
+    it('puts the server span in the browser span trace once the deployment trusts inbound context', () => {
+      const { headers, browserTraceId } = browserRequestHeaders()
+      process.env.TELEMETRY_TRUST_INBOUND_TRACE = 'true'
+      resetTelemetryEnvCache()
+
+      const inbound = propagation.extract(ROOT_CONTEXT, headers)
+      context.with(inbound, () => withSpan('server-request', () => undefined))
+
+      const serverSpan = spanExporter.getFinishedSpans().find((s) => s.name === 'server-request')
+      expect(browserTraceId).toMatch(/^[0-9a-f]{32}$/)
+      expect(serverSpan?.spanContext().traceId).toBe(browserTraceId)
+      // Not the proxy's rewritten id — that is exactly what the backup header defends against.
+      expect(serverSpan?.spanContext().traceId).not.toBe('a'.repeat(32))
+    })
+
+    it('leaves the server span in its own trace while the default trust boundary holds', () => {
+      const { headers, browserTraceId } = browserRequestHeaders()
+
+      const inbound = propagation.extract(ROOT_CONTEXT, headers)
+      context.with(inbound, () => withSpan('server-request', () => undefined))
+
+      const serverSpan = spanExporter.getFinishedSpans().find((s) => s.name === 'server-request')
+      expect(serverSpan?.spanContext().traceId).not.toBe(browserTraceId)
+    })
+  })
+
   it('redacts a leaked email from a span exception (PII backstop at the OTEL boundary)', () => {
     withSpan('pii-span', (s) => {
       s.recordException(new Error('no account for jan.kowalski@example.com'))