feat(frontend): propagate trace context via OpenAPI interceptor

docs/observability.md

@@ -11,7 +11,7 @@ This document describes the observability architecture for the full-stack-fastap
 ```
   Browser (React + OTEL Web SDK)
          │
-         │  W3C traceparent headers via OTEL XHR instrumentation
+         │  W3C traceparent headers via OpenAPI interceptor + OTEL context
          │
          ▼
       Traefik
@@ -58,9 +58,12 @@ This document describes the observability architecture for the full-stack-fastap
 
 ### Trace Context Propagation
 
-Frontend-to-backend trace continuity is achieved through OpenTelemetry browser instrumentation in `frontend/src/telemetry.ts`. `XMLHttpRequestInstrumentation` automatically creates client spans for Axios requests and injects W3C `traceparent` / `tracestate` headers.
+Frontend-to-backend trace continuity is intentionally split into two layers:
 
-`WebTracerProvider` in the browser registers the default W3C TraceContext propagator, so requests stay correlated without patching generated client files under `frontend/src/client/`. The backend's FastAPI auto-instrumentation extracts those headers and creates child spans, resulting in a single trace across frontend → backend → database.
+1. `frontend/src/telemetry.ts` initializes the Web SDK so browser spans exist (document load + XHR client spans).
+2. `frontend/src/telemetry-interceptor.ts` registers `OpenAPI.interceptors.request` middleware that injects W3C `traceparent` / `tracestate` headers into every generated API client request.
+
+Header injection is intentionally centralized in the interceptor (not OTEL XHR auto-propagation) so the generated-client extension point is explicit and easy to teach. This keeps generated files under `frontend/src/client/` untouched while making client-boundary propagation visible and testable. The backend's FastAPI auto-instrumentation extracts those headers and creates child spans, producing a single trace across frontend → backend → database.
 
 ### Metrics Model
 
@@ -278,5 +281,6 @@ def my_function():
 
 ### Frontend traces not linking to backend
 - Verify `traceparent` header is present in browser DevTools Network tab
+- Confirm `registerTraceContextInterceptor()` is called in `frontend/src/main.tsx`
 - Check CORS allows the `traceparent` header (should be covered by `allow_headers=["*"]`)
 - Ensure both frontend and backend OTEL are sending to the same Collector instance

frontend/src/main.tsx

@@ -13,8 +13,10 @@ import { Toaster } from "./components/ui/sonner"
 import "./index.css"
 import { routeTree } from "./routeTree.gen"
 import { initTelemetry } from "./telemetry"
+import { registerTraceContextInterceptor } from "./telemetry-interceptor"
 
 initTelemetry()
+registerTraceContextInterceptor()
 
 OpenAPI.BASE = import.meta.env.VITE_API_URL
 OpenAPI.TOKEN = async () => {

frontend/src/routeTree.gen.ts

@@ -65,14 +65,14 @@ const LayoutAdminRoute = LayoutAdminRouteImport.update({
 } as any)
 
 export interface FileRoutesByFullPath {
+  '/': typeof LayoutIndexRoute
   '/login': typeof LoginRoute
   '/recover-password': typeof RecoverPasswordRoute
   '/reset-password': typeof ResetPasswordRoute
   '/signup': typeof SignupRoute
   '/admin': typeof LayoutAdminRoute
   '/items': typeof LayoutItemsRoute
   '/settings': typeof LayoutSettingsRoute
-  '/': typeof LayoutIndexRoute
 }
 export interface FileRoutesByTo {
   '/login': typeof LoginRoute
@@ -99,14 +99,14 @@ export interface FileRoutesById {
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
+    | '/'
     | '/login'
     | '/recover-password'
     | '/reset-password'
     | '/signup'
     | '/admin'
     | '/items'
     | '/settings'
-    | '/'
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/login'
@@ -171,7 +171,7 @@ declare module '@tanstack/react-router' {
     '/_layout': {
       id: '/_layout'
       path: ''
-      fullPath: ''
+      fullPath: '/'
       preLoaderRoute: typeof LayoutRouteImport
       parentRoute: typeof rootRouteImport
     }

frontend/src/telemetry-interceptor.ts

@@ -0,0 +1,54 @@
+import { context, propagation } from "@opentelemetry/api"
+import type { AxiosRequestConfig } from "axios"
+import { OpenAPI } from "./client"
+
+let traceContextInterceptorRegistered = false
+
+const toHeaderRecord = (
+  headers: AxiosRequestConfig["headers"],
+): Record<string, string> => {
+  if (!headers) {
+    return {}
+  }
+
+  const maybeAxiosHeaders = headers as {
+    toJSON?: () => Record<string, unknown>
+  }
+  const serializedHeaders =
+    typeof maybeAxiosHeaders.toJSON === "function"
+      ? maybeAxiosHeaders.toJSON()
+      : (headers as Record<string, unknown>)
+
+  return Object.fromEntries(
+    Object.entries(serializedHeaders)
+      .filter(([, value]) => value !== undefined && value !== null)
+      .map(([key, value]) => [key, String(value)]),
+  )
+}
+
+export const traceContextInterceptor = (
+  config: AxiosRequestConfig,
+): AxiosRequestConfig => {
+  const traceHeaders: Record<string, string> = {}
+  propagation.inject(context.active(), traceHeaders)
+
+  if (Object.keys(traceHeaders).length === 0) {
+    return config
+  }
+
+  config.headers = {
+    ...toHeaderRecord(config.headers),
+    ...traceHeaders,
+  }
+
+  return config
+}
+
+export const registerTraceContextInterceptor = (): void => {
+  if (traceContextInterceptorRegistered) {
+    return
+  }
+
+  OpenAPI.interceptors.request.use(traceContextInterceptor)
+  traceContextInterceptorRegistered = true
+}

frontend/src/telemetry.ts

@@ -20,9 +20,6 @@ const removeTrailingSlash = (value: string): string => value.replace(/\/+$/, "")
 const getTraceExporterUrl = (collectorUrl: string): string =>
   `${removeTrailingSlash(collectorUrl)}/v1/traces`
 
-const escapeRegex = (value: string): string =>
-  value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-
 const toError = (value: unknown): Error => {
   if (value instanceof Error) {
     return value
@@ -106,7 +103,6 @@ export const initTelemetry = (): void => {
     const collectorUrl = collectorUrlEnv || DEFAULT_OTEL_COLLECTOR_URL
     const serviceName =
       import.meta.env.VITE_OTEL_SERVICE_NAME || DEFAULT_OTEL_SERVICE_NAME
-    const apiBaseUrl = import.meta.env.VITE_API_URL?.trim()
     const traceExporterUrl = getTraceExporterUrl(collectorUrl)
 
     const traceExporter = new OTLPTraceExporter({
@@ -127,15 +123,6 @@ export const initTelemetry = (): void => {
     const xhrConfig: XMLHttpRequestInstrumentationConfig = {
       ignoreUrls: [traceExporterUrl],
     }
-    if (apiBaseUrl) {
-      xhrConfig.propagateTraceHeaderCorsUrls = [
-        new RegExp(`^${escapeRegex(apiBaseUrl)}`),
-      ]
-    } else {
-      console.warn(
-        "[telemetry] VITE_API_URL is not set; backend trace header propagation is disabled",
-      )
-    }
 
     const xhrInstrumentation = new XMLHttpRequestInstrumentation(xhrConfig)
     xhrInstrumentation.setTracerProvider(provider)

frontend/tests/observability.spec.ts

@@ -0,0 +1,29 @@
+import { expect, test } from "@playwright/test"
+
+const TRACEPARENT_PATTERN = /^00-[0-9a-f]{32}-[0-9a-f]{16}-0[0-3]$/
+
+test("API requests include a W3C traceparent header", async ({ page }) => {
+  const observedTraceparents = new Set<string>()
+
+  page.on("request", (request) => {
+    if (!request.url().includes("/api/v1/")) {
+      return
+    }
+
+    const traceparent = request.headers().traceparent
+    if (traceparent) {
+      observedTraceparents.add(traceparent)
+    }
+  })
+
+  await page.goto("/")
+  await page.waitForResponse(
+    (response) =>
+      response.url().includes("/api/v1/users/me") && response.status() === 200,
+  )
+
+  expect(observedTraceparents.size).toBeGreaterThan(0)
+  for (const traceparent of observedTraceparents) {
+    expect(traceparent).toMatch(TRACEPARENT_PATTERN)
+  }
+})