Files
PaperClipAI/doc/browser-performance-tracing.md
T
DottaandClaude Fable 5.2 eaef46b60b feat(ui): browser page-load tracing to Honeycomb for hosted instances (#21156)
## 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>
2026-11-12 13:48:35 -06:00

12 KiB
Raw Blame History

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:

  1. The instance is cloud managed (isCloudManagedInstance: a PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN or a PAPERCLIP_MANAGED_CONFIG document is present).
  2. PAPERCLIP_BROWSER_TRACES_ENDPOINT is 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:

  1. no full-page loading state is mounted (the PaperclipLoading spinner, which is also the route Suspense fallback), and
  2. one of:
    • Content signal (ready_signal = content): when the page declared a primary-content signal with usePageContentReady, 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.

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

  1. Set the variables above and deploy. A cloud-managed instance logs nothing on success; an invalid setting logs one browser tracing is off warning.
  2. Sign in, open the browser network panel, and confirm the session response carries browserTracing, a sdk-*.js chunk loads after the page settles, and a POST to …/v1/traces returns 200.
  3. In Honeycomb, query name = page.load in the browser dataset for the last 10 minutes and check paperclip.page.route and service.version.