or run

tessl search

tessl/npm-posthog-js

tessl install tessl/npm-posthog-js@1.335.0

PostHog Browser JS Library is a comprehensive browser analytics and feature management SDK that enables developers to capture user events, track product analytics, manage feature flags, record session replays, and implement feedback mechanisms like surveys and conversations in web applications.

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.

/**
 * 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:

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

/**
 * 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

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

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

Self-Hosted Sentry

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

Selective Error Reporting

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:

// ✅ 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:

// 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:

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

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

Common Patterns

Conditional Integration

// 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

// 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

// 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

Error occurs in your application
Sentry captures the error
PostHog integration adds session replay link and context to Sentry
Sentry displays error with PostHog session replay link
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