# Sentry Integration

The PostHog Sentry integration links error tracking from Sentry with session replays and user context from PostHog, providing a unified view of errors and user behavior.

## Capabilities

### Create Sentry Integration

Creates a Sentry integration instance that connects PostHog with Sentry error tracking.

```typescript { .api }
/**
 * Creates a Sentry integration
 * Available as both a class and a function
 */
const integration = posthog.sentryIntegration(options?: SentryIntegrationOptions);

// Or as a class
const integration = new posthog.SentryIntegration(options?: SentryIntegrationOptions);
```

**Usage Examples:**

```typescript
import * as Sentry from '@sentry/browser';
import posthog from 'posthog-js';

// Initialize PostHog
posthog.init('<posthog-api-key>', {
    api_host: 'https://us.i.posthog.com'
});

// Initialize Sentry with PostHog integration
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [
        posthog.sentryIntegration({
            organization: 'my-org',
            projectId: 12345,
            severityAllowList: ['error', 'fatal']
        })
    ]
});
```

## Configuration

### SentryIntegrationOptions

```typescript { .api }
/**
 * Configuration options for Sentry integration
 */
interface SentryIntegrationOptions {
    /**
     * Sentry organization slug
     * Used to generate links to Sentry issues
     */
    organization?: string;

    /**
     * Sentry project ID or slug
     * Used to generate links to Sentry issues
     */
    projectId?: number | string;

    /**
     * Custom prefix for self-hosted Sentry
     * @default 'https://sentry.io'
     * @example 'https://sentry.mycompany.com'
     */
    prefix?: string;

    /**
     * Error severity levels to send to PostHog
     * @default ['error']
     * @example ['error', 'fatal', 'warning']
     */
    severityAllowList?: Array<'fatal' | 'error' | 'warning' | 'info' | 'debug'>;

    /**
     * Whether to send exceptions to PostHog as well
     * @default false
     */
    sendExceptionsToPostHog?: boolean;
}
```

## Integration Benefits

### Linked Session Replays

When an error occurs in Sentry, the integration:
- Adds a direct link to the PostHog session replay
- Includes PostHog person profile link
- Shows feature flags active at the time of error
- Provides full user context from PostHog

### Error Context in PostHog

When viewing session replays in PostHog:
- See when Sentry errors occurred during the session
- View error details and stack traces
- Jump directly to the error in Sentry

## Setup Examples

### Basic Setup

```typescript
import * as Sentry from '@sentry/react';
import posthog from 'posthog-js';

// Initialize PostHog first
posthog.init('<posthog-key>');

// Then initialize Sentry with the integration
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [
        posthog.sentryIntegration()
    ]
});
```

### With Organization and Project

```typescript
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [
        posthog.sentryIntegration({
            organization: 'my-company',
            projectId: 12345
        })
    ]
});
```

### Self-Hosted Sentry

```typescript
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [
        posthog.sentryIntegration({
            organization: 'my-company',
            projectId: 'my-project',
            prefix: 'https://sentry.mycompany.com'
        })
    ]
});
```

### Selective Error Reporting

```typescript
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [
        posthog.sentryIntegration({
            // Only send critical errors to PostHog
            severityAllowList: ['error', 'fatal'],
            sendExceptionsToPostHog: true
        })
    ]
});
```

## Best Practices

### Initialization Order

Always initialize PostHog before Sentry:

```typescript
// ✅ Correct order
posthog.init('<posthog-key>');
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [posthog.sentryIntegration()]
});

// ❌ Wrong order - integration won't work properly
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [posthog.sentryIntegration()]
});
posthog.init('<posthog-key>');
```

### User Identification

Identify users in PostHog to see user context in Sentry:

```typescript
// Identify user in PostHog
posthog.identify('user-123', {
    email: 'user@example.com',
    name: 'John Doe'
});

// Sentry will automatically receive this context
```

### Error Severity Filtering

Filter errors sent to PostHog based on severity:

```typescript
posthog.sentryIntegration({
    // Only critical errors
    severityAllowList: ['error', 'fatal']
})

// Or include warnings
posthog.sentryIntegration({
    severityAllowList: ['warning', 'error', 'fatal']
})
```

## Common Patterns

### Conditional Integration

```typescript
// Only integrate in production
const sentryIntegrations = [
    // ... other integrations
];

if (process.env.NODE_ENV === 'production') {
    sentryIntegrations.push(posthog.sentryIntegration({
        organization: 'my-org',
        projectId: 12345
    }));
}

Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: sentryIntegrations
});
```

### Custom Error Grouping

```typescript
// Use PostHog properties for better error grouping
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [posthog.sentryIntegration()],
    beforeSend(event) {
        // Add PostHog context to Sentry events
        event.tags = {
            ...event.tags,
            posthog_distinct_id: posthog.get_distinct_id(),
            posthog_session_id: posthog.get_session_id()
        };
        return event;
    }
});
```

### Error Recovery Tracking

```typescript
// Track error recovery in PostHog
Sentry.init({
    dsn: '<sentry-dsn>',
    integrations: [posthog.sentryIntegration()],
    beforeSend(event, hint) {
        // Capture error recovery attempts
        posthog.capture('error_occurred', {
            error_type: event.exception?.values?.[0]?.type,
            error_message: event.exception?.values?.[0]?.value,
            sentry_event_id: event.event_id
        });

        return event;
    }
});
```

## Data Flow

1. **Error occurs** in your application
2. **Sentry captures** the error
3. **PostHog integration** adds session replay link and context to Sentry
4. **Sentry displays** error with PostHog session replay link
5. **PostHog** (optionally) receives error event if `sendExceptionsToPostHog: true`

## Viewing Integrated Data

### In Sentry

- Open any error in Sentry
- Look for "PostHog" section in error details
- Click "View Session Replay" to see the session in PostHog
- See active feature flags at time of error

### In PostHog

- Open a session replay
- See Sentry errors marked on the timeline
- Click error markers to view details
- Link to full error in Sentry

## Notes

- The integration requires both PostHog and Sentry to be properly initialized
- Session replays must be enabled in PostHog for the integration to be fully functional
- Links between Sentry and PostHog are generated automatically
- The integration works with all Sentry SDKs (browser, React, Vue, Angular, etc.)
- Organization and project ID are optional but recommended for proper link generation
