Browser span export works in production: same-origin OTLP → Axiom

RhysSullivan · RhysSullivan · commit 0e6d5ae722a3 · 2026-06-12T10:40:13.000-07:00
The web client's OTLP exporter now ships in the production build:
wrangler.jsonc bakes VITE_PUBLIC_OTLP_TRACES_URL=/v1/traces, the client
resolves it against the page origin, and a new worker route
(observability/browser-traces.ts) forwards the batch to Axiom with the
server-held token — the browser never sees AXIOM_TOKEN. The route runs
before the worker's server span so exporter traffic doesn't trace
itself, requires a session cookie to be present, caps body size, and
never reflects Axiom's response to the caller.

Client hardening for prod: browser-only install (the module is also
evaluated during SSR), relative exporter URLs resolved against the
page origin, and per-SESSION sampling via
VITE_PUBLIC_OTLP_SAMPLE_RATIO (a session traces everything or nothing
— per-span sampling would shred waterfalls). vite dev strips the baked
endpoint unless a local motel is actually listening, so plain bun dev
doesn't post spans into a dead proxy. e2e keeps working unchanged
(verified: 27 browser entries harvested on a fresh run).
diff --git a/apps/cloud/src/env-augment.d.ts b/apps/cloud/src/env-augment.d.ts
@@ -48,6 +48,8 @@ declare global {
 
       // Shared with frontend
       VITE_PUBLIC_SITE_URL?: string;
+      VITE_PUBLIC_OTLP_TRACES_URL?: string;
+      VITE_PUBLIC_OTLP_SAMPLE_RATIO?: string;
     }
   }
 }
