0
# Error and Event Capture
1

2
Comprehensive error capturing and event reporting functionality for monitoring application errors, messages, and custom events in browser environments.
3

4
## Capabilities
5

6
### Exception Capture
7

8
Capture and report exceptions to Sentry.
9

10
```typescript { .api }
11
/**
12
 * Capture an exception and send it to Sentry
13
 * @param exception - The exception to capture (Error object, string, or any value)
14
 * @param hint - Additional context and configuration for the event
15
 * @returns Event ID string for the captured exception
16
 */
17
function captureException(exception: any, hint?: EventHint): string;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { captureException } from "@sentry/browser";
24

25
// Capture Error objects
26
try {
27
  throw new Error("Something went wrong");
28
} catch (error) {
29
  captureException(error);
30
}
31

32
// Capture with additional context
33
captureException(new Error("API request failed"), {
34
  tags: { endpoint: "/api/users" },
35
  extra: { requestId: "12345", userId: "user-123" },
36
  level: "error",
37
});
38

39
// Capture non-Error values
40
captureException("String error message");
41
captureException({ customError: "Custom error object" });
42
```
43

44
### Message Capture
45

46
Capture and report custom messages with different severity levels.
47

48
```typescript { .api }
49
/**
50
 * Capture a message and send it to Sentry
51
 * @param message - The message to capture
52
 * @param level - Severity level of the message
53
 * @param hint - Additional context and configuration for the event
54
 * @returns Event ID string for the captured message
55
 */
56
function captureMessage(
57
  message: string, 
58
  level?: SeverityLevel, 
59
  hint?: EventHint
60
): string;
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
import { captureMessage } from "@sentry/browser";
67

68
// Simple message capture
69
captureMessage("User completed checkout");
70

71
// With severity level
72
captureMessage("Database connection slow", "warning");
73

74
// With additional context
75
captureMessage("Feature flag toggled", "info", {
76
  tags: { feature: "new-ui", user_segment: "beta" },
77
  extra: { previousValue: false, newValue: true },
78
});
79
```
80

81
### Custom Event Capture
82

83
Capture fully custom events with complete control over event structure.
84

85
```typescript { .api }
86
/**
87
 * Capture a custom event and send it to Sentry
88
 * @param event - The event object to capture
89
 * @param hint - Additional context and configuration for the event
90
 * @returns Event ID string for the captured event
91
 */
92
function captureEvent(event: Event, hint?: EventHint): string;
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
import { captureEvent } from "@sentry/browser";
99

100
// Custom event with full structure
101
captureEvent({
102
  message: "Custom business logic event",
103
  level: "info",
104
  tags: { module: "payment", action: "refund" },
105
  extra: { 
106
    amount: 99.99, 
107
    currency: "USD", 
108
    reason: "customer_request" 
109
  },
110
  contexts: {
111
    payment: {
112
      provider: "stripe",
113
      method: "credit_card",
114
    },
115
  },
116
});
117

118
// Event with custom fingerprint for grouping
119
captureEvent({
120
  message: "Rate limit exceeded",
121
  level: "warning",
122
  fingerprint: ["rate-limit", "{{ default }}"],
123
  tags: { endpoint: "/api/search" },
124
});
125
```
126

127
### Feedback Capture
128

129
Capture user feedback associated with errors or general feedback.
130

131
```typescript { .api }
132
/**
133
 * Capture user feedback and send it to Sentry
134
 * @param feedback - The feedback event to capture
135
 * @param hint - Additional context and configuration for the event
136
 * @returns Event ID string for the captured feedback
137
 */
138
function captureFeedback(feedback: FeedbackEvent, hint?: EventHint): string;
139
```
140

141
### Session Capture
142

143
Capture session-related events.
144

145
```typescript { .api }
146
/**
147
 * Capture session information
148
 * @param end - Whether to end the current session
149
 */
150
function captureSession(end?: boolean): void;
151
```
152

153
### Event Processing
154

155
Get the ID of the last captured event.
156

157
```typescript { .api }
158
/**
159
 * Get the ID of the last event that was captured
160
 * @returns Event ID string or undefined if no event was captured
161
 */
162
function lastEventId(): string | undefined;
163
```
164

165
Add custom event processors to modify events before they are sent.
166

167
```typescript { .api }
168
/**
169
 * Add a global event processor that processes all events
170
 * @param processor - Function that processes and optionally modifies events
171
 */
172
function addEventProcessor(processor: EventProcessor): void;
173

174
type EventProcessor = (event: Event, hint: EventHint) => Event | null | PromiseLike<Event | null>;
175
```
176

177
**Usage Example:**
178

179
```typescript
180
import { addEventProcessor } from "@sentry/browser";
181

182
addEventProcessor((event, hint) => {
183
  // Add custom data to all events
184
  event.tags = {
185
    ...event.tags,
186
    customTag: "customValue",
187
  };
188
  
189
  // Filter out events containing sensitive data
190
  if (event.message && event.message.includes("password")) {
191
    return null; // Don't send this event
192
  }
193
  
194
  return event;
195
});
196
```
197

198
## Types
199

200
### Event Structure
201

