> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sentry verification runbook

> Use this to confirm the React app is sending errors and messages to Sentry after setup or deploy.

Use this to confirm the React app is sending errors and messages to Sentry after setup or deploy.

## Prerequisites

* `VITE_SENTRY_DSN` set in env (e.g. `.env.local`) for the build you are testing.
* Access to the Sentry project dashboard.
* Do not hardcode DSNs in source files. Keep DSNs in environment variables only.

## Configuration checklist

Verify these before or after running manual tests:

| Variable                                            | Required for                 | Where                                              | How to confirm                                                                                                                                                                                                                                                            |
| --------------------------------------------------- | ---------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VITE_SENTRY_DSN`                                   | Sentry enabled               | `.env.local` (dev) or deploy env                   | If unset, Sentry init sets `enabled: false`; no events sent. Check Sentry project Settings → Client Keys (DSN) and set in env.                                                                                                                                            |
| `VITE_APP_VERSION`                                  | Release attribution          | Injected at build in `vite.config.ts` as `buildId` | No env needed. In Sentry Issue details, check **Release** equals your build id (e.g. `build-YYYYMMDD-xxxx`).                                                                                                                                                              |
| `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT` | Source map upload            | CI/build env only                                  | When all three are set, Vite build enables `sentryVitePlugin` and `sourcemap: true`. Omit for local builds if you do not need source map upload.                                                                                                                          |
| `Document-Policy: js-profiling`                     | Browser profiling (Chromium) | Response headers for HTML navigations              | Required by Sentry browser profiling (`browserProfilingIntegration`). On Vercel this is set in [`vercel.json`](../../vercel.json) on the catch-all route. Local `vite dev` does not set this header unless you configure the dev server; profiling may be limited in dev. |

**Vercel production/preview:** For deployments from Vercel, set the same variables in the Vercel project (Settings → Environment Variables). `VITE_SENTRY_DSN` must be set for Production and Preview or the client will have Sentry disabled. For readable stack traces, also set `SENTRY_AUTH_TOKEN`, `SENTRY_ORG` (`encore-health-os`), and `SENTRY_PROJECT` (`sentry-rose-bucket`) so the Vercel build uploads source maps. See [VERCEL\_INTEGRATION.md](../integrations/VERCEL_INTEGRATION.md) for the full checklist.

**Runtime:** Init runs from `src/instrument.ts` (imported first in `main.tsx`). Integrations: `replayIntegration`, `reactRouterV6BrowserTracingIntegration`, `browserProfilingIntegration`; `enableLogs` / `enableMetrics` are on; `sendDefaultPii` is enabled; `beforeSend` still applies breadcrumb/data scrubbing and message truncation. Replay sampling is `replaysSessionSampleRate: 1.0` in development, `0.1` outside development, and `replaysOnErrorSampleRate: 1.0` in all environments. See `src/platform/monitoring/sentry.ts`.

### PHI-scrubbing verification

The init flow ([src/instrument.ts](../../src/instrument.ts), imported first in `main.tsx`) calls `initSentry()` from [src/platform/monitoring/sentry.ts](../../src/platform/monitoring/sentry.ts). The `beforeSend` callback and integrations (`replayIntegration`, `reactRouterV6BrowserTracingIntegration`, `browserProfilingIntegration`) must not send PHI. Verify as follows:

1. **Trigger simulated errors with PHI-like patterns:** In a test or staging build, trigger errors whose messages or breadcrumbs contain sample PHI patterns (e.g. email, phone, SSN-like digits, medical record IDs). Ensure these events are sent through `beforeSend` (init is already loaded).
2. **Verify redaction in Sentry:** In the Sentry UI (or by inspecting the raw event payload), confirm that fields are redacted or masked per `beforeSend` behavior (e.g. message/exception value truncation to `MAX_MESSAGE_LENGTH`, breadcrumb `data` cleared for `ui.input` category). Check that no PHI appears in event message, exception value, or breadcrumb data.
3. **Expected redaction examples and failure indicators:** Document in tests or runbook: a) **Good:** Event message shows truncated text with `[truncated]`; breadcrumbs for `ui.input` have no `data`. b) **Bad:** Full email, phone, SSN, or MRN visible in event or breadcrumbs. If you see PHI in Sentry, `beforeSend` is not applied or was bypassed — fix before going live.
4. **Automated test checklist:** Add unit or integration tests that invoke the same `beforeSend` logic (or the init path that sets it) with sample events containing PHI-like strings; assert that output events have those strings removed or truncated. Reference `beforeSend` in `src/platform/monitoring/sentry.ts` and the integrations `replayIntegration`, `reactRouterV6BrowserTracingIntegration`, and `browserProfilingIntegration` when adding or reviewing these tests.

## Master verification sequence

Repeatable 4-step flow for manual verification:

1. **Set DSN:** Add `VITE_SENTRY_DSN` to `.env.local` (from Sentry project → Settings → Client Keys). Restart the dev server if it is already running.
2. **Open app:** Start the app (`npm run dev`), log in if required, and go to **System Health** at `/settings/system-health`.
3. **Trigger events:** In the **Sentry verification** card (visible only in development), click **Test Message**, **Test Metrics**, then **Test Error**. For "Test Error" the app will show the error boundary; you can reload to continue.
4. **Confirm in Sentry:** In the Sentry project dashboard, open **Issues**. Within a few seconds you should see the test error and the test message. Then open **Metrics** and query `dev_verification_button_click`, `dev_verification_page_load_time_ms`, and `dev_verification_response_time_ms`. Optionally check **Traces** (page load/navigation) and **Replays** (session around the error).

In development, Replay session sampling is set to `1.0`, so every local test session should be visible in **Replays**.

## Manual verification (any environment)

### 1. Test error capture

**Option A — Browser console (quick):**

1. Open the app in the browser.
2. Open DevTools → Console.
3. Run: `throw new Error('Sentry verification test');`
4. In Sentry: **Issues** → the error should appear within seconds.

**Option B — Trigger from UI:**

If the app has a dev-only Sentry test control (e.g. at `/settings/system-health` when `import.meta.env.DEV` is true), click **Test Error**. Otherwise use Option A.

### 2. Test message capture

In the browser console:

```js theme={null}
import('@sentry/react').then((Sentry) => {
  Sentry.captureMessage('Sentry verification message', 'info');
});
```

Or use the dev-only **Test Message** button if available.

In Sentry: **Issues** (or **Logs** if enabled) → the message should appear.

### 3. Test metrics capture

Use the dev-only **Test Metrics** button (preferred) or run this in the browser console:

```js theme={null}
import('@sentry/react').then((Sentry) => {
  Sentry.metrics.count('dev_verification_button_click', 1);
  Sentry.metrics.gauge('dev_verification_page_load_time_ms', 150);
  Sentry.metrics.distribution('dev_verification_response_time_ms', 200);
});
```

In Sentry, open **Metrics** (or Metrics Explorer) and query each metric name directly.
Allow a short ingestion delay before re-querying.

### 4. Check dashboard

| Area        | What to check                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Issues**  | New test error and/or message events                                                                                                  |
| **Metrics** | `dev_verification_button_click`, `dev_verification_page_load_time_ms`, `dev_verification_response_time_ms` appear in Metrics Explorer |
| **Traces**  | Page load and navigation transactions (if tracing on)                                                                                 |
| **Replays** | Session replay for the tab where you triggered the error (if replay on error)                                                         |
| **Logs**    | Structured log entry if you used `Sentry.logger.*`                                                                                    |

### 5. Debug mode

If nothing appears:

1. In `src/platform/monitoring/sentry.ts`, temporarily set `debug: true` in `Sentry.init()`.
2. Reload and trigger a test event; check the browser console for Sentry SDK logs.
3. Confirm DSN is set and not empty; confirm `enabled: Boolean(dsn)` is true.
4. Set `debug: false` again before committing.

## Source map verification

To confirm production stack traces are readable (source file names and line numbers instead of minified code):

1. **Build with Sentry env:** Run a production build with `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` set (e.g. in CI). This enables `sentryVitePlugin` and source map upload in `vite.config.ts`.
2. **Deploy or serve:** Deploy the built app or run `npm run preview` (or equivalent) so the app is served from the production build.
3. **Trigger a test error:** Use the runbook steps above (e.g. console throw or a test button) to send one error to Sentry.
4. **Inspect in Sentry:** Open the error in Sentry **Issues** and expand the stack trace. It should show source file names (e.g. `sentry.ts`, `SentryVerificationButtons.tsx`) and line numbers. If you see only minified filenames and a single line number, the build likely did not have all three Sentry env vars set, or the event’s **Release** does not match the release used when uploading source maps (the build id).

**Security (source maps):** Source maps must be **uploaded only to Sentry** and **never served publicly** (e.g. not from the app origin or CDN). They can expose sensitive business logic or healthcare-specific algorithms — review what is compiled and uploaded. In Sentry, restrict who can view or download source maps (use recommended permissions/roles). Optionally define retention or rotation for source map artifacts and document how releases map to uploaded artifacts so operators understand trade-offs and safe handling.

## Dev-only test component

For one-click verification in development, the platform exports `SentryVerificationButtons` from `@/platform/monitoring`. Render it only when `import.meta.env.DEV` is true (e.g. on a system health or debug page) so it never ships to production.

Example:

```tsx theme={null}
import { SentryVerificationButtons } from '@/platform/monitoring';

// In your component, e.g. system health dashboard:
{import.meta.env.DEV && (
  <Card>
    <CardHeader><CardTitle>Sentry verification</CardTitle></CardHeader>
    <CardContent>
      <SentryVerificationButtons />
    </CardContent>
  </Card>
)}
```

## Post-deploy checklist

* [ ] Trigger test error (console or button).
* [ ] Trigger test message (console or button).
* [ ] Confirm events in Sentry Issues (and Logs if used).
* [ ] Confirm Replay behavior: development captures all sessions (`1.0`), production/preview samples sessions at `0.1`, and error sessions are always captured (`replaysOnErrorSampleRate: 1.0`).
* [ ] Confirm source maps: stack traces show source files and line numbers when `SENTRY_AUTH_TOKEN` + org/project are set in CI build.
* [ ] **Vercel:** If deploying via Vercel, ensure `VITE_SENTRY_DSN` is set for Production and Preview (Vercel Dashboard → Project → Settings → Environment Variables). Optionally set `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT` for source map upload during Vercel builds.