Skip to main content

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.

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:
VariableRequired forWhereHow to confirm
VITE_SENTRY_DSNSentry enabled.env.local (dev) or deploy envIf unset, Sentry init sets enabled: false; no events sent. Check Sentry project Settings → Client Keys (DSN) and set in env.
VITE_APP_VERSIONRelease attributionInjected at build in vite.config.ts as buildIdNo env needed. In Sentry Issue details, check Release equals your build id (e.g. build-YYYYMMDD-xxxx).
SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECTSource map uploadCI/build env onlyWhen 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-profilingBrowser profiling (Chromium)Response headers for HTML navigationsRequired by Sentry browser profiling (browserProfilingIntegration). On Vercel this is set in 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 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, imported first in main.tsx) calls initSentry() from 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: 
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: 
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

AreaWhat to check
IssuesNew test error and/or message events
Metricsdev_verification_button_click, dev_verification_page_load_time_ms, dev_verification_response_time_ms appear in Metrics Explorer
TracesPage load and navigation transactions (if tracing on)
ReplaysSession replay for the tab where you triggered the error (if replay on error)
LogsStructured 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: 
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.