Sentry and OpenTelemetry Setup

Overview

Configure comprehensive error tracking and performance monitoring using Sentry with OpenTelemetry (OTel) instrumentation for Next.js applications, including automatic error capture, distributed tracing, and custom logging.

Installation and Configuration

1. Install Sentry

Install Sentry Next.js SDK:

bash

npm install @sentry/nextjs

Run Sentry wizard for automatic configuration:

bash

npx @sentry/wizard@latest -i nextjs

This creates:

```
sentry.client.config.ts
```
- Client-side configuration
```
sentry.server.config.ts
```
- Server-side configuration
```
sentry.edge.config.ts
```
- Edge runtime configuration
```
instrumentation.ts
```
- OpenTelemetry setup
Updates
```
next.config.js
```
with Sentry webpack plugin

2. Configure Environment Variables

Add Sentry credentials to

.env.local

env

SENTRY_DSN=https://your-dsn@sentry.io/project-id
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project
NEXT_PUBLIC_SENTRY_DSN=https://your-dsn@sentry.io/project-id

Get DSN from Sentry dashboard: Settings > Projects > [Your Project] > Client Keys (DSN)

For production, add these to deployment environment variables.

3. Update Sentry Configurations

Customize

sentry.server.config.ts

using the template from

assets/sentry-server-config.ts

Set environment (development, staging, production)
Configure sample rates for performance monitoring
Enable tracing for Server Actions and API routes
Set up error filtering and breadcrumbs

Customize

sentry.client.config.ts

using the template from

assets/sentry-client-config.ts

Configure replay sessions for debugging
Set error boundaries
Enable performance monitoring for user interactions

4. Add Instrumentation Hook

Create or update

instrumentation.ts

in project root using the template from

assets/instrumentation.ts

. This:

Initializes OpenTelemetry before app starts
Registers Sentry as trace provider
Enables distributed tracing across services
Runs only once on server startup

Note: Requires

experimental.instrumentationHook

next.config.js

(added by Sentry wizard).

5. Create Logging Wrapper

Create

lib/logger.ts

using the template from

assets/logger.ts

. This provides:

Structured logging with context
Automatic Sentry integration
Different log levels (debug, info, warn, error)
Request context capture

Use instead of

console.log

for better debugging:

typescript

import { logger } from '@/lib/logger';

logger.info('User logged in', { userId: user.id });
logger.error('Failed to save data', { error, userId });

6. Add Error Boundary (Client Components)

Create

components/error-boundary.tsx

using the template from

assets/error-boundary.tsx

. This:

Catches React errors in client components
Sends errors to Sentry
Shows fallback UI
Provides error recovery

Use in layouts or pages:

typescript

import { ErrorBoundary } from '@/components/error-boundary';

export default function Layout({ children }) {
  return (
    <ErrorBoundary>
      {children}
    </ErrorBoundary>
  );
}

7. Create Custom Error Page

Update

app/error.tsx

using the template from

assets/error-page.tsx

. This:

Shows user-friendly error messages
Captures errors in Server Components
Provides retry functionality
Sends errors to Sentry

8. Add Global Error Handler

Update

app/global-error.tsx

using the template from

assets/global-error.tsx

. This:

Catches errors in root layout
Last resort error boundary
Required for catching layout errors

Tracing Server Actions

Manual Instrumentation

Wrap Server Actions with Sentry tracing:

typescript

'use server';

import { logger } from '@/lib/logger';
import * as Sentry from '@sentry/nextjs';

export async function createPost(formData: FormData) {
  return await Sentry.startSpan(
    { name: 'createPost', op: 'server.action' },
    async () => {
      try {
        const title = formData.get('title') as string;

        logger.info('Creating post', { title });

        // Your logic here
        const post = await prisma.post.create({
          data: { title, content: '...' },
        });

        logger.info('Post created', { postId: post.id });
        return { success: true, post };

      } catch (error) {
        logger.error('Failed to create post', { error });
        Sentry.captureException(error);
        throw error;
      }
    }
  );
}

Automatic Instrumentation

Sentry automatically instruments:

Next.js API routes
Server Components (partial)
Fetch requests
Database queries (with OTel)

Monitoring Patterns

1. Capture User Context

Associate errors with users:

typescript

import * as Sentry from '@sentry/nextjs';
import { getCurrentUser } from '@/lib/auth/utils';

export async function setUserContext() {
  const user = await getCurrentUser();

  if (user) {
    Sentry.setUser({
      id: user.id,
      email: user.email,
    });
  }
}

Call in layouts or middleware to track user context globally.

2. Add Custom Tags

Tag errors for filtering:

typescript

Sentry.setTag('feature', 'worldbuilding');
Sentry.setTag('entity_type', 'character');

// Now errors are tagged and filterable in Sentry dashboard

3. Add Breadcrumbs

Track user actions leading to errors:

typescript

