## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The board UI is the main surface. Its load speed is a product requirement. > - The team wants to track page-load times over time and give each metric an owner and an SLO in Honeycomb. > - Server traces show only the server part of a page load. They do not show JavaScript start-up, lazy route code, rendering, or client-side navigation. > - Paperclip is also self-hosted by others. Browser tracing must stay off there, and it must not slow any page. > - This pull request adds real-user browser tracing for hosted Paperclip Cloud instances only. It loads lazily and sends a closed set of attributes. > - The benefit is one `page.load` measurement per page (named by route pattern), plus Web Vitals and API spans that join the server trace, ready for Honeycomb queries and SLOs. ## Linked Issues or Issue Description No public issue exists. Feature description: **Subsystem affected** Board UI (`ui/`), the authenticated session route (`server/src/routes/auth.ts`), and the shared session schema. **Problem or motivation** We cannot measure how long the all-tasks page or a task page takes to load for real users. Server traces stop at the API response. Most navigation is client side, and the standard OpenTelemetry document-load instrumentation does not cover it. Without a per-page browser measurement, no agent can own a page-load SLO. **Proposed solution** The server sends a `browserTracing` config in the authenticated session only when the instance is cloud managed and `PAPERCLIP_BROWSER_TRACES_ENDPOINT` is set. The browser then measures every hard load and client navigation in one shared recorder tied to the router's own route tree. After the page settles, it lazily loads an OpenTelemetry chunk that exports `page.load`, `web_vital.*`, and same-origin `/api/` fetch spans to Honeycomb. An allowlist removes every other attribute before export. **Alternatives considered** `@honeycombio/opentelemetry-web` was the first choice. Its defaults add the full page URL, query string, hash, referrer, and user agent to every span and to the resource, and it bundles log and metric pipelines. We would have to replace its exporter and remove most of its defaults. Plain OpenTelemetry web packages plus `web-vitals` are smaller and send only what we choose. Honeycomb needs only OTLP/HTTP and its ingest-key header. **Roadmap alignment** This is internal hosted-instance observability. It changes no product behavior and no self-hosted behavior. ## What Changed - `server/src/browser-tracing-config.ts`: resolves the browser tracing config. It returns `null` unless `isCloudManagedInstance()` is true and `PAPERCLIP_BROWSER_TRACES_ENDPOINT` is set. It accepts only a Honeycomb ingest key (`hcaik_` prefix), requires `https` (except loopback), and fails closed with one value-free warning on any invalid setting. Optional: `PAPERCLIP_BROWSER_TRACES_INGEST_KEY`, `_SAMPLE_RATE` (default 1), `_SERVICE_NAME` (default `paperclip-web`), `_ENVIRONMENT` (default `SENTRY_ENVIRONMENT`). - `GET /api/auth/get-session` adds `browserTracing` (config or `null`), the same delivery path as the front-end Sentry DSN. The shared `authSessionSchema` has the new optional field `browserTracingConfigSchema`. - `ui/src/lib/browser-tracing/page-load-recorder.ts` and `controller.ts` (main bundle, no OpenTelemetry imports): one `page.load` measurement per hard load (from navigation start) and per client navigation (from the history change). A measurement ends at the first painted frame where no full-page loading state is mounted and either every page-declared content signal is ready or no query without data is fetching. Redirects continue the measurement. A new navigation interrupts it. 30 s times out. The sample decision is made once per page session before any download. - `ui/src/components/PageLoadTracker.tsx`: `App` passes the same `<Route>` tree it renders, so every page is reported by route pattern (for example `/:companyPrefix/issues/:issueId`) with no per-page code. - `usePageContentReady` hook and blocking gates: `PaperclipLoading` (also the route `Suspense` fallback) blocks readiness. The task page uses the existing `issue-detail:navigate→content-paint` point. The plain all-tasks list signals when its first rows render. - `ui/src/lib/browser-tracing/sdk.ts` (lazy chunk, loaded after the page settles): OpenTelemetry web tracer, OTLP/HTTP exporter, fetch instrumentation for this origin's `/api/` only with `traceparent` sent only to this origin, `web-vitals` LCP/INP/CLS, and a context manager that makes the open `page.load` span the parent of its API calls. `span-sanitizer.ts` applies the closed attribute allowlist (no URLs, ids, query strings, status messages, or event attributes). Uncaught errors are not sent because Sentry already reports them. - New `ui` dev dependencies, pinned exactly. Each is needed, and the OpenTelemetry ones are the same versions the server already resolves: - `@opentelemetry/api@1.9.1` (already in the workspace): tracer and context API. - `@opentelemetry/sdk-trace-web@2.10.0`: the browser tracer provider, batch processor, and stack context manager. - `@opentelemetry/instrumentation-fetch@0.221.0`: fetch spans and `traceparent` injection. - `@opentelemetry/resources@2.10.0` (already a server dependency): the resource. - `@opentelemetry/otlp-transformer@0.221.0` (already a server dependency): OTLP JSON serialization for a 60-line `OtlpFetchExporter`. This replaces `@opentelemetry/exporter-trace-otlp-http`, which is a server optional peer: installing it in the workspace made the server's exact-version gate test see it as present. - `web-vitals@6.2.3`: LCP, INP, and CLS. All of them are in the lazy chunk only. The lockfile is not committed: `pr-trusted` rejects lockfile edits in pull requests, CI installs with `--no-frozen-lockfile` after the frozen attempt reports `ERR_PNPM_OUTDATED_LOCKFILE`, and the lockfile bot refreshes it after merge. - `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed pins for the three shared files (the session schema is part of the pinned public SDK surface; the contract must live in `packages/shared`). - Docs: new `doc/browser-performance-tracing.md` (enablement, config, key handling, span and attribute list, page-load definitions, example Honeycomb queries and an SLO SLI). Pointers in `doc/observability.md` and the Honeycomb tracing skill. - Two App routing tests mock `PageLoadTracker` because they render `App` without a `QueryClientProvider`. ## Verification - `pnpm verify` returns exit 2 (broader verification required) because docs are global CI inputs. Required CI supplies the broad coverage. - Focused local tests, all pass: - `ui`: `vitest run src/lib/browser-tracing src/components/PageLoadTracker.test.tsx src/components/SentryGate.test.tsx src/api/auth.test.ts src/lib/issue-detail-performance src/pages/IssueDetail src/pages/Issues src/App src/components/CloudAccessGate.test.tsx src/components/IssuesList`: 17 files, 484 tests. - `server`: `browser-tracing-config.test.ts`, `auth-routes.test.ts`, `sentry.test.ts`: 63 passed, 5 skipped. - `packages/shared`: `validators/access.test.ts`: 19 passed. - New tests prove: the SDK module is never imported when the session config is `null`, absent, or signed out, or when the session is not sampled; route templates contain no ids, slugs, or tokens; a client navigation produces a `client` measurement under `/:companyPrefix/issues/:issueId`; `traceparent` goes only to this origin's `/api/` and not to a third-party or non-API URL; exported spans carry only allowlisted attributes. A mutation check (tracker forced on) turned the "never imports" tests red. - Typecheck: `ui` (`pnpm typecheck`), `server` (`pnpm --filter @paperclipai/server typecheck`), and `packages/shared` pass. - Real-browser run: a local dev server with a local OTLP collector and headless Chromium. The self-hosted session returned `browserTracing: null` with the endpoint set, and the page made 0 SDK and 0 collector requests. With a cloud session config injected into the session response, the collector received a hard `page.load` (route `/:companyPrefix/issues`, `ready_signal=idle`), a client `page.load` to `/:companyPrefix/issues/:issueId` (`ready_signal=content`), a back navigation, LCP/INP/CLS spans, and `/api/` fetch spans parented to the open `page.load` span. No task identifier, company id, task title, host, or URL appeared in the exported payload. No third-party request carried `traceparent`. - Bundle size (`ui` production build, initial JavaScript closure of `index.html`): before 3,813,986 B raw / 1,153,991 B gzip; after 3,820,743 B / 1,156,590 B (+6.8 KB raw, +2.6 KB gzip, +0.2%). The lazy SDK chunk is 84 KB raw / 27 KB gzip and is not fetched unless tracing is on and sampled. - Review fixes (each red on the old code, green on the new): the SDK now loads by a 35 s deadline even if the page never settles, so a timed-out hard load is exported (`controller.test.ts`); an agent chat with no saved task uses the idle rule instead of a content gate that never fires (`usePageContentReady.test.tsx`); the sample rate is rounded to exactly 1/N so Honeycomb's `SampleRate` weight matches (`browser-tracing-config.test.ts`). The real-browser run was repeated after the exporter change with the same result. ## Risks - Low risk for self-hosted installs: the server never sends a config, so no tracing code beyond the small recorder runs, and the SDK chunk is never fetched. - On hosted instances the feature is off until an operator sets `PAPERCLIP_BROWSER_TRACES_ENDPOINT` and an ingest key. When on, the controller wraps `history.pushState`/`replaceState` to time navigation starts and restores them on sign-out. - Every signed-in browser can read the ingest key, like the Sentry DSN. Only Honeycomb ingest keys (send-only) are accepted. A collector endpoint can keep the key server-side. - Hard-load API calls happen before the SDK loads, so they have no fetch spans. The hard-load `page.load` span is still recorded. - The browser-to-server trace join needs server tracing. The hosted image does not install the OpenTelemetry server peers today (`CLOUD_BUNDLED_SERVER_DEPS` is `@sentry/node` only). Browser spans work without it. - `ui/src/pages/IssueDetail.tsx` was already over 1,000 lines. This change adds 5 lines there for the task page content signal, next to the existing content-paint measure. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) via Claude Code, with tool use (shell, file edits, local browser automation). Reasoning effort: low. ## 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 - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
12 KiB
Browser Performance Tracing
The board UI can send real-user page-load measurements, Core Web Vitals, and API request spans to Honeycomb (or any OTLP/HTTP collector). The data answers questions such as "what is the P95 time to load the all-tasks page?" and can back a Honeycomb SLO with an owner.
This is part of the operator-gated Observability path (see
observability.md and rules/data-paths.mdc). It is not the
first-party Telemetry system and adds no Telemetry events.
Who gets it
Browser tracing runs only on hosted Paperclip Cloud instances that an operator explicitly configures. It is off by default.
The server decides, in server/src/browser-tracing-config.ts. It sends a
browserTracing object in the authenticated GET /api/auth/get-session
response only when both hold:
- The instance is cloud managed (
isCloudManagedInstance: aPAPERCLIP_CLOUD_TENANT_SERVER_TOKENor aPAPERCLIP_MANAGED_CONFIGdocument is present). PAPERCLIP_BROWSER_TRACES_ENDPOINTis set and every setting is valid.
Otherwise the field is null. Self-hosted installs, local development, and
tests never satisfy (1). With null, or with no session (signed out), the
browser never downloads the tracing code: it lives in its own lazily loaded
chunk (ui/src/lib/browser-tracing/sdk.ts). An invalid setting fails closed:
the field is null and the server logs one warning naming the variable, never
its value.
Configuration
Set these on the hosted server process:
| Variable | Required | Default | Meaning |
|---|---|---|---|
PAPERCLIP_BROWSER_TRACES_ENDPOINT |
yes | — | OTLP/HTTP base URL, for example https://api.honeycomb.io (US) or https://api.eu1.honeycomb.io (EU). /v1/traces is appended unless the path already ends with it. Must be https (plain http only for a loopback host). |
PAPERCLIP_BROWSER_TRACES_INGEST_KEY |
for Honeycomb | — | A Honeycomb ingest key (prefix hcaik_). Sent as x-honeycomb-team. Required when the endpoint is a Honeycomb host; optional for a collector you run. Any other key format is refused. |
PAPERCLIP_BROWSER_TRACES_SAMPLE_RATE |
no | 1 |
Fraction of page sessions traced, 0–1, rounded to an exact 1 in N (0.3 becomes 1/3; 0.75 becomes 1). 0 turns tracing off. |
PAPERCLIP_BROWSER_TRACES_SERVICE_NAME |
no | paperclip-web |
service.name; in Honeycomb this is the dataset name. |
PAPERCLIP_BROWSER_TRACES_ENVIRONMENT |
no | SENTRY_ENVIRONMENT |
deployment.environment.name, for example staging. |
Key handling
Every signed-in browser can read the key, the same way it can read the
front-end Sentry DSN. That is why only a Honeycomb ingest key is accepted:
it can send events but cannot read data or change the Honeycomb account. Use a
key scoped to the environment that should receive browser data, keep it in the
hosting secret store, and never commit it. To keep the key out of browsers
entirely, point the endpoint at an OTLP collector you run (it adds the key) and
leave PAPERCLIP_BROWSER_TRACES_INGEST_KEY unset. That collector must allow
CORS POST from the instance origin with the content-type header.
Sampling
The sample decision is made once per page session (one tab load), before the
SDK downloads. An unsampled session downloads and sends nothing. A sampled
session sends everything, so each trace is complete. When the rate is below 1,
every span carries Honeycomb's SampleRate attribute (1 in N, for example 4
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.
Load-speed cost
Nothing loads on the critical path. The main bundle carries only the
measurement code (route matching, readiness checks); on the ui build of this
change the initial JavaScript grew by about 6.8 KB raw / 2.6 KB gzip (0.2%). The
OpenTelemetry SDK, a small OTLP JSON exporter, fetch instrumentation, and
web-vitals are a separate chunk (about 84 KB raw / 27 KB gzip) fetched only when tracing is on
and the session is sampled, and only after the page settles (painted, no query
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.
What "loaded" means
Each navigation produces one page.load span. It ends at the first animation
frame, held for two consecutive frames, in which:
- no full-page loading state is mounted (the
PaperclipLoadingspinner, which is also the routeSuspensefallback), and - one of:
- Content signal (
ready_signal = content): when the page declared a primary-content signal withusePageContentReady, every declared signal is ready. The end time is the paint time the page reported. - Idle signal (
ready_signal = idle): otherwise, no React Query query that has no data yet is fetching. Background refetches of data already on screen do not count. The end time is the first such frame.
- Content signal (
The rule lives in one place (ui/src/lib/browser-tracing/page-load-recorder.ts)
and the route comes from the router's own route tree (App.tsx passes the tree
it renders to PageLoadTracker), so a new page is measured without page code.
- Hard load (
load_type = hard): starts at navigation start (the document request, time 0) and includes HTML, JavaScript download and start up, authentication, and the page's data and render. Redirects during the load (for example/to/:companyPrefix/dashboard) keep the same span, reported under the final route. - Client navigation (
load_type = client): starts when the URL path changes in history (a link click,navigate(), or back/forward) and includes lazy route code download, data loading, and render. Query-string and hash 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.
Pages with an explicit content signal:
| Page | Route | Loaded when |
|---|---|---|
| Task (issue) page | /:companyPrefix/issues/:issueId |
The conversation content has painted: the same point as the issue-detail:navigate→content-paint User Timing measure. |
| All-tasks list (plain task list) | /:companyPrefix/issues |
The first page of task rows has rendered (or the list shows its error state). The combined inbox and coordinator task views use the idle signal. |
An agent chat with no saved task has no content signal and uses the idle rule.
To add one, call usePageContentReady(ready) in the page component. Use it
only when the idle rule is inaccurate for that page.
Emitted spans
All spans pass through an allowlist (ui/src/lib/browser-tracing/span-sanitizer.ts)
before export. Any other attribute an instrumentation adds, including full
URLs, server addresses, status messages, and event attributes, is dropped.
| Span name | When |
|---|---|
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. |
Attributes (the complete allowlist):
| Attribute | On | Values |
|---|---|---|
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.ready_signal |
page.load |
content, idle, none |
paperclip.page.was_hidden |
page.load |
boolean |
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 |
SampleRate |
all, when sampling | 1-in-N weight |
Resource: service.name, service.version (the UI build commit),
deployment.environment.name.
Not sent: URLs, paths with ids, query strings, hashes, referrers, user agent, user, company, or task identifiers, titles, or content. Server spans carry no company identifier, so browser spans do not either. Uncaught browser errors are not sent here because Sentry already reports them (observability.md).
Trace headers go only to this origin (propagateTraceHeaderCorsUrls is empty),
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).
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.
P95 load time of the all-tasks page
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
P95 load time of an individual task page
VISUALIZE P95(duration_ms), COUNT
WHERE name = page.load
paperclip.page.route = /:companyPrefix/issues/:issueId
paperclip.page.outcome = ready
paperclip.page.was_hidden = false
GROUP BY paperclip.page.load_type
Group by service.version to compare builds. For a timeout rate, count
paperclip.page.outcome = timeout against all page.load spans for the route.
For Web Vitals, P75(paperclip.web_vital.value) where
name = web_vital.lcp (or inp, cls), grouped by paperclip.page.route.
SLO. A Honeycomb SLO needs a boolean SLI as a derived column. For example, "task page loads within 2 s":
IF(AND(EQUALS($name, "page.load"),
EQUALS($paperclip.page.route, "/:companyPrefix/issues/:issueId"),
EQUALS($paperclip.page.was_hidden, false)),
AND(EQUALS($paperclip.page.outcome, "ready"), LTE($duration_ms, 2000)))
The expression is null for other events, so they do not count.
Verifying a deployment
- Set the variables above and deploy. A cloud-managed instance logs nothing on
success; an invalid setting logs one
browser tracing is offwarning. - Sign in, open the browser network panel, and confirm the session response
carries
browserTracing, asdk-*.jschunk loads after the page settles, and aPOSTto…/v1/tracesreturns 200. - In Honeycomb, query
name = page.loadin the browser dataset for the last 10 minutes and checkpaperclip.page.routeandservice.version.