Sentry Integration

Confiance : high

sentryerror-monitoringproduction-debuggingnext-js-integrationconfiguration-managementexception-capture

Comprehensive error monitoring and performance tracking integration for production applications, particularly focusing on Next.js applications with proper exception capture and configuration management.

Configuration Architecture

Environment Variables

Critical Sentry configuration requires multiple environment variables:

SENTRY_DSN="https://[key]@[region].sentry.io/[project-id]"
SENTRY_ORG="organization-slug"
SENTRY_PROJECT="project-slug"
SENTRY_AUTH_TOKEN="token-with-appropriate-scopes"

Regional Considerations

Sentry operates multiple regional instances that must be consistently configured:

EU Region: de.sentry.io for data ingestion, API endpoints
US Region: sentry.io for data ingestion, API endpoints
Mismatched regions between DSN and API calls cause 404/403 errors

Project Slug Resolution

Common configuration issue where expected project names don't match Sentry's automatically-generated slugs:

Next.js projects typically default to javascript-nextjs slug
Custom names may use kebab-case or other transformations
Project slugs must match exactly for API calls to succeed

Next.js Integration Patterns

Instrumentation Setup

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('../sentry.server.config');
  }
  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('../sentry.edge.config');
  }
}

Exception Capture in API Routes

Manual exception capture required for caught errors:

// app/api/sync/route.ts
import { Sentry } from '@sentry/nextjs';

try {
  // API logic
} catch (error) {
  Sentry.captureException(error); // Explicit capture required
  return Response.json({ error: 'Sync failed' }, { status: 500 });
}

Client-Side Error Boundaries

React error boundaries with Sentry integration:

// global-error.tsx
'use client';
import * as Sentry from '@sentry/nextjs';

export default function GlobalError({ error }: { error: Error }) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);
}

Common Integration Issues

Silent Configuration Failures

Incorrect project slugs cause API 404s without obvious error messages
Regional mismatches between DSN and dashboard URLs
Token scope issues preventing organization access

Exception Capture Gaps

Try/catch blocks in API routes without explicit Sentry.captureException()
Client-side network errors that don't reach error boundaries
Serialization errors during server-to-client data transfer

Dashboard URL Construction

Proper Sentry dashboard URLs require numeric project IDs, not slugs:

// Extract project ID from DSN instead of using slug
const projectId = dsn.match(/\/(\d+)$/)?.[1];
const dashboardUrl = `https://${region}/organizations/${org}/issues/?project=${projectId}`;

Debugging Sentry Integration

API Connectivity Testing

Validate configuration by testing API endpoints directly:

# Test organization access (should return 200 or 403, not 404)
curl -H "Authorization: Bearer $TOKEN" \
  https://sentry.io/api/0/organizations/$ORG/

# Test project issues endpoint (should return issues array)
curl -H "Authorization: Bearer $TOKEN" \
  https://sentry.io/api/0/projects/$ORG/$PROJECT/issues/

Token Scope Verification

Required scopes for full integration:

org:read: Organization access
project:read: Project metadata access
event:read: Issue and event access
event:write: For creating releases, sourcemaps

Configuration Validation

Runtime validation of Sentry configuration:

// Validate DSN region matches API calls
const dsnRegion = dsn.includes('de.sentry.io') ? 'EU' : 'US';
const apiBase = dsnRegion === 'EU' ? 'https://sentry.io/api/0' : 'https://sentry.io/api/0';

Production Considerations

Performance Impact

Sentry adds minimal overhead when properly configured
Sample rates should be configured for high-traffic applications
Source map uploads increase build time but improve error debugging

Data Sensitivity

Ensure PII scrubbing is configured appropriately
Consider data residency requirements when choosing regions
Configure allowed domains for browser integration

Rate Limiting

Sentry applies rate limits to prevent abuse
Implement client-side deduplication for repeated errors
Consider error grouping strategies to avoid noise