From 37393f5dc5e662d4d5d02f3a88dd92d0c7090e89 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:09:04 -0600 Subject: [PATCH] fix(browser-tracing): send API spans only for measured page loads, without timing events (#21441) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Hosted instances can send browser page-load traces to Honeycomb (#21156, #21392) > - On staging, one hour in one workspace sent about 64,000 Honeycomb events, and only about 15 were `page.load` > - Two sources make the volume: nine network timing span events on each API request span, and request spans for background polling in idle tabs > - The page-load metrics use neither of them > - This pull request drops the timing events and records API request spans only while a page load is measured > - The benefit is about 30x fewer events in a browser test, with the same page-load data and the same server trace joins ## Linked Issues or Issue Description Refs #21156, Refs #21392 **What existing behavior does this improve?** Browser tracing exports a span for every same-origin `/api/` fetch and nine network timing events on each of those spans. **Subsystem affected** UI browser tracing (`ui/src/lib/browser-tracing/`), on hosted instances with browser tracing turned on. **Current behavior** Honeycomb stores each span event as its own event. Each request span becomes about 10 events. Idle tabs poll (for example live runs every 3 s on a task page), so most spans are requests that no page load made. On staging: about 6,600 `GET` spans plus about 6,400 of each timing event per hour, against about 15 `page.load` spans. **Proposed behavior** Request spans carry no timing events. A request is recorded only when it starts while a `page.load` measurement is open. Other requests send no span and no `traceparent`. **Reason and benefit** Event volume drops by about 30x for an idle tab. `page.load`, Web Vitals, and the Resource Timing backfill do not change. No exported request span lacks its `page.load` parent, and no server span points at a browser span that was never sent. ## What Changed - `sdk.ts`: the fetch instrumentation runs with `ignoreNetworkEvents: true` (an option of the installed `@opentelemetry/instrumentation-fetch` 0.221.0). - `sdk.ts`: new `measuredRequestsOnly` wraps the tracer provider that only the fetch instrumentation uses. When no `page.load` is open, it returns a non-recording span with an invalid context. Nothing is exported. The W3C propagator sends no `traceparent` for an invalid context, so the server traces that request alone, as for an unsampled tab. The `page.load`, Web Vitals, and backfill spans use the normal tracer and do not change. - Failed idle requests are not kept. The server's own request span records server errors. To keep them, the browser must record every idle request and send its `traceparent` before it knows the status, and that brings back the dangling joins. - `span-sanitizer.ts`: comment update only. - `doc/browser-performance-tracing.md`: new "Live API spans" section with the rule, the note that timing events are not sent, and updated volume and trace-header text. ## Verification - Red then green (`ui/src/lib/browser-tracing/sdk.test.ts`): - `records no span and sends no traceparent for an API request made while no page load is measured`: failed on the old code (an idle request sent `traceparent`), passes now. - `sends request spans without per-request network timing events`: failed on the old code (9 timing events on the request span), passes now. - All 56 tests in `ui/src/lib/browser-tracing/` pass. `tsc --noEmit` for `ui` passes. - `pnpm verify` exits 2 because a doc is a global CI input. CI supplies the broad coverage. - Real browser: local dev server on an isolated empty instance with 8 tasks, a stand-in OTLP collector, headless Chromium, and the tracing config injected into the session response. Scenario: hard load of the all-tasks page, click a task, then 2 minutes idle. One Honeycomb event = one span or one span event. | Name | master | this branch | | --- | ---: | ---: | | `page.load` | 2 | 2 | | `web_vital.lcp` | 1 | 1 | | `HTTP` (backfill) | 33 | 32 | | `GET` | 165 | 18 | | `POST` | 1 | 1 | | each of `fetchStart`, `domainLookupStart`, `domainLookupEnd`, `connectStart`, `connectEnd`, `requestStart`, `responseStart`, `responseEnd` | 165 | 0 | | **Total events** | **1,522** | **54** | - `secureConnectionStart` does not appear locally because the dev server is plain HTTP. On staging it is the ninth event. - Branch: the hard `page.load` has 32 `HTTP` children and the client `page.load` of the task has 19 live children (`GET`, `POST`). 0 request spans without a `page.load` parent (master: 146). 19 requests sent `traceparent`, and all 19 point at an exported span (master: 172 sent, 6 point at spans never exported). - Idle traffic in this test (210 `/api/` requests in total): `GET /api/issues/:id/live-runs` 88 times in 2 minutes, and `GET /api/health` 44 times (a dev-server-only 2 s poll). Most of the rest are one-off refetches. - Bundle (`vite build`): entry 3,826,982 B raw both, gzip 1,156,148 → 1,156,173 B (+25 B, chunk hash). Lazy SDK chunk 85,423 → 85,825 B raw, 27,723 → 27,859 B gzip. ## Risks - Low risk. The change is limited to the operator-gated browser tracing path on hosted instances. - Behavior shift: Honeycomb no longer has browser spans for requests made outside a page load, such as polling and mutations in a loaded page. Their server spans are still recorded as their own traces. - A request that starts during a page load and finishes after it is still recorded, as a child of that load. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with tool use (shell, file edits, headless Chromium). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- doc/browser-performance-tracing.md | 38 ++++++++++- ui/src/lib/browser-tracing/sdk.test.ts | 68 ++++++++++++++++++++ ui/src/lib/browser-tracing/sdk.ts | 54 ++++++++++++++-- ui/src/lib/browser-tracing/span-sanitizer.ts | 3 +- 4 files changed, 155 insertions(+), 8 deletions(-) diff --git a/doc/browser-performance-tracing.md b/doc/browser-performance-tracing.md index e82eab2efc1..e3b5ea04d45 100644 --- a/doc/browser-performance-tracing.md +++ b/doc/browser-performance-tracing.md @@ -63,7 +63,10 @@ for `0.25`), so Honeycomb's `COUNT` and percentiles are weighted correctly. Volume per sampled session: one `page.load` span per navigation, up to three `web_vital.*` spans per page lifetime, and one span per same-origin `/api/` -request made during a measured navigation or after the SDK loads. +request that starts while a navigation is being measured (see +[Live API spans](#live-api-spans)). Requests made while no navigation is being +measured, such as background polling in an idle tab, send nothing, and request +spans carry no span events. ## Load-speed cost @@ -193,9 +196,37 @@ URLs, server addresses, status messages, and event attributes, is dropped. | --- | --- | | `page.load` | One per hard load or client navigation. | | `web_vital.lcp`, `web_vital.inp`, `web_vital.cls` | Core Web Vitals, from Google's `web-vitals`, usually reported as the tab hides. Zero duration; the value is an attribute. | -| `GET`, `POST`, … | A `fetch` to this origin's `/api/`. Its `traceparent` header joins the server's request span to the same trace. While a `page.load` span is open it is the parent, so one trace shows the navigation, its API calls, and (when server tracing is on) their server spans. | +| `GET`, `POST`, … | A `fetch` to this origin's `/api/` that starts while a `page.load` span is open, as its child. Its `traceparent` header joins the server's request span to the same trace, so one trace shows the navigation, its API calls, and (when server tracing is on) their server spans. See below. | | `HTTP` | A request to this origin's `/api/` made before the SDK loaded, during a measured navigation (in practice the hard load), rebuilt from Resource Timing. See below. | +### Live API spans + +The rule: **a `fetch` to this origin's `/api/` is recorded only when it starts +while a `page.load` measurement is open.** It is a child of that `page.load` +and sends a `traceparent`, even if it finishes after the navigation ends. + +A request that starts while no measurement is open (background polling, a +refetch after a live update, a mutation in a page that already loaded) gets no +span and no `traceparent`. The fetch instrumentation receives a non-recording +span with an invalid trace context for it, so nothing is exported and the +standard trace context propagator sends no header +(`measuredRequestsOnly` in `ui/src/lib/browser-tracing/sdk.ts`). The server +traces such a request on its own, exactly as it does for a tab that is not +sampled. There is therefore no browser span without a `page.load` parent and +no server span that points at a browser span that was never sent. + +Failed idle requests are not kept either: the server's own request span +already records a server error, and keeping them would mean recording every +idle request and sending its `traceparent` before its status is known. + +Request spans carry **no span events**. The fetch instrumentation runs with +`ignoreNetworkEvents: true`, so the per-request Resource Timing events +(`fetchStart`, `domainLookupStart`, `domainLookupEnd`, `connectStart`, +`secureConnectionStart`, `connectEnd`, `requestStart`, `responseStart`, +`responseEnd`) are not sent. Honeycomb stores each span event as its own +event, so they multiplied request volume by about 10, and the span's own +duration already covers the request. + ### Backfilled API spans The hard load's API requests happen before the SDK exists. When the SDK loads, @@ -250,7 +281,8 @@ not sent here because Sentry already reports them ([observability.md](observability.md#sentry-error-monitoring)). Trace headers go only to this origin (`propagateTraceHeaderCorsUrls` is empty), -so no third party receives a `traceparent`. Same-origin requests need no CORS +and only on requests that start during a measured navigation, so no third +party receives a `traceparent`. Same-origin requests need no CORS change. The server's OpenTelemetry HTTP instrumentation continues the trace when server tracing is enabled ([observability.md](observability.md#enabling-tracing)). diff --git a/ui/src/lib/browser-tracing/sdk.test.ts b/ui/src/lib/browser-tracing/sdk.test.ts index a826417016b..082e1d6621d 100644 --- a/ui/src/lib/browser-tracing/sdk.test.ts +++ b/ui/src/lib/browser-tracing/sdk.test.ts @@ -124,6 +124,74 @@ describe("startTracingSdk", () => { const traceparent = headersOf(fetchMock.mock.calls[0]!).get("traceparent")!; expect(traceparent.split("-")[1]).toBe(pageSpan!.spanContext().traceId); }); + + it("records no span and sends no traceparent for an API request made while no page load is measured", async () => { + const recorder = idleRecorder(); + const flush = (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames; + recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "client", startTime: performance.now() }); + flush(); + handle = startTracingSdk(config, recorder, { exporter }); + + // Background polling with no navigation open. + await fetch(`${window.location.origin}/api/companies/abc/live-runs`); + await fetch(`${window.location.origin}/api/issues`, { method: "POST" }); + // The next navigation's requests are recorded again. + recorder.begin({ routeTemplate: "/:companyPrefix/issues/:issueId", loadType: "client", startTime: performance.now() }); + await fetch(`${window.location.origin}/api/issues/PAP-77`); + + const headersOf = (call: unknown[]) => new Headers((call[1] as RequestInit | undefined)?.headers); + expect(headersOf(fetchMock.mock.calls[0]!).get("traceparent")).toBeNull(); + expect(headersOf(fetchMock.mock.calls[1]!).get("traceparent")).toBeNull(); + expect(headersOf(fetchMock.mock.calls[2]!).get("traceparent")).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-01$/); + + flush(); + await new Promise((resolve) => setTimeout(resolve, 400)); + await handle.forceFlush(); + const spans = exporter.getFinishedSpans(); + const requests = spans.filter((span) => span.name !== "page.load"); + expect(requests.map((span) => span.attributes["paperclip.api.area"])).toEqual(["issues"]); + const issuePage = spans.find((span) => span.name === "page.load" && span.attributes["paperclip.page.route"] === "/:companyPrefix/issues/:issueId")!; + expect(requests[0]!.parentSpanContext?.spanId).toBe(issuePage.spanContext().spanId); + // Every exported span is a page load, a vital, or a child of a page load. + const pageSpanIds = new Set(spans.filter((span) => span.name === "page.load").map((span) => span.spanContext().spanId)); + for (const span of requests) expect(pageSpanIds.has(span.parentSpanContext!.spanId)).toBe(true); + }); + + it("sends request spans without per-request network timing events", async () => { + const recorder = idleRecorder(); + recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "client", startTime: performance.now() }); + handle = startTracingSdk(config, recorder, { exporter }); + const url = `${window.location.origin}/api/issues`; + // The browser's Resource Timing entry for the request, which the fetch + // instrumentation turns into `fetchStart`, `responseEnd`, … events. + let timing: PerformanceResourceTiming | null = null; + fetchMock.mockImplementationOnce(async () => { + const start = performance.now(); + timing = { + name: url, entryType: "resource", initiatorType: "fetch", startTime: start, + fetchStart: start, domainLookupStart: start, domainLookupEnd: start, connectStart: start, + secureConnectionStart: start, connectEnd: start, requestStart: start, responseStart: start + 0.1, + responseEnd: start + 0.2, encodedBodySize: 2, decodedBodySize: 2, + } as unknown as PerformanceResourceTiming; + return new Response("{}", { status: 200 }); + }); + const realGetEntriesByType = performance.getEntriesByType.bind(performance); + const getEntries = vi.spyOn(performance, "getEntriesByType").mockImplementation(((type: string) => + type === "resource" && timing ? [timing] : realGetEntriesByType(type)) as typeof performance.getEntriesByType); + try { + await fetch(url); + (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames(); + await new Promise((resolve) => setTimeout(resolve, 400)); + await handle.forceFlush(); + // The instrumentation found the entry, so timing events could be added. + expect(getEntries).toHaveBeenCalledWith("resource"); + } finally { + getEntries.mockRestore(); + } + const [request] = exporter.getFinishedSpans().filter((span) => span.name === "GET"); + expect(request).toBeDefined(); + expect(request!.events.map((event) => event.name)).toEqual([]); + }); }); describe("hard-load API spans from Resource Timing", () => { diff --git a/ui/src/lib/browser-tracing/sdk.ts b/ui/src/lib/browser-tracing/sdk.ts index 2a76c92f36a..aaddd955d4b 100644 --- a/ui/src/lib/browser-tracing/sdk.ts +++ b/ui/src/lib/browser-tracing/sdk.ts @@ -11,13 +11,27 @@ // Emitted spans (see doc/browser-performance-tracing.md): // page.load one per hard load or client-side navigation // web_vital.lcp|inp|cls Core Web Vitals -// GET|POST|… same-origin `/api/` fetches, with W3C trace context -// so the server's request span joins the trace +// GET|POST|… same-origin `/api/` fetches that start while a +// page.load is open, as its children, with W3C trace +// context so the server's request span joins the +// trace; no network timing events // HTTP same-origin `/api/` requests made before this chunk // loaded, rebuilt from Resource Timing under the // page.load they belong to (no method, no server join) -import { context, propagation, trace, ROOT_CONTEXT, SpanKind, type Attributes, type Context, type Span } from "@opentelemetry/api"; +import { + context, + propagation, + trace, + INVALID_SPAN_CONTEXT, + ROOT_CONTEXT, + SpanKind, + type Attributes, + type Context, + type Span, + type Tracer, + type TracerProvider, +} from "@opentelemetry/api"; import { AlwaysOnSampler, BatchSpanProcessor, @@ -55,6 +69,34 @@ class PageLoadContextManager extends StackContextManager { } } +/** + * The tracer provider given to the fetch instrumentation. A request that + * starts while no page load is being measured (background polling, a refetch + * in an idle tab) gets a non-recording span with an invalid context: nothing + * is recorded or exported, and the trace context propagator sends no + * `traceparent` for an invalid context, so the server traces that request on + * its own exactly as for an unsampled tab. A request that starts while a page + * load is open is a normal child of it. + */ +export function measuredRequestsOnly(provider: TracerProvider, isMeasuring: () => boolean): TracerProvider { + return { + getTracer(name, version, options) { + const tracer = provider.getTracer(name, version, options); + const unrecorded = () => trace.wrapSpanContext(INVALID_SPAN_CONTEXT); + const gated: Tracer = { + startSpan: (spanName, spanOptions, spanContext) => + isMeasuring() ? tracer.startSpan(spanName, spanOptions, spanContext) : unrecorded(), + startActiveSpan: ((...args: unknown[]) => { + if (isMeasuring()) return (tracer.startActiveSpan as (...a: unknown[]) => unknown)(...args); + const fn = args[args.length - 1] as (span: Span) => unknown; + return fn(unrecorded()); + }) as Tracer["startActiveSpan"], + }; + return gated; + }, + }; +} + /** Escapes a string for use inside a regular expression. */ function escapeRegExp(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); @@ -198,9 +240,13 @@ export function startTracingSdk( ignoreUrls: [nonApiUrlPattern(window.location.origin)], propagateTraceHeaderCorsUrls: [], clearTimingResources: false, + // The nine per-request timing events (fetchStart, responseEnd, …) are + // each stored as a separate event by Honeycomb, about 10x the volume of + // the request span, and its duration already covers them. + ignoreNetworkEvents: true, enabled: false, }); - fetchInstrumentation.setTracerProvider(provider); + fetchInstrumentation.setTracerProvider(measuredRequestsOnly(provider, () => openPageSpan !== null)); // Requests from here on get live fetch spans; earlier ones are backfilled. const liveFetchSince = performance.now(); fetchInstrumentation.enable(); diff --git a/ui/src/lib/browser-tracing/span-sanitizer.ts b/ui/src/lib/browser-tracing/span-sanitizer.ts index c8f00ec7d6b..b93247eb3c0 100644 --- a/ui/src/lib/browser-tracing/span-sanitizer.ts +++ b/ui/src/lib/browser-tracing/span-sanitizer.ts @@ -99,7 +99,8 @@ export function sanitizeSpan(span: ReadableSpan): ReadableSpan { status: { code: span.status.code }, attributes, links: [], - // Network timing events keep their names and times, never attributes. + // Any span event keeps its name and time, never its attributes. The fetch + // instrumentation runs with `ignoreNetworkEvents`, so request spans have none. events: span.events.map((event) => ({ name: event.name, time: event.time, droppedAttributesCount: 0 })), duration: span.duration, ended: span.ended,