Sentry Integration

NON-NORMATIVE. Setup and usage guide for Sentry error tracking in the morphism app.

Overview

Property	Value
Org	morphism-systems
Project	morphism-web (Next.js platform)
Team	#morphism-systems
SDK	@sentry/nextjs v10.40.0
Plan	Developer (free)
Timezone	America/Los_Angeles

GitHub integration is connected to the alawein account. Vercel integration is pending (popup was blocked during initial setup — complete via Sentry > Settings > Integrations > Vercel).

Environment Variables

Variable	Where	Description
NEXT_PUBLIC_SENTRY_DSN	Vercel + .env.local	Data Source Name — identifies the project
SENTRY_AUTH_TOKEN	Vercel only	Auth token for source map uploads at build time
SENTRY_ORG	Build config	Org slug (morphism-systems) — used by withSentryConfig
SENTRY_PROJECT	Build config	Project slug (morphism-web) — used by withSentryConfig

SENTRY_AUTH_TOKEN is set in all three Vercel environments (Development, Preview, Production). It is NOT needed locally. The token is scoped to org:ci.

NEXT_PUBLIC_SENTRY_DSN is required in .env.local only if you want errors captured during local development. Leave it unset to keep local runs clean.

Configuration Files

apps/morphism/sentry.server.config.ts

Initializes Sentry for the Node.js runtime (API routes, Server Components, middleware):

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.VERCEL_ENV ?? process.env.NODE_ENV,
  tracesSampleRate: 0.2,      // 20% of transactions
  profilesSampleRate: 0.2,    // 20% CPU profiling
})

Initialization is guarded by a DSN check — if NEXT_PUBLIC_SENTRY_DSN is unset, Sentry is not initialized (keeps local/CI environments clean).

apps/morphism/sentry.client.config.ts

Initializes Sentry for the browser runtime:

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.VERCEL_ENV ?? process.env.NODE_ENV,
  tracesSampleRate: 0.2,
  profilesSampleRate: 0.2,
  replaysOnErrorSampleRate: 1.0,  // 100% session replay on error
  replaysSessionSampleRate: 0.1,  // 10% background session replay
})

The same DSN guard applies.

CSP Configuration

The Content Security Policy in apps/morphism/next.config.ts includes Sentry in the connect-src directive:

connect-src 'self' ... https://*.sentry.io ...

Known limitation: The wildcard *.sentry.io matches one subdomain level only. It does NOT match x.ingest.us.sentry.io (three levels deep). The actual Sentry ingest endpoint for this project is o4510937822920704.ingest.us.sentry.io.

If events are not appearing in Sentry despite the DSN being set, check the browser console for CSP violations against the ingest domain. The fix is to add the full ingest domain explicitly:

connect-src 'self' ... https://*.sentry.io https://o4510937822920704.ingest.us.sentry.io ...

Source Maps

Source maps are uploaded to Sentry at build time via withSentryConfig in next.config.ts:

export default withSentryConfig(nextConfig, { silent: true })

The withSentryConfig wrapper: - Injects the Sentry webpack plugin - Uploads source maps using SENTRY_AUTH_TOKEN - Hides source map upload logs (silent: true)

Source maps are uploaded only when SENTRY_AUTH_TOKEN is present (Vercel builds). They are not uploaded in local development or CI.

Alert Rules

No custom alert rules have been configured yet. The Sentry project uses default alert thresholds. To configure alerts:

1. Go to Sentry > morphism-web > Alerts > Create Alert Rule
2. Recommended starting rules:
3. Error spike: count() > 10 in 1 hour
4. New issue: trigger on first occurrence of any new issue
5. Apdex drop: apdex() < 0.7

Consider adding Linear integration when Linear is actively used — this allows creating issues directly from Sentry.

Verifying the Integration

To trigger a test error and confirm it appears in Sentry:

1. Ensure NEXT_PUBLIC_SENTRY_DSN is set in your environment.
2. Add a temporary test handler:

// In any Route Handler or Server Component
throw new Error('Sentry test error — delete me')

1. Trigger the route, then check the Sentry dashboard under morphism-web > Issues.

Alternatively, use the Sentry debug helper:

import * as Sentry from '@sentry/nextjs'
Sentry.captureMessage('Test message from morphism')

1. Remove the test code after verifying.

Remaining Setup

• Complete the Vercel integration (blocked by popup during initial setup)
• Enable 2FA on the Sentry account
• Configure custom alert rules (see Alert Rules section above)
• Consider Linear integration when Linear is set up