mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
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:
1 parent
08341ea134
commit
37393f5dc5
4 files changed
+155
-8
No files matched your search
@@ -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)).
|
||||
|
||||
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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,
|
||||
|
||||
Reference in new issue
Block a user