diff --git a/apps/cloud/src/observability/browser-traces.test.ts b/apps/cloud/src/observability/browser-traces.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { browserTracesResponse } from "./browser-traces";
+
+const makeRequest = (init?: RequestInit & { path?: string }) =>
+  new Request(`https://executor.sh${init?.path ?? "/v1/traces"}`, {
+    method: "POST",
+    body: "{}",
+    ...init,
+  });
+
+const baseEnv = {
+  AXIOM_TOKEN: "axiom-secret",
+  AXIOM_DATASET: "executor-cloud",
+} as Env;
+
+describe("browserTracesResponse", () => {
+  it("ignores non-/v1/traces requests entirely", () => {
+    expect(
+      browserTracesResponse(makeRequest({ path: "/api/tools" }), baseEnv),
+    ).toBeNull();
+  });
+
+  it("drops batches silently when Axiom is not configured", async () => {
+    const response = await browserTracesResponse(
+      makeRequest({ headers: { cookie: "wos-session=abc" } }),
+      {} as Env,
+    );
+    expect(response?.status).toBe(204);
+  });
+
+  it("rejects anonymous posts", async () => {
+    const response = await browserTracesResponse(makeRequest(), baseEnv);
+    expect(response?.status).toBe(401);
+  });
+
+  it("forwards to Axiom with server-held credentials and hides the upstream body", async () => {
+    let seen:
+      | { url: string; auth: string | null; dataset: string | null }
+      | undefined;
+    const response = await browserTracesResponse(
+      makeRequest({ headers: { cookie: "wos-session=abc" } }),
+      baseEnv,
+      (async (url: RequestInfo | URL, init?: RequestInit) => {
+        seen = {
+          url: String(url),
+          auth: new Headers(init?.headers).get("authorization"),
+          dataset: new Headers(init?.headers).get("x-axiom-dataset"),
+        };
+        return new Response("axiom-internals", { status: 200 });
+      }) as typeof fetch,
+    );
+    expect(seen?.url).toBe("https://api.axiom.co/v1/traces");
+    expect(seen?.auth).toBe("Bearer axiom-secret");
+    expect(seen?.dataset).toBe("executor-cloud");
+    expect(response?.status).toBe(204);
+    expect(await response?.text()).toBe("");
+  });
+
+  it("reports upstream failure as 502 without leaking detail", async () => {
+    const response = await browserTracesResponse(
+      makeRequest({ headers: { cookie: "wos-session=abc" } }),
+      baseEnv,
+      (async () => new Response("denied", { status: 403 })) as typeof fetch,
+    );
+    expect(response?.status).toBe(502);
+  });
+
+  it("refuses oversized batches", async () => {
+    const response = await browserTracesResponse(
+      makeRequest({
+        headers: {
+          cookie: "wos-session=abc",
+          "content-length": String(3_000_000),
+        },
+      }),
+      baseEnv,
+    );
+    expect(response?.status).toBe(413);
+  });
+
+  it("only accepts POST", async () => {
+    const response = await browserTracesResponse(
+      new Request("https://executor.sh/v1/traces", { method: "GET" }),
+      baseEnv,
+    );
+    expect(response?.status).toBe(405);
+  });
+});
diff --git a/apps/cloud/src/observability/browser-traces.ts b/apps/cloud/src/observability/browser-traces.ts
@@ -0,0 +1,52 @@
+// Browser → Axiom OTLP ingress. The web client exports its spans to
+// same-origin /v1/traces (it can never hold AXIOM_TOKEN); this worker route
+// forwards the batch to Axiom with the server-held credentials. Locally and
+// in e2e the vite dev server proxies the same path to motel before the
+// worker ever sees it, so this route only serves deployed workers.
+//
+// Guards, not auth: the endpoint is write-only into a server-pinned dataset,
+// but it should not be an anonymous internet ingest — a session cookie must
+// at least be present, and bodies are capped. We deliberately do NOT verify
+// the session (that would put a WorkOS round-trip on every span batch).
+
+const MAX_BODY_BYTES = 2_000_000;
+
+export const BROWSER_TRACES_PATH = "/v1/traces";
+
+export const browserTracesResponse = (
+  request: Request,
+  env: Env,
+  fetchImpl: typeof fetch = fetch,
+): Promise<Response> | null => {
+  const url = new URL(request.url);
+  if (url.pathname !== BROWSER_TRACES_PATH) return null;
+  if (request.method !== "POST") {
+    return Promise.resolve(new Response(null, { status: 405 }));
+  }
+  // Tracing not configured on this deployment — accept and drop so the
+  // client exporter stays quiet (it would retry/log on errors).
+  if (!env.AXIOM_TOKEN) {
+    return Promise.resolve(new Response(null, { status: 204 }));
+  }
+  if (!(request.headers.get("cookie") ?? "").includes("wos-session=")) {
+    return Promise.resolve(new Response(null, { status: 401 }));
+  }
+  const contentLength = Number(request.headers.get("content-length") ?? 0);
+  if (contentLength > MAX_BODY_BYTES) {
+    return Promise.resolve(new Response(null, { status: 413 }));
+  }
+  return fetchImpl(env.AXIOM_TRACES_URL ?? "https://api.axiom.co/v1/traces", {
+    method: "POST",
+    headers: {
+      "content-type": request.headers.get("content-type") ?? "application/json",
+      authorization: `Bearer ${env.AXIOM_TOKEN}`,
+      "x-axiom-dataset": env.AXIOM_DATASET ?? "executor-cloud",
+    },
+    body: request.body,
+  }).then(
+    // The exporter only needs success/failure; never reflect Axiom's
+    // response body (or its headers) back to an unauthenticated caller.
+    (upstream) => new Response(null, { status: upstream.ok ? 204 : 502 }),
+    () => new Response(null, { status: 502 }),
+  );
+};
diff --git a/apps/cloud/src/server.ts b/apps/cloud/src/server.ts
@@ -10,7 +10,11 @@ import * as Sentry from "@sentry/cloudflare";
 import handler from "@tanstack/react-start/server-entry";
 
 import { McpSessionDO as McpSessionDOBase } from "./mcp/session-durable-object";
-import { flushTracerProvider, installTracerProvider } from "./observability/telemetry";
+import { browserTracesResponse } from "./observability/browser-traces";
+import {
+  flushTracerProvider,
+  installTracerProvider,
+} from "./observability/telemetry";
 
 // ---------------------------------------------------------------------------
 // Sentry config
