Files
PaperClipAI/ui
DottaandClaude Opus 5.5 37393f5dc5 fix(browser-tracing): send API spans only for measured page loads, without timing events (#21441)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Hosted instances can send browser page-load traces to Honeycomb
(#21156, #21392)
> - On staging, one hour in one workspace sent about 64,000 Honeycomb
events, and only about 15 were `page.load`
> - Two sources make the volume: nine network timing span events on each
API request span, and request spans for background polling in idle tabs
> - The page-load metrics use neither of them
> - This pull request drops the timing events and records API request
spans only while a page load is measured
> - The benefit is about 30x fewer events in a browser test, with the
same page-load data and the same server trace joins

## Linked Issues or Issue Description

Refs #21156, Refs #21392

**What existing behavior does this improve?**
Browser tracing exports a span for every same-origin `/api/` fetch and
nine network timing events on each of those spans.

**Subsystem affected**
UI browser tracing (`ui/src/lib/browser-tracing/`), on hosted instances
with browser tracing turned on.

**Current behavior**
Honeycomb stores each span event as its own event. Each request span
becomes about 10 events. Idle tabs poll (for example live runs every 3 s
on a task page), so most spans are requests that no page load made. On
staging: about 6,600 `GET` spans plus about 6,400 of each timing event
per hour, against about 15 `page.load` spans.

**Proposed behavior**
Request spans carry no timing events. A request is recorded only when it
starts while a `page.load` measurement is open. Other requests send no
span and no `traceparent`.

**Reason and benefit**
Event volume drops by about 30x for an idle tab. `page.load`, Web
Vitals, and the Resource Timing backfill do not change. No exported
request span lacks its `page.load` parent, and no server span points at
a browser span that was never sent.

## What Changed

- `sdk.ts`: the fetch instrumentation runs with `ignoreNetworkEvents:
true` (an option of the installed `@opentelemetry/instrumentation-fetch`
0.221.0).
- `sdk.ts`: new `measuredRequestsOnly` wraps the tracer provider that
only the fetch instrumentation uses. When no `page.load` is open, it
returns a non-recording span with an invalid context. Nothing is
exported. The W3C propagator sends no `traceparent` for an invalid
context, so the server traces that request alone, as for an unsampled
tab. The `page.load`, Web Vitals, and backfill spans use the normal
tracer and do not change.
- Failed idle requests are not kept. The server's own request span
records server errors. To keep them, the browser must record every idle
request and send its `traceparent` before it knows the status, and that
brings back the dangling joins.
- `span-sanitizer.ts`: comment update only.
- `doc/browser-performance-tracing.md`: new "Live API spans" section
with the rule, the note that timing events are not sent, and updated
volume and trace-header text.

## Verification

- Red then green (`ui/src/lib/browser-tracing/sdk.test.ts`):
- `records no span and sends no traceparent for an API request made
while no page load is measured`: failed on the old code (an idle request
sent `traceparent`), passes now.
- `sends request spans without per-request network timing events`:
failed on the old code (9 timing events on the request span), passes
now.
- All 56 tests in `ui/src/lib/browser-tracing/` pass. `tsc --noEmit` for
`ui` passes.
- `pnpm verify` exits 2 because a doc is a global CI input. CI supplies
the broad coverage.
- Real browser: local dev server on an isolated empty instance with 8
tasks, a stand-in OTLP collector, headless Chromium, and the tracing
config injected into the session response. Scenario: hard load of the
all-tasks page, click a task, then 2 minutes idle. One Honeycomb event =
one span or one span event.

| Name | master | this branch |
| --- | ---: | ---: |
| `page.load` | 2 | 2 |
| `web_vital.lcp` | 1 | 1 |
| `HTTP` (backfill) | 33 | 32 |
| `GET` | 165 | 18 |
| `POST` | 1 | 1 |
| each of `fetchStart`, `domainLookupStart`, `domainLookupEnd`,
`connectStart`, `connectEnd`, `requestStart`, `responseStart`,
`responseEnd` | 165 | 0 |
| **Total events** | **1,522** | **54** |

- `secureConnectionStart` does not appear locally because the dev server
is plain HTTP. On staging it is the ninth event.
- Branch: the hard `page.load` has 32 `HTTP` children and the client
`page.load` of the task has 19 live children (`GET`, `POST`). 0 request
spans without a `page.load` parent (master: 146). 19 requests sent
`traceparent`, and all 19 point at an exported span (master: 172 sent, 6
point at spans never exported).
- Idle traffic in this test (210 `/api/` requests in total): `GET
/api/issues/:id/live-runs` 88 times in 2 minutes, and `GET /api/health`
44 times (a dev-server-only 2 s poll). Most of the rest are one-off
refetches.
- Bundle (`vite build`): entry 3,826,982 B raw both, gzip 1,156,148 →
1,156,173 B (+25 B, chunk hash). Lazy SDK chunk 85,423 → 85,825 B raw,
27,723 → 27,859 B gzip.

## Risks

- Low risk. The change is limited to the operator-gated browser tracing
path on hosted instances.
- Behavior shift: Honeycomb no longer has browser spans for requests
made outside a page load, such as polling and mutations in a loaded
page. Their server spans are still recorded as their own traces.
- A request that starts during a page load and finishes after it is
still recorded, as a child of that load.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits, headless Chromium).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 13:09:04 -06:00
..
…

@paperclipai/ui

Published static assets for the Paperclip board UI.

What gets published

The npm package contains the production build under dist/. It does not ship the UI source tree or workspace-only dependencies.

Storybook

Storybook config, stories, and fixtures live under ui/storybook/.

pnpm --filter @paperclipai/ui storybook
pnpm --filter @paperclipai/ui build-storybook

Typical use

Install the package, then serve or copy the built files from node_modules/@paperclipai/ui/dist.

Editor dependency identity

Keep the root and workspace overrides for @codemirror/state, @codemirror/view, and @lezer/common aligned. CodeMirror requires shared extension identity, while Lezer parsers and syntax highlighters require shared NodeProp IDs. Multiple Lezer copies can crash code-block highlighting with tags is not iterable. src/lib/codemirror-single-instance.test.ts checks the installed dependency graph and highlights sample code through the editor's real language dependencies. GitHub Actions owns regeneration of pnpm-lock.yaml.