Files
PaperClipAI/ui/src/lib/sentry.ts
T
Devin FoleyandClaude Opus 5.5 f58bbefc4e fix(ui): group failed-query Sentry reports by status and query name (#21475)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The browser app can report errors to Sentry. A final query error
goes to Sentry when it is not an outage, a denial, or a missing item.
> - Every failed API request throws an `ApiError` from the same frames
in `api/client.ts`.
> - Sentry groups errors by stack. Thus all unrelated server failures go
into one issue, titled "ApiError: Internal server error".
> - The report has no route, no query name, and no status. Breadcrumbs
and URLs are removed for privacy. A person cannot find which endpoint
failed.
> - This pull request tags each failed-query report with its HTTP status
and the static name of its query key. It also sets the Sentry
fingerprint from these two values.
> - The benefit: each failing endpoint gets its own Sentry issue, and a
person can connect it to the server error.

## Linked Issues or Issue Description

**What happened?**
One browser Sentry issue collected unrelated server 500 errors from
different pages and environments. The events had no route or query name.
A person could not connect an event to a server error.

**Steps to reproduce**
1. Turn on browser error monitoring with a Sentry DSN.
2. Make two different queries fail with a 500 response, for example the
issues list and the agents list.
3. Look at Sentry. Both events are in one issue with the title
"ApiError: Internal server error". Neither event shows which query
failed.

**Expected behavior**
Each failing query has its own Sentry issue. The event shows the HTTP
status and the static query name. It shows no IDs, refs, or filters.

**Environment**
The hosted browser app, staging and production builds.

I searched open pull requests for duplicates. I found no pull request
that changes browser query-error grouping.

## What Changed

- `ui/src/lib/browser-error-context.ts`: add `queryKindFor`. It keeps
only the first query-key part, and only when it is a lowercase word list
such as `issues` or `agent-commentary`. Other values become `other`, so
an ID, a ref, an email, or a typed value is never sent.
- `ui/src/lib/browser-error-context.ts`: add `buildQueryErrorContext`.
For an error with an HTTP status, it sets the `query_kind` and
`api_status` tags and the fingerprint `["api-error", status,
queryKind]`. For an error without a status, it sets only the
`query_kind` tag and keeps default stack grouping.
- `ui/src/lib/sentry.ts`: add `captureQueryException`. It uses the same
serialized queue as `captureBrowserException`. Both functions now share
one private capture step.
- `ui/src/lib/query-client.ts`: `reportError` now also receives the
query key.
- `ui/src/main.tsx`: the query client reports through
`captureQueryException`.
- Tests for key sanitizing, the fingerprint, the reporter argument, and
the gate call.

## Verification

- Red before the fix: the 6 new assertions fail on the old source
(`queryKindFor`, `buildQueryErrorContext` and `captureQueryException` do
not exist, and `reportError` gets no key).
- Green after the fix: `cd ui && npx vitest run src/lib/sentry.test.ts
src/lib/browser-error-context.test.ts src/lib/query-client.test.ts`
passes 3 files and 78 tests.
- The privacy test makes sure that `company-uuid` and `PAP-1` from later
key parts do not go into the Sentry call. It also makes sure that UUID,
ref, email, and long heads become `other`.
- `ui` typecheck: no errors in the changed files. The local install was
filtered to the UI package, so unrelated packages (`plugin-sdk` build
output, runner dependencies) could not resolve. Required CI supplies the
full typecheck.
- I did not run browser e2e suites. This change does not touch them.

## Risks

- Low risk. Only the grouping and tags of browser query-error reports
change. The app does not change what it shows to users.
- Sentry opens new issues for future query errors, one for each status
and query name. The old catch-all issue gets no new events.
- A query key with a dynamic first part becomes `other`. Those errors
still group together, but they keep the status tag.

> 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

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with
tool use, repository inspection, and shell code execution.

## 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 12:24:46 -08:00

255 lines
11 KiB
TypeScript

// Optional Sentry error monitoring for the browser.
//
// Activated only when the signed-in session carries a Sentry DSN. `SentryGate`
// reads the DSN off `GET /api/auth/get-session` and calls
// `initBrowserErrorMonitoring` once. A signed-out browser, or a browser with
// no DSN, calls this module never — see `SentryGate.tsx`.
//
// Sign-out must stop monitoring, not just stop starting it: `SentryGate`
// calls `teardownBrowserErrorMonitoring` when the session's DSN goes away.
// The function detaches the client from the current scope first
// (`Sentry.getCurrentScope().setClient(undefined)`), then closes that same
// client (`client.close()`), so a signed-out page's global handlers find no
// attached client at any point. Detach runs first because a client stays
// attached, and stays enabled, for the whole close call — closing first
// would leave the signed-out page able to send one more event to Sentry for
// as long as the close call takes. Both calls are built-in Sentry client
// calls — no custom filter code.
//
// `initBrowserErrorMonitoring`, `teardownBrowserErrorMonitoring`,
// `captureBrowserException`, and `captureQueryException` each queue their
// work on one shared promise chain (`enqueue`) instead of running at once.
// One operation runs at a time, in call order, so no operation can ever
// observe another one part-finished — a sign-out always closes the client a
// sign-in already finished starting, never one still starting.
//
// `@sentry/browser` loads through a dynamic import, so Vite puts it in a
// separate chunk that a browser with no DSN never fetches.
//
// Default-integration privacy note: two default integrations copy values
// this app does not want inside a Sentry event, so the initializer removes
// them with a built-in Sentry option — no custom filter code:
// - `Breadcrumbs` turns a console call, a click, and a fetch call into a
// breadcrumb with the raw arguments and the raw request URL.
// - `HttpContext` copies the page URL, the query string, and the referrer
// onto every event.
// The initializer keeps every other default integration, so the browser
// still captures `window.onerror` and `window.onunhandledrejection`
// (`GlobalHandlers`), the two React error boundaries, deduplicates a repeat
// event (`Dedupe`), and links a caused-by chain (`LinkedErrors`).
import {
buildBrowserErrorContext,
buildQueryErrorContext,
classifyRejectionReason,
readBrowserErrorState,
readPageLifecycle,
startPageDiagnostics,
takeRejectionEventSnapshot,
type BrowserErrorDetails,
} from "./browser-error-context";
let queue: Promise<void> = Promise.resolve();
/** Run gate operations one at a time, in call order. */
function enqueue(op: () => Promise<void>): Promise<void> {
const next = queue.then(op);
queue = next.catch(() => {});
return next;
}
/** The `@sentry/browser` module shape, resolved once. */
type SentryBrowserModule = typeof import("@sentry/browser");
/**
* The `Sentry.init` options this gate builds. `Sentry.init`'s parameter is
* optional, so `Parameters<...>[0]` alone carries an `| undefined` arm this
* gate never returns. `NonNullable` removes only that arm — the object shape
* underneath stays the true `@sentry/browser` option type.
*/
type BrowserSentryInitOptions = NonNullable<Parameters<SentryBrowserModule["init"]>[0]>;
let sentry: SentryBrowserModule | null = null;
/**
* Load `@sentry/browser` and start the client with the given DSN. Idempotent
* — the session query can refetch and call this again, and a second call is
* a no-op because a client is already started.
*/
export function initBrowserErrorMonitoring(dsn: string, environment?: string | null): Promise<void> {
return enqueue(async () => {
if (sentry) return;
try {
const Sentry = await import("@sentry/browser");
// Before init: the rejection snapshot listener must precede the SDK's
// `onunhandledrejection` handler. Diagnostics never block monitoring.
try {
startPageDiagnostics();
} catch { /* diagnostic unavailable */ }
Sentry.init(buildBrowserSentryInitOptions(dsn, environment));
sentry = Sentry;
} catch (err) {
// The dynamic import or the init call failed. Fall through with a
// single diagnostic. The gate fails open — the app keeps running
// without error monitoring rather than crashing on an opt-in feature.
// eslint-disable-next-line no-console
console.error("[paperclip] Sentry browser bootstrap failed", err);
}
});
}
/**
* Stop browser error monitoring and forget the started client. Call this on
* sign-out, so the browser sends Sentry no more events and no more
* breadcrumbs after the session ends. A no-op when monitoring never started.
*
* Detaches the client from the current scope, then closes that same client.
* A client stays attached, and stays enabled, for the whole close call — a
* signed-out page's `window.onerror` or `window.onunhandledrejection`
* handler would still reach it for as long as the close call takes.
* Detaching first removes that window instead of leaving it open.
*/
export function teardownBrowserErrorMonitoring(): Promise<void> {
return enqueue(async () => {
const Sentry = sentry;
sentry = null;
if (!Sentry) return;
// Read the client before detaching it. The scope holds no client after
// detach, so the close step below needs this reference to flush and
// close the right client.
const client = Sentry.getClient();
// Detach first, close second — the opposite order from a plain
// `Sentry.close()` call, which reads the client off the current scope
// and would find nothing to close if detach ran first. A separate
// guarded try keeps this step unable to reject, unlike a bare finally
// block: a thrown error here would still reach the caller, and
// `SentryGate.tsx` discards this function's returned promise with a
// bare `void` call, so a rejection would surface as an unhandled
// promise rejection in the browser.
try {
Sentry.getCurrentScope().setClient(undefined);
} catch (err) {
// eslint-disable-next-line no-console
console.error("[paperclip] Sentry client detach failed", err);
}
// A second, separate guarded try, for the same reason as the one
// above: this step must never reject the returned promise.
try {
// Awaiting matters: the client flushes buffered events to Sentry
// during close; a caller that does not wait may navigate away, or
// the page may unload, before the flush finishes.
await client?.close(2_000);
} catch (err) {
// eslint-disable-next-line no-console
console.error("[paperclip] Sentry teardownBrowserErrorMonitoring failed", err);
}
});
}
/**
* Report an error to Sentry. Never throws — observability must not change
* control flow. A no-op before the gate opens, when the gate never opens (no
* DSN on the session), or when bootstrap failed.
*/
export function captureBrowserException(error: unknown, details?: BrowserErrorDetails): void {
let context: ReturnType<typeof buildBrowserErrorContext> | undefined;
try {
if (details) context = buildBrowserErrorContext(details);
} catch {
// Diagnostics must never replace the original exception or its recovery UI.
}
enqueueCapture(error, context);
}
/**
* Report a failed query, grouped by its HTTP status and the static name of
* its query key. Never throws, and is a no-op until the gate opens.
*/
export function captureQueryException(error: unknown, queryKey: readonly unknown[]): void {
let context: ReturnType<typeof buildQueryErrorContext> | undefined;
try {
context = buildQueryErrorContext(error, queryKey);
} catch {
// Diagnostics must never replace the original exception.
}
enqueueCapture(error, context);
}
function enqueueCapture(
error: unknown,
context: ReturnType<typeof buildBrowserErrorContext> | ReturnType<typeof buildQueryErrorContext> | undefined,
): void {
void enqueue(async () => {
try {
if (context) sentry?.captureException(error, context);
else sentry?.captureException(error);
} catch (err) {
// eslint-disable-next-line no-console
console.error("[paperclip] Sentry captureException failed", err);
}
});
}
/**
* Build the `Sentry.init` options object. A pure function, split out from
* `initBrowserErrorMonitoring` so a test can call it with the real
* `@sentry/browser` module and assert the resolved integration list and the
* captured-event shape against the true SDK, not a stand-in.
*/
export function buildBrowserSentryInitOptions(
dsn: string,
environment?: string | null,
): BrowserSentryInitOptions {
return {
dsn,
environment: environment ?? undefined,
// Use the loaded bundle's build, even when the server has since deployed.
release:
typeof __PAPERCLIP_BUILD_COMMIT__ === "string"
? __PAPERCLIP_BUILD_COMMIT__
: undefined,
tracesSampleRate: 0,
sendDefaultPii: false,
beforeSend: (event, hint) => {
// Global handlers do not pass through our React boundaries. Give their
// reports the same bounded document state, without URLs or breadcrumbs.
// Preserve a boundary's earlier snapshot across the asynchronous queue.
try {
event.contexts = {
...event.contexts,
browser_state: event.contexts?.browser_state ?? readBrowserErrorState(),
page_lifecycle: event.contexts?.page_lifecycle ?? readPageLifecycle(),
};
event.tags = {
...event.tags,
browser_build_mode: import.meta.env.DEV ? "development" : "production",
};
if (event.exception?.values?.some((value) =>
value.mechanism?.type === "onunhandledrejection"
|| value.mechanism?.type === "auto.browser.global_handlers.onunhandledrejection",
)) {
// The SDK supplies the rejected value directly. Classify without
// reading object properties, coercing strings, or copying its value.
const kind = classifyRejectionReason(hint.originalException);
event.tags.browser_rejection_kind = kind;
// Whether the browser or a script dispatched the event, and which
// promise implementation carried it. Without a stack these are the
// remaining attribution facts for an `undefined` rejection.
const rejection = takeRejectionEventSnapshot(kind);
if (rejection) {
event.tags.browser_rejection_event = rejection.trusted ? "trusted" : "synthetic";
event.contexts.rejection_event = rejection;
}
}
} catch {
// Diagnostics must not replace or discard the original error.
}
return event;
},
integrations: (defaults) =>
defaults.filter(
(integration) => integration.name !== "HttpContext" && integration.name !== "Breadcrumbs",
),
};
}