Debug Integration

Development-only integration for debugging Sentry events. Logs events to console and optionally triggers debugger breakpoints before events are sent. This integration should not be used in production.

Capabilities

Modern Function-based Integration

/**
 * Integration to debug sent Sentry events (development only)
 * @param options - Debug configuration options
 * @returns Integration instance for debugging events
 */
function debugIntegration(options?: DebugOptions): Integration;

interface DebugOptions {
  /** Controls whether console output should be stringified. Default: false */
  stringify?: boolean;
  /** Controls whether debugger should launch before event sent. Default: false */
  debugger?: boolean;
}

Legacy Class-based Integration (Deprecated)

/**
 * Legacy class-based debug integration
 * @deprecated Use debugIntegration() instead
 */
class Debug implements Integration {
  constructor(options?: {
    stringify?: boolean;
    debugger?: boolean;
  });
  name: string;
  setup(client: Client): void;
}

Configuration Options

stringify Option

When true, events and hints are JSON.stringify'd before console output:

• false (default): Raw objects logged to console (allows interactive inspection)
• true: Objects converted to JSON strings (better for copying/logging)

debugger Option

When true, triggers a debugger statement before each event is sent:

• false (default): No debugger breakpoint
• true: Pauses execution in debugger (only when DevTools open)

Behavior

Event Logging

The integration hooks into the beforeSendEvent client event and logs:

1. The complete event object (with stack traces, contexts, etc.)
2. The event hint object (if present and non-empty)

Both objects are logged either as interactive objects or JSON strings based on the stringify option.

Console Output

All logging is wrapped in consoleSandbox() to prevent interference with other console integrations.

Usage Examples

import { debugIntegration } from '@sentry/integrations';
import * as Sentry from '@sentry/browser';

// Basic debug logging
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    debugIntegration()
  ]
});

// Enhanced debugging with breakpoints and stringified output
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    debugIntegration({
      stringify: true,    // JSON stringify for easy copying
      debugger: true      // Pause in debugger before sending
    })
  ]
});

// Development vs Production setup
const integrations = [];
if (process.env.NODE_ENV === 'development') {
  integrations.push(debugIntegration({ debugger: true }));
}

Sentry.init({
  dsn: 'YOUR_DSN',
  integrations
});

Development Workflow

This integration is particularly useful during development for:

1. Event Inspection: See exactly what data is being sent to Sentry
2. Debugging Setup: Verify integration configuration and data collection
3. Testing Scenarios: Step through event creation with debugger breakpoints
4. Context Validation: Ensure all expected context and metadata is captured

Important: Remove this integration from production builds as it adds console noise and potential performance overhead.