0
# Sentry Integrations
1

2
The @sentry/integrations package provides a collection of pluggable integrations that enhance the functionality of Sentry JavaScript SDKs. These integrations add capabilities for error tracking, monitoring, debugging, and data collection across different environments.
3

4
**Note**: This package was discontinued with version 8.0.0 of the Sentry JavaScript SDKs. All integrations from this package are now directly exported from the SDK packages like `@sentry/react` and `@sentry/node` for better maintenance and reduced bundle size. 
5

6
For migration guidance, see:
7
- [Client-side migration guide](https://docs.sentry.io/platforms/javascript/migration/v7-to-v8/#removal-of-sentryintegrations-package)
8
- [Server-side migration guide](https://docs.sentry.io/platforms/javascript/guides/node/migration/v7-to-v8/#removal-of-sentryintegrations-package)
9

10
## Package Information
11

12
- **Package Name**: @sentry/integrations
13
- **Package Type**: npm
14
- **Language**: TypeScript/JavaScript
15
- **Installation**: `npm install @sentry/integrations`
16

17
## Core Imports
18

19
All integrations are available as both modern function-based integrations (recommended) and legacy class-based integrations (deprecated):
20

21
```typescript
22
// Modern function-based integrations (recommended)
23
import { captureConsoleIntegration, debugIntegration, dedupeIntegration } from '@sentry/integrations';
24

25
// Legacy class-based integrations (deprecated)
26
import { CaptureConsole, Debug, Dedupe } from '@sentry/integrations';
27
```
28

29
CommonJS:
30

31
```javascript
32
const { captureConsoleIntegration, debugIntegration } = require('@sentry/integrations');
33
```
34

35
## Basic Usage
36

37
```typescript
38
import * as Sentry from '@sentry/browser';
39
import { captureConsoleIntegration, dedupeIntegration } from '@sentry/integrations';
40

41
Sentry.init({
42
  dsn: 'YOUR_DSN',
43
  integrations: [
44
    captureConsoleIntegration({
45
      levels: ['error', 'warn']
46
    }),
47
    dedupeIntegration()
48
  ]
49
});
50
```
51

52
## Architecture
53

54
The integrations package follows a dual-pattern architecture:
55

56
- **Modern Function-based**: Each integration exports a factory function that returns an integration object. Uses `defineIntegration()` for consistent behavior.
57
- **Legacy Class-based**: Each integration exports a class that implements the Integration interface. Converted from function-based using `convertIntegrationFnToClass()`.
58
- **Hook System**: Integrations can hook into various points in the Sentry event pipeline through methods like `setup()`, `setupOnce()`, and `processEvent()`.
59
- **Client Integration**: Most integrations register event handlers or processors with the Sentry client when activated.
60

61
## Capabilities
62

63
### Console Capture
64

65
Captures Console API calls (console.log, console.error, etc.) as Sentry events. Useful for debugging and monitoring console output in production.
66

67
```typescript { .api }
68
function captureConsoleIntegration(options?: CaptureConsoleOptions): Integration;
69

70
interface CaptureConsoleOptions {
71
  levels?: string[];
72
}
73
```
74

75
[Console Capture](./console-capture.md)
76

77
### Error Deduplication
78

79
Removes duplicate error events based on message, exception, stacktrace, and fingerprint comparison. Prevents spam from repeated errors.
80

81
```typescript { .api }
82
function dedupeIntegration(): Integration;
83
```
84

85
[Error Deduplication](./error-deduplication.md)
86

87
### Debug Integration
88

89
Development-only integration that logs events to console and optionally triggers debugger breakpoints before events are sent.
90

91
```typescript { .api }
92
function debugIntegration(options?: DebugOptions): Integration;
93

94
interface DebugOptions {
95
  stringify?: boolean;
96
  debugger?: boolean;
97
}
98
```
99

100
[Debug Integration](./debug-integration.md)
101

102
### Extra Error Data
103

104
Extracts additional custom properties from Error objects and attaches them as event context. Captures error causes and custom error properties.
105

106
```typescript { .api }
107
function extraErrorDataIntegration(options?: Partial<ExtraErrorDataOptions>): Integration;
108

109
interface ExtraErrorDataOptions {
110
  /** The object depth up to which to capture data on error objects. Default: 3 */
111
  depth: number;
112
  /** Whether to capture error causes (Error.cause property). Default: false */
113
  captureErrorCause: boolean;
114
}
115
```
116

117
[Extra Error Data](./extra-error-data.md)
118

119
### HTTP Client Monitoring
120

121
Monitors HTTP requests (fetch and XMLHttpRequest) and creates events for failed requests based on status codes and URL patterns.
122

123
```typescript { .api }
124
function httpClientIntegration(options?: Partial<HttpClientOptions>): Integration;
125

126
interface HttpClientOptions {
127
  /** HTTP status codes that should be considered failed. Default: [[500, 599]] */
128
  failedRequestStatusCodes: HttpStatusCodeRange[];
129
  /** Targets to track for failed requests. Default: [/.*/] */
130
  failedRequestTargets: HttpRequestTarget[];
131
}
132

133
type HttpStatusCodeRange = [number, number] | number;
134
type HttpRequestTarget = string | RegExp;
135
```
136

137
[HTTP Client Monitoring](./http-client.md)
138

139
### Frame Rewriting
140

141
Transforms stack frame filenames using configurable rules. Useful for normalizing paths in different deployment environments.
142

143
```typescript { .api }
144
function rewriteFramesIntegration(options?: RewriteFramesOptions): Integration;
145

146
interface RewriteFramesOptions {
147
  /** Root path to strip from filenames */
148
  root?: string;
149
  /** Prefix to add to rewritten filenames. Default: 'app:///' */
150
  prefix?: string;
151
  /** Custom frame processing function */
152
  iteratee?: StackFrameIteratee;
153
}
154

155
type StackFrameIteratee = (frame: StackFrame) => StackFrame;
156
```
157

158
[Frame Rewriting](./frame-rewriting.md)
159

160
### Reporting Observer
161

162
Browser-only integration that captures Reporting API events (crash reports, deprecation warnings, intervention reports).
163

164
```typescript { .api }
165
function reportingObserverIntegration(options?: ReportingObserverOptions): Integration;
166

167
interface ReportingObserverOptions {
168
  types?: ReportTypes[];
169
}
170

171
type ReportTypes = 'crash' | 'deprecation' | 'intervention';
172
```
173

174
[Reporting Observer](./reporting-observer.md)
175

176
### Context Lines
177

178
Browser-only integration that adds source context lines to stack frames for inline JavaScript in HTML pages.
179

180
```typescript { .api }
181
function contextLinesIntegration(options?: ContextLinesOptions): Integration;
182

183
interface ContextLinesOptions {
184
  frameContextLines?: number;
185
}
186
```
187

188
[Context Lines](./context-lines.md)
189

190
### Session Timing
191

192
Adds session duration information to events, tracking time since Sentry initialization.
193

194
```typescript { .api }
195
function sessionTimingIntegration(): Integration;
196
```
197

198
[Session Timing](./session-timing.md)
199

200
### Offline Support
201

202
Legacy class-based integration for caching events when offline and sending them when connection is restored. Deprecated in favor of offline transport wrapper.
203

204
```typescript { .api }
205
class Offline implements Integration {
206
  constructor(options?: { maxStoredEvents?: number });
207
}
208
```
209

210
[Offline Support](./offline-support.md)
211

212
### Transaction Integration
213

214
Legacy integration that adds transaction names to events based on stack frames. Deprecated and will be removed in v8.
215

216
```typescript { .api }
217
class Transaction implements Integration {
218
  // No configuration options
219
}
220
```
221

222
[Transaction Integration](./transaction-integration.md)
223

224
## Core Types
225

226
```typescript { .api }
227
// Integration base interface from @sentry/types
228
interface Integration {
229
  name: string;
230
  setupOnce?(addGlobalEventProcessor: (callback: EventProcessor) => void, getCurrentHub: () => Hub): void;
231
  setup?(client: Client): void;
232
  processEvent?(event: Event, hint: EventHint, client: Client): Event | null | PromiseLike<Event | null>;
233
}
234

235
// Core Sentry types
236
interface Client<O extends ClientOptions = ClientOptions> {
237
  getOptions(): O;
238
  getDsn(): DsnComponents | undefined;
239
  captureException(exception: any, hint?: EventHint, scope?: Scope): string;
240
  captureMessage(message: string, level?: SeverityLevel, hint?: EventHint, scope?: Scope): string;
241
  captureEvent(event: Event, hint?: EventHint, scope?: Scope): string;
242
  // ... additional client methods
243
}
244

245
interface Event {
246
  event_id?: string;
247
  message?: string;
248
  timestamp?: number;
249
  level?: SeverityLevel;
250
  platform?: string;
251
  logger?: string;
252
  fingerprint?: string[];
253
  tags?: Record<string, string>;
254
  extra?: Record<string, any>;
255
  contexts?: Record<string, any>;
256
  exception?: {
257
    values?: Exception[];
258
  };
259
  // ... additional event properties
260
}
261

262
interface EventHint {
263
  data?: any;
264
  event_id?: string;
265
  originalException?: Error | string;
266
  syntheticException?: Error;
267
  // ... additional hint properties
268
}
269

270
type EventProcessor = (event: Event, hint?: EventHint) => Event | null | PromiseLike<Event | null>;
271

272
// Stack frame type for rewriteFrames integration
273
interface StackFrame {
274
  filename?: string;
275
  function?: string;
276
  module?: string;
277
  platform?: string;
278
  lineno?: number;
279
  colno?: number;
280
  abs_path?: string;
281
  context_line?: string;
282
  pre_context?: string[];
283
  post_context?: string[];
284
  in_app?: boolean;
285
  instruction_addr?: string;
286
  addr_mode?: string;
287
  package?: string;
288
  symbol?: string;
289
  symbol_addr?: string;
290
  image_addr?: string;
291
}
292

293
// Factory function type for modern integrations
294
type IntegrationFn = (...args: any[]) => Integration;
295

296
// Class type for legacy integrations  
297
type IntegrationClass<T extends Integration = Integration> = new (...args: any[]) => T;
298
```