diff --git a/doc/browser-performance-tracing.md b/doc/browser-performance-tracing.md index dec60f9f939..e82eab2efc1 100644 --- a/doc/browser-performance-tracing.md +++ b/doc/browser-performance-tracing.md @@ -63,7 +63,7 @@ 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 after the SDK loads. +request made during a measured navigation or after the SDK loads. ## Load-speed cost @@ -77,10 +77,22 @@ fetching, browser idle; `ui/src/lib/when-page-settles.ts`). If the page never settles (for example a request hangs), the chunk loads 35 seconds after tracing starts anyway, so a hard load that ended as `timeout` is still exported. -Because the SDK loads after the first page settles, API requests made during -the hard load have no fetch spans. The hard load's `page.load` span is still -recorded: measurements taken before the SDK loads are buffered and exported -when it arrives. +Because the SDK loads after the first page settles, it cannot trace the hard +load's API requests live. Instead the main-bundle controller registers one +`PerformanceObserver` for `resource` entries and keeps only this +origin's `/api/` `fetch`/XHR entries, at most 500. `buffered: true` delivers +the requests that finished before tracing started (it starts once the session +request returns). After that, the observer receives every entry even when the +browser's resource buffer (250 entries by default) is full; only entries that +overflowed that buffer before tracing started are missed. When the SDK loads it turns +those entries into child spans of the `page.load` they belong to (see +[Backfilled API spans](#backfilled-api-spans)). The observer stops and the +entries are dropped once no navigation that started before the SDK loaded can +still claim them: every such navigation has ended, and either a navigation +that started after the SDK loaded has begun or 60 seconds have passed (a +navigation whose history change came before the SDK can commit after it). +Measurements taken before the SDK loads are buffered and exported when it +arrives. ## What "loaded" means @@ -112,10 +124,35 @@ it renders to `PageLoadTracker`), so a new page is measured without page code. changes are not navigations. A history replace while a navigation is still open is a redirect and continues it. -Outcomes: `ready`; `interrupted` (another navigation started first); `timeout` -(not ready after 30 seconds). A navigation open when the tab closes is not -sent. `was_hidden = true` means the tab was hidden during the measurement; -browsers pause rendering in hidden tabs, so exclude these from SLOs. +Outcomes: + +- `ready`: loaded, as defined above. +- `interrupted`: another navigation started first. +- `hidden`: the tab was hidden when the navigation started (a link opened in + a background tab) or became hidden before the page was ready. The span ends + at the moment the tab hid, so a load in a background tab has a duration of + about 0. Browsers do not paint hidden tabs, so such a load could never + become ready; this is the same rule `web-vitals` applies to LCP and FCP. + For a hard load, Chromium's `visibility-state` performance entries give the + time the tab first hid, even before tracing started; elsewhere a tab that is + hidden when tracing starts counts as hidden from navigation start. A + redirect while the tab is still hidden renames the hidden span rather than + starting another one. `was_hidden` is `true` on these spans. +- `timeout`: not ready 30 seconds after it started. The span always ends at + exactly start + 30 s, however late the browser ran the timer. Any end + observed after that deadline (for example a page that only became ready + after the computer woke up) is also reported as this timeout. + +`paperclip.page.suspended = true` marks a span during which the computer slept +or the tab was frozen: the observed end was more than 5 seconds past the +30 s deadline, or two consecutive animation frames were more than 5 seconds +apart. Its duration does not describe the page; exclude it like `hidden`. A +suspend that ends before the next frame is not detectable, but it can never +stretch a span beyond 30 s. + +A navigation open when the tab closes is not sent. For load-time percentiles +and SLOs, filter on `outcome = ready`; that excludes hidden tabs, timeouts and +interruptions, which you count separately. Pages with an explicit content signal: @@ -126,6 +163,23 @@ Pages with an explicit content signal: An agent chat with no saved task has no content signal and uses the idle rule. +### Page views + +Some pages show a different list depending on `?view=`. For those, +`paperclip.page.view` records the view (`ui/src/lib/browser-tracing/page-view.ts`), +read from the URL when the span ends, so it is the view the page resolved and +wrote into the URL. Only names from the code's view registries are sent; any +other value is `other`. + +| Route | Values | +| --- | --- | +| `/:companyPrefix/issues` | The keys of `TASK_VIEW_KEYS` in `ui/src/lib/task-views.ts` (`mine`, `unread`, `blocked`, `recent`, `everything`, `needs_attention`, `all`, `active`, `backlog`, `done`), `default` when the URL has no view yet, else `other` | +| `/:companyPrefix/decisions` | `ATTENTION_PERSONAL_VIEWS` (`mine`, `unassigned`, `company`, `archived`, `all`), `mine` when the URL has no view, else `other` | + +Switching views on the same page changes only the query string, so it is not a +new navigation and has no `page.load` span; the attribute describes the view a +navigation landed on. + To add one, call `usePageContentReady(ready)` in the page component. Use it only when the idle rule is inaccurate for that page. @@ -140,6 +194,30 @@ 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. | +| `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. | + +### Backfilled API spans + +The hard load's API requests happen before the SDK exists. When the SDK loads, +it creates one `HTTP` child span under that load's `page.load` for each +same-origin `/api/` `fetch`/XHR Resource Timing entry that started inside the +load's window (and before the SDK started tracing requests live, so nothing is +counted twice). Each runs from the entry's `startTime` to its `responseEnd`. +They differ from live fetch spans in three ways: + +- The name is `HTTP`, OpenTelemetry's name for a request whose method is + unknown: Resource Timing does not expose the method, so there is no + `http.request.method`. +- `http.response.status_code` is present only where the browser exposes + `responseStatus` (Chromium); it is never guessed. +- No `traceparent` was sent with these requests, so they do not join the + server's spans. Use `paperclip.api.area` and the timings; for the server + side, query server spans by time. + +They carry `paperclip.api.timing_source = resource_timing`. The URL is reduced +to `paperclip.api.area` by the same sanitizer as live fetch spans. + +### Attributes Attributes (the complete allowlist): @@ -147,16 +225,19 @@ Attributes (the complete allowlist): | --- | --- | --- | | `paperclip.page.route` | all | Route pattern, for example `/:companyPrefix/issues/:issueId`; `(unmatched)` when no route matches. Built only from route definitions, never from the URL. On fetch spans: the route current when the request started. On `web_vital.lcp`: the hard load's route. | | `paperclip.page.load_type` | `page.load` | `hard`, `client` | -| `paperclip.page.outcome` | `page.load` | `ready`, `interrupted`, `timeout` | +| `paperclip.page.outcome` | `page.load` | `ready`, `interrupted`, `hidden`, `timeout` | | `paperclip.page.ready_signal` | `page.load` | `content`, `idle`, `none` | | `paperclip.page.was_hidden` | `page.load` | boolean | +| `paperclip.page.suspended` | `page.load` | `true` when the computer slept or the tab froze during the measurement; absent otherwise | +| `paperclip.page.view` | `page.load` on pages with views | The view from `?view=`, from a fixed list per page, else `other`; absent on other pages | | `paperclip.page.navigation_type` | hard `page.load` | `navigate`, `reload`, `back_forward`, `prerender` | | `paperclip.page.ttfb_ms`, `paperclip.page.dom_content_loaded_ms`, `paperclip.page.load_event_ms` | hard `page.load` | Navigation Timing milestones, ms from navigation start | | `paperclip.web_vital.name` | `web_vital.*` | `LCP`, `INP`, `CLS` | | `paperclip.web_vital.value` | `web_vital.*` | ms for LCP and INP; unitless for CLS | | `paperclip.web_vital.rating` | `web_vital.*` | `good`, `needs-improvement`, `poor` | | `paperclip.api.area` | fetch | First path segment after `/api/` when it is a fixed word (`issues`, `companies`, …), else `other`. Use the joined server span's route for detail. | -| `http.request.method`, `http.response.status_code`, `error.type` | fetch | OpenTelemetry HTTP semantics | +| `paperclip.api.timing_source` | backfilled `HTTP` | `resource_timing` | +| `http.request.method`, `http.response.status_code`, `error.type` | fetch | OpenTelemetry HTTP semantics (backfilled spans: status only, where the browser exposes it) | | `SampleRate` | all, when sampling | 1-in-N weight | Resource: `service.name`, `service.version` (the UI build commit), @@ -176,17 +257,20 @@ when server tracing is enabled ([observability.md](observability.md#enabling-tra ## Example Honeycomb queries Use the `paperclip-web` dataset (or your `service.name`) and the environment -that holds browser data. Exclude hidden tabs and unfinished loads. +that holds browser data. Load-time percentiles filter on `outcome = ready`, +which leaves out hidden tabs, timeouts, and interruptions. Also leave out +suspended spans: `paperclip.page.suspended` is only ever set to `true`, so +filter on it not existing. -**P95 load time of the all-tasks page** +**P95 load time of the all-tasks page, by view** ```text VISUALIZE P95(duration_ms), COUNT WHERE name = page.load paperclip.page.route = /:companyPrefix/issues paperclip.page.outcome = ready - paperclip.page.was_hidden = false -GROUP BY paperclip.page.load_type + paperclip.page.suspended does-not-exist +GROUP BY paperclip.page.load_type, paperclip.page.view ``` **P95 load time of an individual task page** @@ -196,12 +280,22 @@ VISUALIZE P95(duration_ms), COUNT WHERE name = page.load paperclip.page.route = /:companyPrefix/issues/:issueId paperclip.page.outcome = ready - paperclip.page.was_hidden = false + paperclip.page.suspended does-not-exist GROUP BY paperclip.page.load_type ``` +**API requests during hard loads of the all-tasks page** + +```text +VISUALIZE P95(duration_ms), COUNT +WHERE paperclip.api.timing_source = resource_timing + paperclip.page.route = /:companyPrefix/issues +GROUP BY paperclip.api.area +``` + Group by `service.version` to compare builds. For a timeout rate, count -`paperclip.page.outcome = timeout` against all `page.load` spans for the route. +`paperclip.page.outcome = timeout` against `page.load` spans for the route +whose outcome is not `hidden`. For Web Vitals, `P75(paperclip.web_vital.value)` where `name = web_vital.lcp` (or `inp`, `cls`), grouped by `paperclip.page.route`. @@ -211,11 +305,13 @@ For Web Vitals, `P75(paperclip.web_vital.value)` where ```text IF(AND(EQUALS($name, "page.load"), EQUALS($paperclip.page.route, "/:companyPrefix/issues/:issueId"), - EQUALS($paperclip.page.was_hidden, false)), + IN($paperclip.page.outcome, "ready", "timeout"), + NOT(EQUALS($paperclip.page.suspended, true))), AND(EQUALS($paperclip.page.outcome, "ready"), LTE($duration_ms, 2000))) ``` -The expression is null for other events, so they do not count. +The expression is null for other events (including `hidden` and +`interrupted` loads), so they do not count; a timeout counts as a failure. ## Verifying a deployment diff --git a/ui/src/components/PageLoadTracker.test.tsx b/ui/src/components/PageLoadTracker.test.tsx index ebf0327e705..d528005b330 100644 --- a/ui/src/components/PageLoadTracker.test.tsx +++ b/ui/src/components/PageLoadTracker.test.tsx @@ -68,6 +68,17 @@ const routes = ( ); +/** + * The page's clock starts at navigation start. A test process can be older + * than the 30 s page-load timeout, which would turn the hard load (start 0) + * into a timeout, so the clock is restarted for each test. + */ +function restartPageClock() { + const realNow = performance.now.bind(performance); + const origin = realNow(); + vi.spyOn(performance, "now").mockImplementation(() => realNow() - origin); +} + describe("PageLoadTracker", () => { let container: HTMLDivElement; let root: Root | null = null; @@ -81,6 +92,7 @@ describe("PageLoadTracker", () => { measurements.ended.length = 0; resetPageSessionSampleForTest(); window.history.replaceState(null, "", "/PAP/issues"); + restartPageClock(); }); afterEach(() => { @@ -88,6 +100,7 @@ describe("PageLoadTracker", () => { root = null; container.remove(); vi.clearAllMocks(); + vi.mocked(performance.now).mockRestore?.(); }); async function render(initialPath: string) { diff --git a/ui/src/lib/browser-tracing/controller.test.ts b/ui/src/lib/browser-tracing/controller.test.ts index 932c8cd6bb3..418a5a84a15 100644 --- a/ui/src/lib/browser-tracing/controller.test.ts +++ b/ui/src/lib/browser-tracing/controller.test.ts @@ -5,6 +5,7 @@ import { QueryClient } from "@tanstack/react-query"; import type { BrowserTracingConfig } from "@paperclipai/shared"; import type { PageLoadMeasurement } from "./page-load-recorder"; import { + observeApiResources, resetPageSessionSampleForTest, SDK_LOAD_DEADLINE_MS, startBrowserTracingController, @@ -19,14 +20,101 @@ const config: BrowserTracingConfig = { sampleRate: 1, }; +/** + * The page's clock starts at navigation start. A test process can be older + * than the 30 s page-load timeout, which would turn the hard load (start 0) + * into a timeout, so the clock is restarted for each test. + */ +function restartPageClock() { + const realNow = performance.now.bind(performance); + const origin = realNow(); + vi.spyOn(performance, "now").mockImplementation(() => realNow() - origin); +} + describe("startBrowserTracingController", () => { beforeEach(() => { vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "requestAnimationFrame", "cancelAnimationFrame"] }); resetPageSessionSampleForTest(); + restartPageClock(); }); afterEach(() => { vi.useRealTimers(); + vi.restoreAllMocks(); + setVisibility("visible"); + }); + + function setVisibility(state: DocumentVisibilityState) { + Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state }); + } + + function hangingQueryClient() { + const queryClient = new QueryClient(); + void queryClient.fetchQuery({ queryKey: ["hangs"], queryFn: () => new Promise(() => {}) }); + return queryClient; + } + + function recordingSdk(ended: PageLoadMeasurement[]) { + return vi.fn(async (): Promise => ({ + startTracingSdk: (_config, recorder) => { + recorder.attachSink({ begin: () => {}, end: (m) => ended.push({ ...m }) }); + return { forceFlush: async () => {}, shutdown: async () => {} }; + }, + })); + } + + it("ends a hard load in a background tab as hidden instead of a 30 s timeout", async () => { + setVisibility("hidden"); + const ended: PageLoadMeasurement[] = []; + const controller = startBrowserTracingController(config, { + queryClient: hangingQueryClient(), + initialPathname: "/PAP/issues", + initialRouteTemplate: "/:companyPrefix/issues", + loadSdk: recordingSdk(ended), + scheduleSdkLoad: () => () => {}, + }); + await vi.advanceTimersByTimeAsync(SDK_LOAD_DEADLINE_MS); + await vi.waitFor(() => expect(ended).toHaveLength(1)); + expect(ended[0]).toMatchObject({ loadType: "hard", outcome: "hidden", startTime: 0, endTime: 0, wasHidden: true }); + controller?.stop(); + }); + + it("ends an open load as hidden when the tab hides", async () => { + const ended: PageLoadMeasurement[] = []; + const controller = startBrowserTracingController(config, { + queryClient: hangingQueryClient(), + initialPathname: "/PAP/issues", + initialRouteTemplate: "/:companyPrefix/issues", + loadSdk: recordingSdk(ended), + scheduleSdkLoad: () => () => {}, + }); + await vi.advanceTimersByTimeAsync(1_000); + setVisibility("hidden"); + const hiddenAt = performance.now(); + document.dispatchEvent(new Event("visibilitychange")); + await vi.advanceTimersByTimeAsync(SDK_LOAD_DEADLINE_MS); + await vi.waitFor(() => expect(ended).toHaveLength(1)); + expect(ended[0]!.outcome).toBe("hidden"); + expect(ended[0]!.endTime).toBeGreaterThanOrEqual(hiddenAt); + expect(ended[0]!.endTime).toBeLessThan(hiddenAt + 1_000); + controller?.stop(); + }); + + it("records the all-tasks page view from the URL", async () => { + window.history.replaceState(null, "", "/PAP/issues?view=mine&q=private-search"); + const ended: PageLoadMeasurement[] = []; + const controller = startBrowserTracingController(config, { + queryClient: hangingQueryClient(), + initialPathname: "/PAP/issues", + initialRouteTemplate: "/:companyPrefix/issues", + loadSdk: recordingSdk(ended), + scheduleSdkLoad: () => () => {}, + }); + await vi.advanceTimersByTimeAsync(SDK_LOAD_DEADLINE_MS); + await vi.waitFor(() => expect(ended).toHaveLength(1)); + expect(ended[0]!.view).toBe("mine"); + controller?.stop(); + window.history.replaceState(null, "", "/"); }); it("still loads the SDK and exports a timed-out hard load when the page never settles", async () => { @@ -79,3 +167,58 @@ describe("startBrowserTracingController", () => { controller?.stop(); }); }); + +describe("observeApiResources", () => { + type Listener = (list: { getEntries(): PerformanceEntry[] }) => void; + + function fakeObserver() { + const state: { listener: Listener | null; options: PerformanceObserverInit | null; disconnected: boolean } = { + listener: null, + options: null, + disconnected: false, + }; + class FakeObserver { + static supportedEntryTypes = ["resource"]; + constructor(listener: Listener) { + state.listener = listener; + } + observe(options: PerformanceObserverInit) { + state.options = options; + } + disconnect() { + state.disconnected = true; + } + } + return { state, Observer: FakeObserver as unknown as typeof PerformanceObserver }; + } + + const entry = (name: string, initiatorType = "fetch") => ({ name, initiatorType, entryType: "resource", startTime: 5 }) as unknown as PerformanceEntry; + + it("keeps only this origin's /api/ fetches, including ones already buffered", () => { + const { state, Observer } = fakeObserver(); + const collector = observeApiResources("https://acme.paperclip.app", Observer); + expect(state.options).toEqual({ type: "resource", buffered: true }); + state.listener!({ + getEntries: () => [ + entry("https://acme.paperclip.app/api/issues?view=mine"), + entry("https://acme.paperclip.app/api/companies", "xmlhttprequest"), + entry("https://acme.paperclip.app/assets/index.js", "script"), + entry("https://acme.paperclip.app.evil.com/api/issues"), + entry("https://api.honeycomb.io/v1/traces"), + ], + }); + expect(collector.entries().map((e) => e.name)).toEqual([ + "https://acme.paperclip.app/api/issues?view=mine", + "https://acme.paperclip.app/api/companies", + ]); + collector.stop(); + expect(state.disconnected).toBe(true); + expect(collector.entries()).toEqual([]); + }); + + it("does nothing where resource timing is unavailable", () => { + const collector = observeApiResources("https://acme.paperclip.app", null); + expect(collector.entries()).toEqual([]); + collector.stop(); + }); +}); diff --git a/ui/src/lib/browser-tracing/controller.ts b/ui/src/lib/browser-tracing/controller.ts index 77c212a9f36..9f93123946b 100644 --- a/ui/src/lib/browser-tracing/controller.ts +++ b/ui/src/lib/browser-tracing/controller.ts @@ -6,7 +6,10 @@ // - decides once per page session whether this session is sampled; an // unsampled session does nothing else and downloads nothing, // - measures the hard load and every client-side navigation -// (`page-load-recorder.ts`), and +// (`page-load-recorder.ts`), +// - keeps the Resource Timing entries of this origin's `/api/` requests +// until the SDK loads, so the SDK can show the hard load's API requests, +// and // - after the page settles, downloads the tracing SDK chunk (`sdk.ts`), // which exports the measurements, Web Vitals, and API request spans. // See doc/browser-performance-tracing.md. @@ -16,6 +19,7 @@ import type { BrowserTracingConfig } from "@paperclipai/shared"; import { whenPageSettles } from "@/lib/when-page-settles"; import { readPageContentGates } from "./page-content-gates"; import { createPageLoadRecorder, PAGE_LOAD_TIMEOUT_MS, type PageLoadRecorder } from "./page-load-recorder"; +import { pageViewFor } from "./page-view"; export type RouterNavigationType = "PUSH" | "POP" | "REPLACE"; @@ -30,8 +34,19 @@ export interface TracingSdkHandle { shutdown(): Promise; } +/** Resource Timing entries for this origin's `/api/` requests, kept until the SDK takes them. */ +export interface ApiResourceCollector { + entries(): readonly PerformanceResourceTiming[]; + /** Stops observing and drops the entries. */ + stop(): void; +} + export interface TracingSdkModule { - startTracingSdk(config: BrowserTracingConfig, recorder: PageLoadRecorder): TracingSdkHandle; + startTracingSdk( + config: BrowserTracingConfig, + recorder: PageLoadRecorder, + options?: { apiResources?: ApiResourceCollector }, + ): TracingSdkHandle; } export interface BrowserTracingControllerOptions { @@ -71,6 +86,67 @@ export function hasPendingPrimaryData(queryClient: QueryClient): boolean { return queryClient.isFetching({ predicate: (query) => query.state.data === undefined }) > 0; } +/** At most this many entries are kept; a hard load makes far fewer requests. */ +const API_RESOURCE_LIMIT = 500; + +/** + * Collects Resource Timing entries for `fetch`/XHR requests to `origin/api/`. + * `buffered: true` delivers the requests that finished before this ran (the + * hard load's session request, for example), and an observer keeps receiving + * entries after the browser's resource buffer (250 entries by default) is + * full. One observer callback per batch of finished requests; nothing else. + */ +export function observeApiResources( + origin: string, + Observer: typeof PerformanceObserver | null = typeof PerformanceObserver === "function" ? PerformanceObserver : null, +): ApiResourceCollector { + let kept: PerformanceResourceTiming[] = []; + if (!Observer || !(Observer.supportedEntryTypes ?? []).includes("resource")) { + return { entries: () => kept, stop: () => {} }; + } + const prefix = `${origin}/api/`; + let observer: PerformanceObserver | null = null; + try { + observer = new Observer((list) => { + for (const entry of list.getEntries() as PerformanceResourceTiming[]) { + if (kept.length >= API_RESOURCE_LIMIT) break; + if ((entry.initiatorType === "fetch" || entry.initiatorType === "xmlhttprequest") && entry.name.startsWith(prefix)) { + kept.push(entry); + } + } + }); + observer.observe({ type: "resource", buffered: true }); + } catch { + observer = null; + } + return { + entries: () => kept, + stop() { + observer?.disconnect(); + observer = null; + kept = []; + }, + }; +} + +/** + * When the tab was first hidden since navigation start, or null if it has + * been visible throughout. Chromium records each visibility change as a + * `visibility-state` performance entry (including the initial state); where + * it does not, a tab that is hidden now counts as hidden from the start, as + * `web-vitals` assumes. + */ +function firstHiddenTime(): number | null { + try { + const entries = performance.getEntriesByType?.("visibility-state") ?? []; + const hidden = entries.find((entry) => entry.name === "hidden"); + if (hidden) return hidden.startTime; + } catch { + // Not supported. + } + return document.visibilityState === "hidden" ? 0 : null; +} + function pathnameOf(url: string | URL | null | undefined): string | null { if (url === null || url === undefined) return null; try { @@ -136,15 +212,17 @@ export function startBrowserTracingController( isDocumentHidden: () => document.visibilityState === "hidden", hasPendingPrimaryData: () => hasPendingPrimaryData(options.queryClient), readGates: readPageContentGates, + readView: (routeTemplate) => pageViewFor(routeTemplate, window.location.search), }); + const apiResources = observeApiResources(window.location.origin); const history = trackHistoryChanges(now); const onVisibilityChange = () => { - if (document.visibilityState === "hidden") recorder.noteHidden(); + if (document.visibilityState === "hidden") recorder.noteHidden(now()); }; document.addEventListener("visibilitychange", onVisibilityChange); // The hard load started at navigation start (time 0), before this code ran. - recorder.begin({ routeTemplate: options.initialRouteTemplate, loadType: "hard", startTime: 0 }); + recorder.begin({ routeTemplate: options.initialRouteTemplate, loadType: "hard", startTime: 0, hiddenAt: firstHiddenTime() }); let lastPathname = options.initialPathname; let stopped = false; @@ -161,10 +239,11 @@ export function startBrowserTracingController( void loadSdk() .then((module) => { if (stopped) return; - sdk = module.startTracingSdk(config, recorder); + sdk = module.startTracingSdk(config, recorder, { apiResources }); }) .catch(() => { // Tracing is optional; a failed chunk load must not affect the page. + apiResources.stop(); }); }; const deadline = window.setTimeout(startLoad, options.sdkLoadDeadlineMs ?? SDK_LOAD_DEADLINE_MS); @@ -191,6 +270,7 @@ export function startBrowserTracingController( history.stop(); document.removeEventListener("visibilitychange", onVisibilityChange); recorder.stop(); + apiResources.stop(); void sdk?.shutdown(); sdk = null; }, diff --git a/ui/src/lib/browser-tracing/page-load-recorder.test.ts b/ui/src/lib/browser-tracing/page-load-recorder.test.ts index 9f8a081f8cf..3582a4ad3bf 100644 --- a/ui/src/lib/browser-tracing/page-load-recorder.test.ts +++ b/ui/src/lib/browser-tracing/page-load-recorder.test.ts @@ -10,6 +10,7 @@ function createHarness() { const state = { pendingData: false, hidden: false, + view: null as string | null, gates: { blockingCount: 0, contentCount: 0, pendingContentCount: 0, lastContentReadyAt: null } as PageContentGateSnapshot, }; const recorder = createPageLoadRecorder({ @@ -32,6 +33,7 @@ function createHarness() { isDocumentHidden: () => state.hidden, hasPendingPrimaryData: () => state.pendingData, readGates: () => state.gates, + readView: () => state.view, }); const ended: PageLoadMeasurement[] = []; const begun: PageLoadMeasurement[] = []; @@ -58,6 +60,10 @@ function createHarness() { } } }, + /** Move the clock without firing timers or frames, as a suspended computer does. */ + jump(ms: number) { + time += ms; + }, advance(ms: number) { time += ms; for (const [id, timer] of timers) { @@ -132,6 +138,17 @@ describe("createPageLoadRecorder", () => { expect(harness.recorder.open()?.routeTemplate).toBe("/b"); }); + it("ends an interrupted measurement where the next one starts, so their windows never overlap", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.state.pendingData = true; + harness.recorder.begin({ routeTemplate: "/a", loadType: "client", startTime: 0 }); + harness.advance(250); + // The router commits after the history change that started the navigation. + harness.recorder.begin({ routeTemplate: "/b", loadType: "client", startTime: 200 }); + expect(harness.ended[0]).toMatchObject({ routeTemplate: "/a", outcome: "interrupted", endTime: 200 }); + }); + it("continues a measurement through a redirect under the new route", () => { const harness = createHarness(); harness.recorder.attachSink(harness.sink); @@ -154,14 +171,118 @@ describe("createPageLoadRecorder", () => { expect(harness.ended[0]).toMatchObject({ outcome: "timeout", endTime: 30_000, readySignal: null }); }); - it("marks a measurement whose tab was hidden", () => { + it("ends a measurement as hidden, at the moment the tab hid, instead of waiting for frames that never come", () => { const harness = createHarness(); harness.recorder.attachSink(harness.sink); + harness.state.pendingData = true; harness.recorder.begin({ routeTemplate: "/a", loadType: "client", startTime: 0 }); - harness.recorder.noteHidden(); + harness.advance(400); + harness.state.hidden = true; + harness.recorder.noteHidden(400); + expect(harness.ended).toEqual([expect.objectContaining({ outcome: "hidden", endTime: 400, readySignal: null, wasHidden: true })]); + harness.advance(30_000); + expect(harness.ended).toHaveLength(1); + }); + + it("ends a load that starts in a hidden tab immediately as hidden, never as a 30 s timeout", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.state.hidden = true; + harness.state.pendingData = true; + harness.advance(900); + harness.recorder.begin({ routeTemplate: "/", loadType: "hard", startTime: 0, hiddenAt: 0 }); + expect(harness.ended).toEqual([expect.objectContaining({ outcome: "hidden", endTime: 0, loadType: "hard" })]); + harness.advance(30_000); + expect(harness.ended).toHaveLength(1); + }); + + it("ends a hard load that was hidden before tracing started at the time it hid", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.advance(900); + // Visible again by now, but rendering was paused while it was hidden. + harness.recorder.begin({ routeTemplate: "/a", loadType: "hard", startTime: 0, hiddenAt: 350 }); + expect(harness.ended[0]).toMatchObject({ outcome: "hidden", endTime: 350 }); + }); + + it("keeps a redirect after a hidden hard load on the same measurement", () => { + const harness = createHarness(); + harness.state.hidden = true; + harness.recorder.begin({ routeTemplate: "/", loadType: "hard", startTime: 0, hiddenAt: 0 }); + expect(harness.recorder.redirect("/:companyPrefix/dashboard")).toBe(true); + harness.recorder.attachSink(harness.sink); + expect(harness.ended).toEqual([expect.objectContaining({ routeTemplate: "/:companyPrefix/dashboard", outcome: "hidden" })]); + expect(harness.recorder.hardLoadRouteTemplate()).toBe("/:companyPrefix/dashboard"); + }); + + it("ends a timeout at start + timeout however late the timer fires, and marks a suspend", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.state.pendingData = true; + harness.recorder.begin({ routeTemplate: "/slow", loadType: "hard", startTime: 0 }); + // The computer slept: the 30 s timer fires about two hours later. + harness.advance(7_758_250); + expect(harness.ended).toEqual([expect.objectContaining({ outcome: "timeout", endTime: 30_000, suspended: true })]); + }); + + it("does not mark an ordinarily late timeout as suspended", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.state.pendingData = true; + harness.recorder.begin({ routeTemplate: "/slow", loadType: "client", startTime: 0 }); + harness.advance(30_400); + expect(harness.ended[0]).toMatchObject({ outcome: "timeout", endTime: 30_000, suspended: false }); + }); + + it("reports a load that only became ready after the deadline, across a suspend, as a capped timeout", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.state.pendingData = true; + harness.recorder.begin({ routeTemplate: "/a", loadType: "client", startTime: 0 }); + harness.frame(); + harness.jump(2 * 60 * 60 * 1000); + harness.state.pendingData = false; + // Frames resume before the overdue timer runs. harness.frame(); harness.frame(); - expect(harness.ended[0]).toMatchObject({ wasHidden: true }); + expect(harness.ended).toEqual([expect.objectContaining({ outcome: "timeout", endTime: 30_000, readySignal: null, suspended: true })]); + }); + + it("marks a ready load that spanned a suspend shorter than the timeout", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.state.pendingData = true; + harness.recorder.begin({ routeTemplate: "/a", loadType: "client", startTime: 0 }); + harness.frame(); + harness.jump(20_000); + harness.state.pendingData = false; + harness.frame(); + harness.frame(); + expect(harness.ended[0]).toMatchObject({ outcome: "ready", suspended: true }); + }); + + it("records the page view, read again when the measurement ends", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.state.view = "default"; + harness.recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "hard", startTime: 0 }); + expect(harness.begun[0]).toMatchObject({ view: "default" }); + // The page writes the resolved view into the URL while loading. + harness.state.view = "mine"; + harness.frame(); + harness.frame(); + expect(harness.ended[0]).toMatchObject({ view: "mine", suspended: false }); + }); + + it("keeps the view an interrupted measurement had, not the next page's", () => { + const harness = createHarness(); + harness.recorder.attachSink(harness.sink); + harness.state.pendingData = true; + harness.state.view = "mine"; + harness.recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "client", startTime: 0 }); + harness.state.view = null; + harness.recorder.begin({ routeTemplate: "/b", loadType: "client", startTime: 10 }); + expect(harness.ended[0]).toMatchObject({ outcome: "interrupted", view: "mine" }); }); it("buffers measurements that finish before the SDK attaches and replays them in order", () => { diff --git a/ui/src/lib/browser-tracing/page-load-recorder.ts b/ui/src/lib/browser-tracing/page-load-recorder.ts index 1b2aad242c2..ffb7f67b45b 100644 --- a/ui/src/lib/browser-tracing/page-load-recorder.ts +++ b/ui/src/lib/browser-tracing/page-load-recorder.ts @@ -12,13 +12,26 @@ // (the end time is the latest gate's paint time), otherwise // 2b. no query that has no data yet is fetching (the end time is the first // such frame). -// A new navigation interrupts an open one. A measurement that has not ended -// after `timeoutMs` ends with outcome `timeout`. +// A new navigation interrupts an open one. +// +// A measurement in a tab that is hidden when it starts, or that hides before +// it is ready, ends with outcome `hidden` at the moment the tab hid. Browsers +// stop painting hidden tabs, so it could never become ready; the same rule as +// `web-vitals`, which stops reporting LCP and FCP once the page has been +// hidden. +// +// A measurement that has not ended `timeoutMs` after it started ends with +// outcome `timeout`, and its end time is exactly start + `timeoutMs`. Any end +// observed after that deadline (a timer that fired late, a frame that ran +// after the computer woke up) is reported as that timeout, never as a longer +// duration. When the observed end, or a gap between two frames, is more than +// `SUSPEND_GRACE_MS` late, the measurement is marked `suspended`: the +// computer slept or the tab was frozen while it was open. import type { PageContentGateSnapshot } from "./page-content-gates"; export type PageLoadType = "hard" | "client"; -export type PageLoadOutcome = "ready" | "timeout" | "interrupted"; +export type PageLoadOutcome = "ready" | "timeout" | "interrupted" | "hidden"; export type PageLoadReadySignal = "content" | "idle"; export interface PageLoadMeasurement { @@ -32,6 +45,10 @@ export interface PageLoadMeasurement { readySignal: PageLoadReadySignal | null; /** The tab was hidden at some point during the measurement. */ wasHidden: boolean; + /** The computer slept or the tab froze while the measurement was open. */ + suspended: boolean; + /** The page's `?view=`, from an allowlist (`page-view.ts`); null for pages without views. */ + view: string | null; } /** Receives measurements; implemented by the lazily loaded tracing SDK. */ @@ -49,6 +66,8 @@ export interface PageLoadRecorderDeps { isDocumentHidden(): boolean; hasPendingPrimaryData(): boolean; readGates(): PageContentGateSnapshot; + /** The current page view for `routeTemplate` (`pageViewFor`). */ + readView?(routeTemplate: string): string | null; } export interface PageLoadRecorderOptions { @@ -59,21 +78,29 @@ export interface PageLoadRecorderOptions { } export interface PageLoadRecorder { - begin(input: { routeTemplate: string; loadType: PageLoadType; startTime: number }): PageLoadMeasurement; + /** + * `hiddenAt`: when the tab was first hidden after `startTime`, if it was + * hidden before this call (a hard load opened in a background tab). + */ + begin(input: { routeTemplate: string; loadType: PageLoadType; startTime: number; hiddenAt?: number | null }): PageLoadMeasurement; /** * A redirect (history replace) while a measurement is open continues it - * under the new route. Returns false when no measurement is open. + * under the new route, as does one right after a measurement that ended + * hidden and has not been exported yet. Returns false otherwise. */ redirect(routeTemplate: string): boolean; open(): PageLoadMeasurement | null; currentRouteTemplate(): string | null; hardLoadRouteTemplate(): string | null; - noteHidden(): void; + /** The tab became hidden at `time`: an open measurement ends as `hidden`. */ + noteHidden(time: number): void; attachSink(sink: PageLoadSink): void; stop(): void; } export const PAGE_LOAD_TIMEOUT_MS = 30_000; +/** An end, or a frame, this much later than expected means the computer slept. */ +export const SUSPEND_GRACE_MS = 5_000; export function createPageLoadRecorder( deps: PageLoadRecorderDeps, @@ -93,6 +120,8 @@ export function createPageLoadRecorder( let timer: unknown = null; let streak = 0; let streakStart = 0; + let lastFrameAt: number | null = null; + let lastEnded: PageLoadMeasurement | null = null; const buffered: PageLoadMeasurement[] = []; function cancelScheduled() { @@ -102,14 +131,31 @@ export function createPageLoadRecorder( timer = null; } + function readView(routeTemplate: string): string | null { + return deps.readView ? deps.readView(routeTemplate) : null; + } + function finish(measurement: PageLoadMeasurement, outcome: PageLoadOutcome, endTime: number, signal: PageLoadReadySignal | null) { if (current === measurement) { current = null; cancelScheduled(); } + const deadline = measurement.startTime + timeoutMs; + if (endTime > deadline) { + // Not ready by the deadline, whatever happened after it. + if (endTime - deadline > SUSPEND_GRACE_MS) measurement.suspended = true; + outcome = "timeout"; + signal = null; + endTime = deadline; + } + if (outcome === "hidden") measurement.wasHidden = true; + // An interrupted measurement keeps the view it had: the URL already + // belongs to the next page. + if (outcome !== "interrupted") measurement.view = readView(measurement.routeTemplate); measurement.outcome = outcome; measurement.readySignal = signal; measurement.endTime = Math.max(measurement.startTime, endTime); + lastEnded = measurement; if (measurement.loadType === "hard") hardLoadRoute = measurement.routeTemplate; if (sink) { sink.end(measurement); @@ -123,7 +169,13 @@ export function createPageLoadRecorder( frame = null; const measurement = current; if (!measurement || stopped) return; - if (deps.isDocumentHidden()) measurement.wasHidden = true; + const time = deps.now(); + if (deps.isDocumentHidden()) { + finish(measurement, "hidden", time, null); + return; + } + if (lastFrameAt !== null && time - lastFrameAt > SUSPEND_GRACE_MS) measurement.suspended = true; + lastFrameAt = time; const gates = deps.readGates(); let signal: PageLoadReadySignal | null = null; @@ -138,7 +190,7 @@ export function createPageLoadRecorder( if (signal === null) { streak = 0; } else { - if (streak === 0) streakStart = deps.now(); + if (streak === 0) streakStart = time; streak += 1; if (streak >= stableFrames) { const endTime = signal === "content" && gates.lastContentReadyAt !== null @@ -153,6 +205,7 @@ export function createPageLoadRecorder( function schedule(measurement: PageLoadMeasurement) { streak = 0; + lastFrameAt = null; frame = deps.requestFrame(tick); const remaining = Math.max(0, measurement.startTime + timeoutMs - deps.now()); timer = deps.setTimer(() => { @@ -162,8 +215,11 @@ export function createPageLoadRecorder( } return { - begin({ routeTemplate, loadType, startTime }) { - if (current) finish(current, "interrupted", deps.now(), null); + begin({ routeTemplate, loadType, startTime, hiddenAt = null }) { + // The open measurement ends where this one starts, so no request or + // time is counted under both. + if (current) finish(current, "interrupted", Math.min(deps.now(), startTime), null); + const hidden = hiddenAt !== null || deps.isDocumentHidden(); const measurement: PageLoadMeasurement = { id: nextId++, routeTemplate, @@ -172,18 +228,31 @@ export function createPageLoadRecorder( endTime: null, outcome: null, readySignal: null, - wasHidden: deps.isDocumentHidden(), + wasHidden: hidden, + suspended: false, + view: readView(routeTemplate), }; latestRoute = routeTemplate; if (stopped) return measurement; current = measurement; sink?.begin(measurement); - schedule(measurement); + if (hidden) finish(measurement, "hidden", hiddenAt ?? startTime, null); + else schedule(measurement); return measurement; }, redirect(routeTemplate) { latestRoute = routeTemplate; - if (!current) return false; + if (!current) { + // A load in a background tab ends as soon as it starts; its redirect + // (for example `/` to the dashboard) renames it rather than starting + // a second, also hidden, measurement. + const ended = lastEnded; + if (ended?.outcome !== "hidden" || !deps.isDocumentHidden() || !buffered.includes(ended)) return false; + ended.routeTemplate = routeTemplate; + ended.view = readView(routeTemplate); + if (ended.loadType === "hard") hardLoadRoute = routeTemplate; + return true; + } current.routeTemplate = routeTemplate; streak = 0; return true; @@ -191,8 +260,8 @@ export function createPageLoadRecorder( open: () => current, currentRouteTemplate: () => latestRoute, hardLoadRouteTemplate: () => hardLoadRoute ?? (current?.loadType === "hard" ? current.routeTemplate : null), - noteHidden() { - if (current) current.wasHidden = true; + noteHidden(time) { + if (current) finish(current, "hidden", time, null); }, attachSink(next) { if (stopped) return; diff --git a/ui/src/lib/browser-tracing/page-view.test.ts b/ui/src/lib/browser-tracing/page-view.test.ts new file mode 100644 index 00000000000..3b3f171a894 --- /dev/null +++ b/ui/src/lib/browser-tracing/page-view.test.ts @@ -0,0 +1,28 @@ +import { describe, expect, it } from "vitest"; +import { TASK_VIEW_KEYS } from "@/lib/task-views"; +import { pageViewFor } from "./page-view"; + +describe("pageViewFor", () => { + it("reports the all-tasks page's view from ?view=", () => { + expect(pageViewFor("/:companyPrefix/issues", "?view=mine")).toBe("mine"); + expect(pageViewFor("/:companyPrefix/issues", "?q=secret&view=needs_attention")).toBe("needs_attention"); + for (const key of TASK_VIEW_KEYS) expect(pageViewFor("/:companyPrefix/issues", `?view=${key}`)).toBe(key); + }); + + it("never reports free text: an unknown view becomes other", () => { + expect(pageViewFor("/:companyPrefix/issues", "?view=PAP-1234")).toBe("other"); + expect(pageViewFor("/:companyPrefix/issues", "?view=someone%40example.com")).toBe("other"); + expect(pageViewFor("/:companyPrefix/decisions", "?view=mine%20x")).toBe("other"); + }); + + it("reports the page's default when the URL names no view", () => { + expect(pageViewFor("/:companyPrefix/issues", "")).toBe("default"); + expect(pageViewFor("/:companyPrefix/decisions", "?other=1")).toBe("mine"); + expect(pageViewFor("/:companyPrefix/decisions", "?view=unassigned")).toBe("unassigned"); + }); + + it("reports nothing for a page without views", () => { + expect(pageViewFor("/:companyPrefix/issues/:issueId", "?view=mine")).toBeNull(); + expect(pageViewFor("/:companyPrefix/skills", "?view=catalog")).toBeNull(); + }); +}); diff --git a/ui/src/lib/browser-tracing/page-view.ts b/ui/src/lib/browser-tracing/page-view.ts new file mode 100644 index 00000000000..fa1266c2c97 --- /dev/null +++ b/ui/src/lib/browser-tracing/page-view.ts @@ -0,0 +1,46 @@ +// The `paperclip.page.view` dimension: which view a page's `?view=` selects, +// for the pages where that parameter picks a different list (for example +// `/:companyPrefix/issues?view=mine`). Main-bundle code, no OpenTelemetry. +// +// Only fixed view names from the code's own view registries are reported. A +// value that is not in the page's list becomes `other`, so a hand-edited URL +// never puts free text into a span. + +import { ATTENTION_PERSONAL_VIEWS } from "@paperclipai/shared"; +import { TASK_VIEW_KEYS, TASK_VIEW_PARAM } from "@/lib/task-views"; +import { ATTENTION_VIEW_PARAM } from "@/lib/attention-views"; + +/** Reported for a `?view=` value that is not one of the page's views. */ +export const OTHER_PAGE_VIEW = "other"; + +interface PageViewRule { + param: string; + views: ReadonlySet; + /** Reported when the URL has no `?view=`. */ + missing: string; +} + +const PAGE_VIEW_RULES: ReadonlyMap = new Map([ + // Tasks resolves a missing view from the last one used and writes it into + // the URL, so a finished measurement usually sees the resolved view. + ["/:companyPrefix/issues", { param: TASK_VIEW_PARAM, views: new Set(TASK_VIEW_KEYS), missing: "default" }], + // Decisions shows "For you" (`mine`) when the URL names no view. + ["/:companyPrefix/decisions", { param: ATTENTION_VIEW_PARAM, views: new Set(ATTENTION_PERSONAL_VIEWS), missing: "mine" }], +]); + +/** + * The view for `routeTemplate` given the URL's query string, or null for a + * page that has no views. + */ +export function pageViewFor(routeTemplate: string, search: string): string | null { + const rule = PAGE_VIEW_RULES.get(routeTemplate); + if (!rule) return null; + let value: string | null; + try { + value = new URLSearchParams(search).get(rule.param); + } catch { + return OTHER_PAGE_VIEW; + } + if (value === null || value === "") return rule.missing; + return rule.views.has(value) ? value : OTHER_PAGE_VIEW; +} diff --git a/ui/src/lib/browser-tracing/sdk.test.ts b/ui/src/lib/browser-tracing/sdk.test.ts index 1a9b065e9e2..a826417016b 100644 --- a/ui/src/lib/browser-tracing/sdk.test.ts +++ b/ui/src/lib/browser-tracing/sdk.test.ts @@ -4,7 +4,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { InMemorySpanExporter } from "@opentelemetry/sdk-trace-web"; import type { BrowserTracingConfig } from "@paperclipai/shared"; import { createPageLoadRecorder, type PageLoadRecorder } from "./page-load-recorder"; -import { honeycombSampleRate, nonApiUrlPattern, startTracingSdk } from "./sdk"; +import { honeycombSampleRate, nonApiUrlPattern, pageLoadAttributes, startTracingSdk } from "./sdk"; import { apiAreaFromUrl } from "./span-sanitizer"; import type { TracingSdkHandle } from "./controller"; @@ -126,7 +126,186 @@ describe("startTracingSdk", () => { }); }); +describe("hard-load API spans from Resource Timing", () => { + let exporter: InMemorySpanExporter; + let handle: TracingSdkHandle | null = null; + + beforeEach(() => { + exporter = new InMemorySpanExporter(); + }); + + afterEach(async () => { + await handle?.shutdown(); + handle = null; + }); + + const origin = () => window.location.origin; + const resource = (name: string, startTime: number, responseEnd: number, extra: Record = {}) => + ({ name, initiatorType: "fetch", entryType: "resource", startTime, responseEnd, ...extra }) as unknown as PerformanceResourceTiming; + + it("backfills child spans under a hard load that finished before the SDK loaded", async () => { + const recorder = idleRecorder(); + recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "hard", startTime: 0 }); + (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames(); + const loadEnd = performance.now(); + let stopped = false; + const entries = [ + resource(`${origin()}/api/auth/get-session`, 0.5, 1, { responseStatus: 200 }), + resource(`${origin()}/api/companies/0f6b6d1e-2c4f-4b5e/issues?view=mine&q=secret`, 1, 2, { responseStatus: 404 }), + // Before the browser exposes a status, none is invented. + resource(`${origin()}/api/issues/PAP-77`, 1.5, 3), + // Started after the load ended: not part of it. + resource(`${origin()}/api/issues`, loadEnd + 1, loadEnd + 2), + ]; + handle = startTracingSdk(config, recorder, { + exporter, + apiResources: { entries: () => entries, stop: () => { stopped = true; } }, + earlyResourceGraceMs: 0, + }); + await handle.forceFlush(); + + const spans = exporter.getFinishedSpans(); + const pageSpan = spans.find((span) => span.name === "page.load")!; + const children = spans.filter((span) => span.name !== "page.load"); + expect(children.map((span) => span.name)).toEqual(["HTTP", "HTTP", "HTTP"]); + for (const child of children) { + expect(child.parentSpanContext?.spanId).toBe(pageSpan.spanContext().spanId); + expect(child.spanContext().traceId).toBe(pageSpan.spanContext().traceId); + const serialized = JSON.stringify(child.attributes); + expect(serialized).not.toContain("://"); + expect(serialized).not.toContain("0f6b6d1e"); + expect(serialized).not.toContain("PAP-77"); + expect(serialized).not.toContain("secret"); + expect(child.attributes["url.full"]).toBeUndefined(); + } + expect(children.map((span) => span.attributes)).toEqual([ + { "paperclip.api.area": "auth", "paperclip.api.timing_source": "resource_timing", "http.response.status_code": 200, "paperclip.page.route": "/:companyPrefix/issues", SampleRate: 4 }, + { "paperclip.api.area": "companies", "paperclip.api.timing_source": "resource_timing", "http.response.status_code": 404, "paperclip.page.route": "/:companyPrefix/issues", SampleRate: 4 }, + { "paperclip.api.area": "issues", "paperclip.api.timing_source": "resource_timing", "paperclip.page.route": "/:companyPrefix/issues", SampleRate: 4 }, + ]); + await new Promise((resolve) => setTimeout(resolve, 10)); + expect(stopped).toBe(true); + }); + + it("backfills every buffered navigation, not only the first one replayed", async () => { + const recorder = idleRecorder(); + const flush = (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames; + recorder.begin({ routeTemplate: "/:companyPrefix/dashboard", loadType: "hard", startTime: 0 }); + flush(); + const clientStart = performance.now(); + recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "client", startTime: clientStart }); + flush(); + const clientEnd = performance.now(); + let entries: PerformanceResourceTiming[] = [ + resource(`${origin()}/api/companies`, 0.5, 1, { responseStatus: 200 }), + resource(`${origin()}/api/issues`, clientStart, clientEnd, { responseStatus: 200 }), + ]; + handle = startTracingSdk(config, recorder, { + exporter, + // A real collector drops its entries when stopped. + apiResources: { entries: () => entries, stop: () => { entries = []; } }, + }); + await handle.forceFlush(); + + const spans = exporter.getFinishedSpans(); + const pages = spans.filter((span) => span.name === "page.load"); + const childrenOf = (route: string) => { + const page = pages.find((span) => span.attributes["paperclip.page.route"] === route)!; + return spans.filter((span) => span.parentSpanContext?.spanId === page.spanContext().spanId).map((span) => span.attributes["paperclip.api.area"]); + }; + expect(childrenOf("/:companyPrefix/dashboard")).toEqual(["companies"]); + expect(childrenOf("/:companyPrefix/issues")).toEqual(["issues"]); + }); + + it("keeps early entries for a navigation that started before the SDK loaded but commits after it", async () => { + const recorder = idleRecorder(); + const flush = (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames; + recorder.begin({ routeTemplate: "/:companyPrefix/dashboard", loadType: "hard", startTime: 0 }); + flush(); + // The user clicks (history change) just before the SDK finishes loading; + // the route commits after it. + const historyChange = performance.now(); + let entries: PerformanceResourceTiming[] = [ + resource(`${origin()}/api/companies`, 0.5, 1, { responseStatus: 200 }), + resource(`${origin()}/api/issues`, historyChange, historyChange + 5, { responseStatus: 200 }), + ]; + let stopped = false; + handle = startTracingSdk(config, recorder, { + exporter, + apiResources: { entries: () => entries, stop: () => { stopped = true; entries = []; } }, + }); + expect(stopped).toBe(false); + recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "client", startTime: historyChange }); + flush(); + await handle.forceFlush(); + + const spans = exporter.getFinishedSpans(); + const childrenOf = (route: string) => { + const page = spans.find((span) => span.name === "page.load" && span.attributes["paperclip.page.route"] === route)!; + return spans.filter((span) => span.parentSpanContext?.spanId === page.spanContext().spanId).map((span) => span.attributes["paperclip.api.area"]); + }; + expect(childrenOf("/:companyPrefix/dashboard")).toEqual(["companies"]); + expect(childrenOf("/:companyPrefix/issues")).toEqual(["issues"]); + // Released once a navigation that started after the SDK loaded begins. + recorder.begin({ routeTemplate: "/:companyPrefix/agents", loadType: "client", startTime: performance.now() + 1 }); + expect(stopped).toBe(true); + }); + + it("releases early entries after the grace period when no later navigation happens", async () => { + const recorder = idleRecorder(); + recorder.begin({ routeTemplate: "/", loadType: "hard", startTime: 0 }); + (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames(); + let stopped = false; + handle = startTracingSdk(config, recorder, { + exporter, + apiResources: { entries: () => [], stop: () => { stopped = true; } }, + earlyResourceGraceMs: 0, + }); + expect(stopped).toBe(false); + await new Promise((resolve) => setTimeout(resolve, 10)); + expect(stopped).toBe(true); + }); + + it("does not backfill requests that the live fetch instrumentation already traces", async () => { + const recorder = idleRecorder(); + recorder.begin({ routeTemplate: "/", loadType: "hard", startTime: 0 }); + const afterSdk = () => performance.now() + 1; + const entries: PerformanceResourceTiming[] = []; + handle = startTracingSdk(config, recorder, { + exporter, + apiResources: { entries: () => entries, stop: () => {} }, + }); + entries.push(resource(`${origin()}/api/issues`, afterSdk(), afterSdk() + 1)); + (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames(); + await handle.forceFlush(); + expect(exporter.getFinishedSpans().map((span) => span.name)).toEqual(["page.load"]); + }); +}); + describe("browser tracing helpers", () => { + it("reports hidden, suspended, and view attributes on page.load", () => { + expect(pageLoadAttributes({ + id: 1, + routeTemplate: "/:companyPrefix/issues", + loadType: "hard", + startTime: 0, + endTime: 30_000, + outcome: "timeout", + readySignal: null, + wasHidden: false, + suspended: true, + view: "mine", + })).toEqual({ + "paperclip.page.route": "/:companyPrefix/issues", + "paperclip.page.load_type": "hard", + "paperclip.page.outcome": "timeout", + "paperclip.page.ready_signal": "none", + "paperclip.page.was_hidden": false, + "paperclip.page.suspended": true, + "paperclip.page.view": "mine", + }); + }); + it("ignores every URL outside this origin's API", () => { const pattern = nonApiUrlPattern("https://acme.paperclip.app"); expect(pattern.test("https://acme.paperclip.app/api/issues")).toBe(false); diff --git a/ui/src/lib/browser-tracing/sdk.ts b/ui/src/lib/browser-tracing/sdk.ts index 8ef1079bb10..2a76c92f36a 100644 --- a/ui/src/lib/browser-tracing/sdk.ts +++ b/ui/src/lib/browser-tracing/sdk.ts @@ -13,8 +13,11 @@ // 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 +// 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, type Context, type Span } from "@opentelemetry/api"; +import { context, propagation, trace, ROOT_CONTEXT, SpanKind, type Attributes, type Context, type Span } from "@opentelemetry/api"; import { AlwaysOnSampler, BatchSpanProcessor, @@ -27,7 +30,7 @@ import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch"; import { resourceFromAttributes } from "@opentelemetry/resources"; import { onCLS, onINP, onLCP, type Metric } from "web-vitals"; import type { BrowserTracingConfig } from "@paperclipai/shared"; -import type { TracingSdkHandle } from "./controller"; +import type { ApiResourceCollector, TracingSdkHandle } from "./controller"; import type { PageLoadMeasurement, PageLoadRecorder } from "./page-load-recorder"; import { OtlpFetchExporter } from "./otlp-fetch-exporter"; import { SanitizingSpanExporter } from "./span-sanitizer"; @@ -83,9 +86,46 @@ export function pageLoadAttributes(measurement: PageLoadMeasurement): Record, + pageSpan: Span, + measurement: PageLoadMeasurement, + entries: readonly PerformanceResourceTiming[], + before: number, +) { + const windowEnd = Math.min(measurement.endTime ?? before, before); + const parent = trace.setSpan(ROOT_CONTEXT, pageSpan); + for (const entry of entries) { + if (entry.startTime < measurement.startTime || entry.startTime >= windowEnd) continue; + const attributes: Attributes = { + "url.full": entry.name, + "paperclip.api.timing_source": "resource_timing", + "paperclip.page.route": measurement.routeTemplate, + }; + // Only where the browser exposes it (Chromium); never guessed. + const status = (entry as PerformanceResourceTiming & { responseStatus?: number }).responseStatus; + if (typeof status === "number" && status > 0) attributes["http.response.status_code"] = status; + const span = tracer.startSpan(UNKNOWN_METHOD_SPAN_NAME, { kind: SpanKind.CLIENT, startTime: entry.startTime, attributes }, parent); + span.end(Math.max(entry.startTime, entry.responseEnd)); + } +} + /** Honeycomb weights each event by its `SampleRate` (1 in N). */ export function honeycombSampleRate(sampleRate: number): number | null { return sampleRate >= 1 ? null : Math.max(1, Math.round(1 / sampleRate)); @@ -94,8 +134,19 @@ export function honeycombSampleRate(sampleRate: number): number | null { export interface TracingSdkOptions { /** Replaces the OTLP exporter (tests). Spans are still sanitized. */ exporter?: SpanExporter; + /** `/api/` requests recorded before the SDK loaded (`observeApiResources`). */ + apiResources?: ApiResourceCollector; + /** Overrides `EARLY_RESOURCE_GRACE_MS` (tests). */ + earlyResourceGraceMs?: number; } +/** + * After this long, a navigation whose history change preceded the SDK has + * long since committed, so early entries no open measurement claims are + * released even if the user never navigates again. + */ +export const EARLY_RESOURCE_GRACE_MS = 60_000; + export function startTracingSdk( config: BrowserTracingConfig, recorder: PageLoadRecorder, @@ -150,8 +201,30 @@ export function startTracingSdk( enabled: false, }); fetchInstrumentation.setTracerProvider(provider); + // Requests from here on get live fetch spans; earlier ones are backfilled. + const liveFetchSince = performance.now(); fetchInstrumentation.enable(); + // Who may still claim the early Resource Timing entries: any measurement + // that started before `liveFetchSince` and has not ended, including one not + // yet begun (a navigation's start is its history change, which can precede + // the SDK while its route commits after it). Navigation starts only move + // forward, so once a measurement that started after `liveFetchSince` has + // begun, or the grace period has passed, no new claimant can appear; the + // entries are released when, in addition, no claimant is open. + const apiResources = options.apiResources ?? null; + const earlyOpen = new Set(); + let noNewEarlyClaimants = false; + const releaseIfUnclaimed = () => { + if (apiResources && noNewEarlyClaimants && earlyOpen.size === 0) apiResources.stop(); + }; + const graceTimer = apiResources + ? window.setTimeout(() => { + noNewEarlyClaimants = true; + releaseIfUnclaimed(); + }, options.earlyResourceGraceMs ?? EARLY_RESOURCE_GRACE_MS) + : undefined; + recorder.attachSink({ begin(measurement) { const span = tracer.startSpan("page.load", { @@ -164,6 +237,12 @@ export function startTracingSdk( }); pageSpans.set(measurement.id, span); if (measurement.endTime === null) openPageSpan = span; + if (measurement.startTime < liveFetchSince) { + earlyOpen.add(measurement.id); + } else { + noNewEarlyClaimants = true; + releaseIfUnclaimed(); + } }, end(measurement) { const span = pageSpans.get(measurement.id); @@ -172,7 +251,12 @@ export function startTracingSdk( if (openPageSpan === span) openPageSpan = null; span.setAttributes(pageLoadAttributes(measurement)); if (measurement.loadType === "hard") span.setAttributes(navigationTimingAttributes()); + if (apiResources && measurement.startTime < liveFetchSince) { + backfillApiSpans(tracer, span, measurement, apiResources.entries(), liveFetchSince); + } span.end(measurement.endTime ?? performance.now()); + earlyOpen.delete(measurement.id); + releaseIfUnclaimed(); }, }); @@ -207,6 +291,8 @@ export function startTracingSdk( pageSpans.clear(); openPageSpan = null; fetchInstrumentation.disable(); + window.clearTimeout(graceTimer); + apiResources?.stop(); await provider.shutdown().catch(() => undefined); trace.disable(); context.disable(); diff --git a/ui/src/lib/browser-tracing/span-sanitizer.ts b/ui/src/lib/browser-tracing/span-sanitizer.ts index e1a7576bb88..c8f00ec7d6b 100644 --- a/ui/src/lib/browser-tracing/span-sanitizer.ts +++ b/ui/src/lib/browser-tracing/span-sanitizer.ts @@ -16,6 +16,8 @@ export const ALLOWED_SPAN_ATTRIBUTES: ReadonlySet = new Set([ "paperclip.page.outcome", "paperclip.page.ready_signal", "paperclip.page.was_hidden", + "paperclip.page.suspended", + "paperclip.page.view", "paperclip.page.navigation_type", "paperclip.page.ttfb_ms", "paperclip.page.dom_content_loaded_ms", @@ -24,6 +26,7 @@ export const ALLOWED_SPAN_ATTRIBUTES: ReadonlySet = new Set([ "paperclip.web_vital.value", "paperclip.web_vital.rating", "paperclip.api.area", + "paperclip.api.timing_source", "http.request.method", "http.response.status_code", "error.type",