202
```typescript { .api }
203
interface Event {
204
  /** Unique identifier for this event */
205
  event_id?: string;
206
  
207
  /** Primary message for this event */
208
  message?: string;
209
  
210
  /** Timestamp when the event occurred */
211
  timestamp?: number;
212
  
213
  /** Severity level */
214
  level?: SeverityLevel;
215
  
216
  /** Platform identifier */
217
  platform?: string;
218
  
219
  /** Logger name that created this event */
220
  logger?: string;
221
  
222
  /** Server name where event occurred */
223
  server_name?: string;
224
  
225
  /** Release version */
226
  release?: string;
227
  
228
  /** Distribution identifier */
229
  dist?: string;
230
  
231
  /** Environment name */
232
  environment?: string;
233
  
234
  /** Loaded modules */
235
  modules?: { [key: string]: string };
236
  
237
  /** Additional arbitrary data */
238
  extra?: { [key: string]: any };
239
  
240
  /** Tags for categorization and filtering */
241
  tags?: { [key: string]: Primitive };
242
  
243
  /** Structured context data */
244
  contexts?: { [key: string]: Context };
245
  
246
  /** User information */
247
  user?: User;
248
  
249
  /** Exception information */
250
  exception?: {
251
    values?: Exception[];
252
  };
253
  
254
  /** Stack trace information */
255
  stacktrace?: Stacktrace;
256
  
257
  /** HTTP request information */
258
  request?: Partial<Request>;
259
  
260
  /** Transaction name */
261
  transaction?: string;
262
  
263
  /** Custom fingerprint for event grouping */
264
  fingerprint?: string[];
265
  
266
  /** Breadcrumbs leading up to this event */
267
  breadcrumbs?: Breadcrumb[];
268
}
269
```
270

271
### Event Hint
272

273
```typescript { .api }
274
interface EventHint {
275
  /** Original exception object that caused this event */
276
  originalException?: unknown;
277
  
278
  /** Synthetic exception created for this event */
279
  syntheticException?: Error;
280
  
281
  /** Event ID to use for this event */
282
  event_id?: string;
283
  
284
  /** Additional tags to apply */
285
  tags?: { [key: string]: Primitive };
286
  
287
  /** Additional extra data to apply */
288
  extra?: { [key: string]: any };
289
  
290
  /** Severity level override */
291
  level?: SeverityLevel;
292
  
293
  /** Fingerprint override */
294
  fingerprint?: string[];
295
  
296
  /** Mechanism that captured this event */
297
  mechanism?: Mechanism;
298
}
299
```
300

301
### Severity Levels
302

303
```typescript { .api }
304
type SeverityLevel = "fatal" | "error" | "warning" | "info" | "debug";
305
```
306

307
### Exception Structure
308

309
```typescript { .api }
310
interface Exception {
311
  /** Exception type (e.g., "TypeError") */
312
  type?: string;
313
  
314
  /** Exception message */
315
  value?: string;
316
  
317
  /** Module where exception occurred */
318
  module?: string;
319
  
320
  /** Thread ID */
321
  thread_id?: number;
322
  
323
  /** Stack trace for this exception */
324
  stacktrace?: Stacktrace;
325
  
326
  /** Mechanism that caught this exception */
327
  mechanism?: Mechanism;
328
}
329
```
330

331
### Mechanism
332

333
```typescript { .api }
334
interface Mechanism {
335
  /** Type of mechanism (e.g., "generic", "promise") */
336
  type: string;
337
  
338
  /** Whether this was handled or unhandled */
339
  handled?: boolean;
340
  
341
  /** Additional mechanism data */
342
  data?: { [key: string]: any };
343
  
344
  /** Description of the mechanism */
345
  description?: string;
346
  
347
  /** Help URL for this mechanism */
348
  help_link?: string;
349
  
350
  /** Whether mechanism data should be included in grouping */
351
  synthetic?: boolean;
352
}
353
```
354

355
### Feedback Event
356

357
```typescript { .api }
358
interface FeedbackEvent {
359
  /** User's name */
360
  name?: string;
361
  
362
  /** User's email */
363
  email?: string;
364
  
365
  /** Feedback message */
366
  message: string;
367
  
368
  /** Associated event ID */
369
  event_id?: string;
370
  
371
  /** URL where feedback was given */
372
  url?: string;
373
  
374
  /** User information */
375
  user?: User;
376
  
377
  /** Additional tags */
378
  tags?: { [key: string]: Primitive };
379
}
380
```
381

382
## Error Handling Patterns
383

384
### Automatic Error Capture
385

386
The SDK automatically captures unhandled errors and promise rejections when properly configured with integrations:
387

388
```typescript
389
import * as Sentry from "@sentry/browser";
390

391
Sentry.init({
392
  dsn: "YOUR_DSN",
393
  integrations: [
394
    Sentry.globalHandlersIntegration(), // Captures unhandled errors
395
    Sentry.browserApiErrorsIntegration(), // Captures browser API errors
396
  ],
397
});
398
```
399

400
### Manual Error Boundaries
401

402
For React applications or manual error handling:
403

404
```typescript
405
import { captureException, withScope } from "@sentry/browser";
406

407
function handleError(error: Error, errorInfo?: any) {
408
  withScope((scope) => {
409
    if (errorInfo) {
410
      scope.setContext("errorInfo", errorInfo);
411
    }
412
    scope.setTag("errorBoundary", true);
413
    captureException(error);
414
  });
415
}
416
```
417

418
### Filtering Sensitive Data
419

420
Use beforeSend to filter out sensitive information:
421

422
```typescript
423
Sentry.init({
424
  dsn: "YOUR_DSN",
425
  beforeSend(event, hint) {
426
    // Remove sensitive data
427
    if (event.extra) {
428
      delete event.extra.password;
429
      delete event.extra.creditCard;
430
    }
431
    
432
    // Filter out noisy errors
433
    if (event.exception) {
434
      const error = hint.originalException;
435
      if (error instanceof TypeError && error.message.includes("Script error")) {
436
        return null;
437
      }
438
    }
439
    
440
    return event;
441
  },
442
});
443
```