0002. Browser error and transaction telemetry with Sentry

Status

Accepted

Context

The SeaHaven admin SPA has no centralized browser error reporting or distributed transaction tracing. Operational failures therefore have to be reconstructed from user reports and isolated backend logs. We need browser navigation and API request transactions to join the backend trace while preserving the existing UI, routing, authentication, and server-state behavior.

Decision

Use the pinned @sentry/react 10.73.0 SDK. Initialize it before the application router is created, and wrap createBrowserRouter with Sentry's current React Router compatibility API. Configure the browser tracing integration with a 100% transaction sample rate, and propagate trace headers only to the SPA origin and the configured VITE_API_URL base.

The DSN comes from VITE_SENTRY_DSN. It is intentionally treated as public browser configuration because every VITE_ value is embedded in the built JavaScript. A missing or blank DSN leaves telemetry inactive without preventing the application from starting. Default personally identifiable information collection remains disabled.

Source-map upload is outside this change. It requires a Sentry organization, project, and scoped upload token that are not currently available, plus an explicit deployment design for handling that credential without exposing it in the browser bundle.

Alternatives considered

Manual error and timing calls — rejected because they would miss route transitions and distributed request context, and would require every feature to maintain its own instrumentation.
Propagate tracing headers to every request — rejected because third-party requests must not receive SeaHaven trace metadata and broad propagation can introduce cross-origin request failures.
Add the Sentry Vite plugin now — rejected until the organization, project, upload credential, and deployment ownership are defined.

Consequences

Browser navigations and API requests are recorded as connected transactions when the deployment supplies a valid DSN.
Every transaction is sampled. This meets the current requirement but increases event volume and should be reviewed against Sentry quota and retention after real traffic is measured.
Cross-origin API tracing depends on the backend accepting sentry-trace and baggage request headers; the current API CORS policy allows request headers.
Production stack traces remain minified until source-map upload is designed.
Rollback is isolated: remove @sentry/react, the initialization module and import, restore the unwrapped router factory, and remove the Sentry env entries.

2.7 KiB Raw Blame History