/** * OpenTelemetry bootstrap for the apps/web browser bundle. * * Initialises a `WebTracerProvider` with a `BatchSpanProcessor` wrapped in * the shared `PIISpanProcessor` (so query-strings and disallowed headers * are stripped before the spans leave the browser). The provider becomes * the global tracer provider — `@sentry/react-router` v10 then plugs into * the same provider so both stacks share the trace_id. * * IMPORTANT: This module MUST be initialised BEFORE `Sentry.init()` in * `apps/web/app/entry.client.tsx`. The Sentry browser SDK depends on * `@opentelemetry/api`'s global TracerProvider — `WebTracerProvider.register()` * installs that provider, so calling Sentry.init afterwards is what allows * them to coexist. * * No-op when `VITE_OTEL_EXPORTER_OTLP_ENDPOINT` is empty/unset at build * time, so production builds without a configured collector keep working. * * @see docs/improvement-plan/02-observability/opentelemetry.md (Step 7 + 8) */ import { ZoneContextManager } from "@opentelemetry/context-zone"; import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch"; import { XMLHttpRequestInstrumentation } from "@opentelemetry/instrumentation-xml-http-request"; import { resourceFromAttributes } from "@opentelemetry/resources"; import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"; import { WebTracerProvider } from "@opentelemetry/sdk-trace-web"; import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions"; import { PIISpanProcessor } from "@hivegrid/observability"; export interface ClientOtelConfig { endpoint: string | undefined; serviceName: string; serviceVersion: string | undefined; deploymentEnvironment: string | undefined; serviceNamespace: string; /** * URL allowlist for which `traceparent`/`tracestate` headers may be propagated * cross-origin. Per the OWASP guidance in the spec, this MUST be an allowlist * (regex), never a wildcard, to avoid leaking the trace context to third-party * fetches (analytics, CDNs, ...). */ propagateTraceHeaderCorsUrls: RegExp[]; } const DEFAULT_SERVICE_NAME = "hivegrid-web"; const DEFAULT_SERVICE_NAMESPACE = "hivegrid"; // derived from the @hivegrid/ npm-scope /** * Reads the OTel browser configuration from Vite-injected env vars. * The `import.meta.env.*` reads happen at build time — production * builds without the env var bake a `false` endpoint into the bundle. */ export function readClientOtelConfig( env: Record = (import.meta as unknown as { env?: Record }).env ?? {}, ): ClientOtelConfig { const apiHost = env.VITE_OTEL_PROPAGATE_API_HOST || env.VITE_API_HOST || ""; const allowlist: RegExp[] = []; // Always allow same-origin (RegExp matching the empty origin trivially works). allowlist.push(/^\//); if (apiHost) { // Escape regex meta-characters in the host so VITE_API_HOST=api.example.com // is matched literally. const escaped = apiHost.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); allowlist.push(new RegExp(`^https?://${escaped}`)); } return { endpoint: env.VITE_OTEL_EXPORTER_OTLP_ENDPOINT || undefined, serviceName: env.VITE_OTEL_SERVICE_NAME || DEFAULT_SERVICE_NAME, serviceVersion: env.VITE_SENTRY_RELEASE || env.VITE_APP_REVISION || undefined, deploymentEnvironment: env.VITE_SENTRY_ENVIRONMENT || env.MODE || undefined, serviceNamespace: DEFAULT_SERVICE_NAMESPACE, propagateTraceHeaderCorsUrls: allowlist, }; } let cachedProvider: WebTracerProvider | undefined; let cachedConfig: ClientOtelConfig | undefined; /** * Initialises the OTel browser SDK. Returns `true` when init actually * happened (endpoint configured), `false` when the build had no endpoint * (no-op). Idempotent — repeat calls are short-circuited. */ export function initClientOtel(config: ClientOtelConfig = readClientOtelConfig()): boolean { if (cachedProvider) return true; cachedConfig = config; if (!config.endpoint) return false; const exporter = new OTLPTraceExporter({ url: config.endpoint }); const resource = resourceFromAttributes({ [ATTR_SERVICE_NAME]: config.serviceName, ...(config.serviceVersion ? { [ATTR_SERVICE_VERSION]: config.serviceVersion } : {}), ...(config.deploymentEnvironment ? { "deployment.environment": config.deploymentEnvironment } : {}), "service.namespace": config.serviceNamespace, }); const provider = new WebTracerProvider({ resource, spanProcessors: [new PIISpanProcessor(new BatchSpanProcessor(exporter))], }); provider.register({ contextManager: new ZoneContextManager(), }); // Wiring instrumentations directly (instead of via `registerInstrumentations`) // keeps the bundle smaller and avoids the @opentelemetry/instrumentation // peer-dep dance. const fetchInstrumentation = new FetchInstrumentation({ propagateTraceHeaderCorsUrls: config.propagateTraceHeaderCorsUrls, }); fetchInstrumentation.setTracerProvider(provider); fetchInstrumentation.enable(); const xhrInstrumentation = new XMLHttpRequestInstrumentation({ propagateTraceHeaderCorsUrls: config.propagateTraceHeaderCorsUrls, }); xhrInstrumentation.setTracerProvider(provider); xhrInstrumentation.enable(); cachedProvider = provider; return true; } /** Test-only: reset the cached provider so multiple test cases can call init. */ export function __resetClientOtelForTests(): void { cachedProvider = undefined; cachedConfig = undefined; } /** Test-only: read back the resolved config (or `undefined` when not initialised). */ export function __getClientOtelConfigForTests(): ClientOtelConfig | undefined { return cachedConfig; }