@@ -68,6 +72,11 @@ const tracer = trace.getTracer("executor-cloud-worker");
 
 const cloudflareHandler: ExportedHandler<Env> = {
   fetch: async (request, env, ctx) => {
+    // Browser OTLP ingress — before the server span opens: exporter traffic
+    // must never trace itself (the browser already excludes /v1/traces from
+    // its own tracing for the same reason).
+    const browserTraces = browserTracesResponse(request, env);
+    if (browserTraces) return browserTraces;
     if (!installTracerProvider()) {
       return fetchHandler(request, env, ctx);
     }
@@ -76,9 +85,10 @@ const cloudflareHandler: ExportedHandler<Env> = {
     // sends traceparent on every API fetch, so the browser's spans and this
     // request share one trace id end to end. Same parsing the DO path does
     // in session-durable-object.ts.
-    const traceparentMatch = /^[0-9a-f]{2}-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(
-      request.headers.get("traceparent") ?? "",
-    );
+    const traceparentMatch =
+      /^[0-9a-f]{2}-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(
+        request.headers.get("traceparent") ?? "",
+      );
     const parentContext = traceparentMatch
       ? trace.setSpanContext(context.active(), {
           traceId: traceparentMatch[1]!,
diff --git a/apps/cloud/vite.config.ts b/apps/cloud/vite.config.ts
@@ -49,13 +49,26 @@ const loadWranglerPublicVars = () => {
 // proxy isn't routed anyway.
 const ANALYTICS_PATH = process.env.VITE_PUBLIC_ANALYTICS_PATH ?? "a";
 
-export default defineConfig(({ mode }) => {
+export default defineConfig(({ command, mode }) => {
   const env = loadEnv(mode, process.cwd(), "");
   const publicEnv = {
     ...loadWranglerPublicVars(),
     VITE_PUBLIC_ANALYTICS_PATH: ANALYTICS_PATH,
     ...env,
   };
+  // The wrangler-declared OTLP endpoint is for DEPLOYED workers (the
+  // /v1/traces forwarding route). Under `vite dev` that path is only the
+  // proxy below — keep the exporter off unless something actually listens
+  // (e2e/dev sets MOTEL_URL or the env var itself), or every dev session
+  // posts spans into a dead proxy once a second.
+  if (
+    command === "serve" &&
+    !process.env.MOTEL_URL &&
+    !env.VITE_PUBLIC_OTLP_TRACES_URL
+  ) {
+    delete (publicEnv as Record<string, string | undefined>)
+      .VITE_PUBLIC_OTLP_TRACES_URL;
+  }
 
   return {
     define: Object.fromEntries(
diff --git a/apps/cloud/wrangler.jsonc b/apps/cloud/wrangler.jsonc
@@ -62,5 +62,12 @@
   "vars": {
     "VITE_PUBLIC_SITE_URL": "https://executor.sh",
     "VITE_PUBLIC_POSTHOG_KEY": "phc_nNLrNMALpRsfrEkZovUkfMxYbcJvHnsJHeoSPavprgLL",
+    // Browser OTLP spans → same-origin, forwarded to Axiom by the worker
+    // (src/observability/browser-traces.ts). Relative on purpose: the
+    // client resolves it against the page origin, so previews work too.
+    "VITE_PUBLIC_OTLP_TRACES_URL": "/v1/traces",
+    // Per-session sampling: 1 = every signed-in session exports. Dial down
+    // (e.g. "0.1") if Axiom volume becomes a cost concern.
+    "VITE_PUBLIC_OTLP_SAMPLE_RATIO": "1",
   },
 }
diff --git a/packages/react/src/api/client.tsx b/packages/react/src/api/client.tsx
@@ -1,6 +1,10 @@
 import * as Atom from "effect/unstable/reactivity/Atom";
 import * as AtomHttpApi from "effect/unstable/reactivity/AtomHttpApi";
-import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
+import {
+  FetchHttpClient,
+  HttpClient,
+  HttpClientRequest,
+} from "effect/unstable/http";
 import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import { OtlpSerialization, OtlpTracer } from "effect/unstable/observability";
 import { ExecutorApi } from "@executor-js/api/client";
@@ -11,15 +15,21 @@ import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 
 import { reportHandledFrontendError } from "./error-reporting";
-import { getExecutorApiBaseUrl, getExecutorServerAuthorizationHeader } from "./server-connection";
+import {
+  getExecutorApiBaseUrl,
+  getExecutorServerAuthorizationHeader,
+} from "./server-connection";
 
 const isApiClientInfrastructureCause = (cause: Cause.Cause<unknown>): boolean =>
   Option.match(Cause.findErrorOption(cause), {
     onNone: () => false,
-    onSome: (error) => Schema.isSchemaError(error) || HttpClientError.isHttpClientError(error),
+    onSome: (error) =>
+      Schema.isSchemaError(error) || HttpClientError.isHttpClientError(error),
   });
 
-export const reportApiClientInfrastructureCause = (cause: Cause.Cause<unknown>) =>
+export const reportApiClientInfrastructureCause = (
+  cause: Cause.Cause<unknown>,
+) =>
   Effect.sync(() => {
     if (!isApiClientInfrastructureCause(cause)) return;
     reportHandledFrontendError(cause, {
@@ -41,7 +51,14 @@ export const reportApiClientInfrastructureCause = (cause: Cause.Cause<unknown>)
 // Plain member access — vite `define` rewrites the exact expression
 // `import.meta.env.VITE_PUBLIC_OTLP_TRACES_URL`; optional chaining would
 // dodge the replacement and always read undefined.
-const otlpTracesUrl = import.meta.env.VITE_PUBLIC_OTLP_TRACES_URL as string | undefined;
+const otlpTracesUrl = import.meta.env.VITE_PUBLIC_OTLP_TRACES_URL as
+  | string
+  | undefined;
+// Per-SESSION sampling for production: a page either traces everything it
+// does or nothing (per-span sampling would shred the waterfalls). Unset = 1.
+const otlpSampleRatio = Number(
+  (import.meta.env.VITE_PUBLIC_OTLP_SAMPLE_RATIO as string | undefined) ?? "1",
+);
 
 // The tracer must reach the runtime context the atom effects EXECUTE in.
 // Merging it into the `httpClient` option doesn't: AtomHttpApi builds the
@@ -58,17 +75,30 @@ const otlpTracesUrl = import.meta.env.VITE_PUBLIC_OTLP_TRACES_URL as string | un
 // error. URL-scoped, the leak is the desired behavior: any client posting
 // to the OTLP endpoint (the exporter) goes untraced, everything else is
 // traced.
-if (otlpTracesUrl) {
+// Browser-only (this module is also evaluated during SSR, where the worker
+// has its own tracer and a relative exporter URL would be meaningless).
+if (
+  otlpTracesUrl &&
+  typeof document !== "undefined" &&
+  Math.random() < otlpSampleRatio
+) {
   Atom.runtime.addGlobalLayer(
     Layer.mergeAll(
       OtlpTracer.layer({
-        url: otlpTracesUrl,
+        // Relative paths (the prod shape: "/v1/traces" → the worker's
+        // forwarding route) resolve against the page's own origin.
+        url: new URL(otlpTracesUrl, window.location.origin).toString(),
         resource: { serviceName: "executor-web" },
         // Browser sessions are short; the 5s default loses the tail spans
         // when the tab closes.
         exportInterval: "1 second",
-      }).pipe(Layer.provide(OtlpSerialization.layerJson), Layer.provide(FetchHttpClient.layer)),
-      Layer.succeed(HttpClient.TracerDisabledWhen, (request) => request.url.includes("/v1/traces")),
+      }).pipe(
+        Layer.provide(OtlpSerialization.layerJson),
+        Layer.provide(FetchHttpClient.layer),
+      ),
+      Layer.succeed(HttpClient.TracerDisabledWhen, (request) =>
+        request.url.includes("/v1/traces"),
+      ),
     ),
   );
 }
@@ -77,18 +107,26 @@ if (otlpTracesUrl) {
 // Core API client — tools + secrets
 // ---------------------------------------------------------------------------
 
-const ExecutorApiClient = AtomHttpApi.Service<"ExecutorApiClient">()("ExecutorApiClient", {
-  api: ExecutorApi,
-  httpClient: FetchHttpClient.layer,
-  transformClient: HttpClient.mapRequest((request) => {
-    let next = HttpClientRequest.prependUrl(request, getExecutorApiBaseUrl());
-    const authorization = getExecutorServerAuthorizationHeader();
-    if (authorization) {
-      next = HttpClientRequest.setHeader(next, "authorization", authorization);
-    }
-    return next;
-  }),
-  transformResponse: (effect) => Effect.tapCause(effect, reportApiClientInfrastructureCause),
-});
+const ExecutorApiClient = AtomHttpApi.Service<"ExecutorApiClient">()(
+  "ExecutorApiClient",
+  {
+    api: ExecutorApi,
+    httpClient: FetchHttpClient.layer,
+    transformClient: HttpClient.mapRequest((request) => {
+      let next = HttpClientRequest.prependUrl(request, getExecutorApiBaseUrl());
+      const authorization = getExecutorServerAuthorizationHeader();
+      if (authorization) {
+        next = HttpClientRequest.setHeader(
+          next,
+          "authorization",
+          authorization,
+        );
+      }
+      return next;
+    }),
+    transformResponse: (effect) =>
+      Effect.tapCause(effect, reportApiClientInfrastructureCause),
+  },
+);
 
 export { ExecutorApiClient };

Original file line number	Diff line number	Diff line change
`@@ -48,6 +48,8 @@ declare global {`
`48`	`48`
`49`	`49`	`// Shared with frontend`
`50`	`50`	`VITE_PUBLIC_SITE_URL?: string;`
	`51`	`+ VITE_PUBLIC_OTLP_TRACES_URL?: string;`
	`52`	`+ VITE_PUBLIC_OTLP_SAMPLE_RATIO?: string;`
`51`	`53`	`}`
`52`	`54`	`}`
`53`	`55`	`}`