adam/shoc-frontend-new
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/shoc-frontend-new.git synced 2026-09-30 04:33:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
shoc-frontend-new/docs/adr/0002-sentry-observability.md
Codex Review Integration a24002bc24 feat: activate Sentry deployment environments
2026-09-03 15:10:01 -03:00

3.4 KiB
Raw Blame History

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. .env.production commits the public DSN of the real shoc-frontend Sentry project, so dev and staging deploys are live; a missing or blank DSN in any other build leaves telemetry inactive without preventing the application from starting. Default personally identifiable information collection remains disabled.

The Sentry environment label comes from VITE_SENTRY_ENVIRONMENT when set and non-blank, falling back to the Vite build mode otherwise. The committed .env.production labels dev deploys development, the staging deploy job overrides the label to staging, and a future production pipeline can set production without code changes.

Source-map upload is outside this change. The Sentry organization and the shoc-frontend project now exist and receive telemetry through the committed public DSN, but upload still requires a scoped upload token that is 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.
  • Events are labeled by VITE_SENTRY_ENVIRONMENT (development on dev deploys, staging on the staging job), falling back to the Vite build mode when unset.
  • 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.