Sentry.addBreadcrumb({
  category: 'user_action',
  message: 'User clicked create entity',
  level: 'info',
  data: {
    entityType: 'character',
    worldId: 'world-123',
  },
});

4. Performance Monitoring

Track custom operations:

typescript

import * as Sentry from '@sentry/nextjs';

export async function complexOperation() {
  const transaction = Sentry.startTransaction({
    name: 'Complex World Generation',
    op: 'task',
  });

  // Step 1
  const span1 = transaction.startChild({
    op: 'generate.terrain',
    description: 'Generate terrain data',
  });
  await generateTerrain();
  span1.finish();

  // Step 2
  const span2 = transaction.startChild({
    op: 'generate.biomes',
    description: 'Generate biome data',
  });
  await generateBiomes();
  span2.finish();

  transaction.finish();
}

5. Database Query Tracing

Prisma automatically integrates with OTel:

typescript

// Queries are automatically traced if OTel is configured
const users = await prisma.user.findMany();
// Shows up in Sentry as a database span

Configuration Options

Sample Rates

Control how many events are sent to Sentry (avoid quota limits):

typescript

// sentry.server.config.ts
Sentry.init({
  dsn: process.env.SENTRY_DSN,

  // Percentage of errors to capture (1.0 = 100%)
  sampleRate: 1.0,

  // Percentage of transactions to trace
  tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,

  // Percentage of sessions to replay
  replaysSessionSampleRate: 0.1,

  // Percentage of error sessions to replay
  replaysOnErrorSampleRate: 1.0,
});

Environment Detection

Configure different settings per environment:

typescript

Sentry.init({
  environment: process.env.NODE_ENV,
  enabled: process.env.NODE_ENV !== 'development', // Disable in dev

  beforeSend(event, hint) {
    // Filter out specific errors
    if (event.exception?.values?.[0]?.value?.includes('ResizeObserver')) {
      return null; // Don't send to Sentry
    }
    return event;
  },
});

Source Maps

Ensure source maps are uploaded for readable stack traces:

typescript

// next.config.js (added by Sentry wizard)
const { withSentryConfig } = require('@sentry/nextjs');

module.exports = withSentryConfig(
  nextConfig,
  {
    silent: true,
    org: process.env.SENTRY_ORG,
    project: process.env.SENTRY_PROJECT,
  },
  {
    hideSourceMaps: true,
    widenClientFileUpload: true,
  }
);

Best Practices

Use logger wrapper: Centralize logging for consistency
Set user context: Associate errors with users for debugging
Add breadcrumbs: Track user journey before errors
Monitor performance: Use tracing for slow operations
Filter noise: Exclude known non-critical errors
Configure sample rates: Balance visibility with quota
Test in staging: Verify Sentry integration before production
Review regularly: Check Sentry dashboard for patterns

Troubleshooting

Sentry not capturing errors: Check DSN is correct and Sentry is initialized. Verify

instrumentation.ts

exports

register()

Source maps not working: Ensure auth token is set and source maps are uploaded during build. Check Sentry dashboard > Settings > Source Maps.

High quota usage: Reduce sample rates in production. Filter out noisy errors with

beforeSend

Traces not appearing: Verify

tracesSampleRate

> 0. Check OpenTelemetry is initialized in

instrumentation.ts

Client errors not captured: Ensure

NEXT_PUBLIC_SENTRY_DSN

is set and accessible from browser.

Resources

scripts/

No executable scripts needed for this skill.

references/

```
sentry-best-practices.md
```
- Error handling patterns, performance monitoring strategies, and quota management
```
otel-integration.md
```
- OpenTelemetry concepts, custom instrumentation, and distributed tracing setup

assets/

```
sentry-server-config.ts
```
- Server-side Sentry configuration with tracing and sampling
```
sentry-client-config.ts
```
- Client-side Sentry configuration with replay and error boundaries
```
instrumentation.ts
```
- OpenTelemetry initialization and Sentry integration
```
logger.ts
```
- Structured logging wrapper with Sentry integration
```
error-boundary.tsx
```
- React error boundary component for client-side error handling
```
error-page.tsx
```
- Custom error page for Server Component errors
```
global-error.tsx
```
- Global error handler for root layout errors

sentry-and-otel-setup

NPX Install

Tags

SKILL.md Content

Sentry and OpenTelemetry Setup

Overview

Installation and Configuration

1. Install Sentry

2. Configure Environment Variables

3. Update Sentry Configurations

4. Add Instrumentation Hook

5. Create Logging Wrapper

6. Add Error Boundary (Client Components)

7. Create Custom Error Page

8. Add Global Error Handler

Tracing Server Actions

Manual Instrumentation

Automatic Instrumentation

Monitoring Patterns

1. Capture User Context

2. Add Custom Tags

3. Add Breadcrumbs

4. Performance Monitoring

5. Database Query Tracing

Configuration Options

Sample Rates

Environment Detection

Source Maps

Best Practices

Troubleshooting

Resources

scripts/

references/

assets/