0
# Debug Integration
1

2
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.**
3

4
## Capabilities
5

6
### Modern Function-based Integration
7

8
```typescript { .api }
9
/**
10
 * Integration to debug sent Sentry events (development only)
11
 * @param options - Debug configuration options
12
 * @returns Integration instance for debugging events
13
 */
14
function debugIntegration(options?: DebugOptions): Integration;
15

16
interface DebugOptions {
17
  /** Controls whether console output should be stringified. Default: false */
18
  stringify?: boolean;
19
  /** Controls whether debugger should launch before event sent. Default: false */
20
  debugger?: boolean;
21
}
22
```
23

24
### Legacy Class-based Integration (Deprecated)
25

26
```typescript { .api }
27
/**
28
 * Legacy class-based debug integration
29
 * @deprecated Use debugIntegration() instead
30
 */
31
class Debug implements Integration {
32
  constructor(options?: {
33
    stringify?: boolean;
34
    debugger?: boolean;
35
  });
36
  name: string;
37
  setup(client: Client): void;
38
}
39
```
40

41
## Configuration Options
42

43
### stringify Option
44

45
When `true`, events and hints are JSON.stringify'd before console output:
46
- **false** (default): Raw objects logged to console (allows interactive inspection)
47
- **true**: Objects converted to JSON strings (better for copying/logging)
48

49
### debugger Option
50

51
When `true`, triggers a `debugger` statement before each event is sent:
52
- **false** (default): No debugger breakpoint
53
- **true**: Pauses execution in debugger (only when DevTools open)
54

55
## Behavior
56

57
### Event Logging
58

59
The integration hooks into the `beforeSendEvent` client event and logs:
60
1. The complete event object (with stack traces, contexts, etc.)
61
2. The event hint object (if present and non-empty)
62

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

65
### Console Output
66

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

69
## Usage Examples
70

71
```typescript
72
import { debugIntegration } from '@sentry/integrations';
73
import * as Sentry from '@sentry/browser';
74

75
// Basic debug logging
76
Sentry.init({
77
  dsn: 'YOUR_DSN',
78
  integrations: [
79
    debugIntegration()
80
  ]
81
});
82

83
// Enhanced debugging with breakpoints and stringified output
84
Sentry.init({
85
  dsn: 'YOUR_DSN',
86
  integrations: [
87
    debugIntegration({
88
      stringify: true,    // JSON stringify for easy copying
89
      debugger: true      // Pause in debugger before sending
90
    })
91
  ]
92
});
93

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

100
Sentry.init({
101
  dsn: 'YOUR_DSN',
102
  integrations
103
});
104
```
105

106
## Development Workflow
107

108
This integration is particularly useful during development for:
109

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

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