fix(browser-tracing): send API spans only for measured page loads, without timing events (#21441)

## 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 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-13 13:09:04 -06:00
1 parent 08341ea134
commit 37393f5dc5
4 files changed
+155 -8

No files matched your search

+35 -3
View File
@@ -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)).
+68
View File
@@ -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", () => {
+50 -4
View File
@@ -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();
+2 -1
View File
@@ -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,