mirror of
https://github.com/Sea-Haven-Industries/shoc-frontend-new.git
synced 2026-10-03 02:13:22 +00:00
56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
# 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.
|