0
# Error and Event Capture
1

2
Functions for capturing exceptions, messages, events, and user feedback.
3

4
## Capabilities
5

6
### Exception Capture
7

8
Capture exceptions and errors with optional context.
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 captureContext - Optional context to attach to the event
15
 * @returns Event ID of the captured exception
16
 */
17
function captureException(exception: any, captureContext?: CaptureContext): string;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import * as Sentry from "@sentry/node";
24

25
// Capture a basic exception
26
try {
27
  throw new Error("Something went wrong!");
28
} catch (error) {
29
  Sentry.captureException(error);
30
}
31

32
// Capture with additional context
33
try {
34
  processUserData(userData);
35
} catch (error) {
36
  Sentry.captureException(error, {
37
    tags: {
38
      section: "user-processing",
39
    },
40
    extra: {
41
      userData: userData,
42
      timestamp: Date.now(),
43
    },
44
    user: {
45
      id: userId,
46
      email: userEmail,
47
    },
48
    level: "error",
49
  });
50
}
51

52
// Capture with scope callback
53
try {
54
  performCriticalOperation();
55
} catch (error) {
56
  Sentry.captureException(error, (scope) => {
57
    scope.setTag("operation", "critical");
58
    scope.setLevel("fatal");
59
    scope.setContext("operation_details", {
60
      startTime: operationStartTime,
61
      parameters: operationParams,
62
    });
63
    return scope;
64
  });
65
}
66
```
67

68
### Message Capture
69

70
Capture messages with different severity levels.
71

72
```typescript { .api }
73
/**
74
 * Capture a message and send it to Sentry
75
 * @param message - The message to capture
76
 * @param level - Severity level of the message (optional, defaults to 'info')
77
 * @param captureContext - Optional context to attach to the event
78
 * @returns Event ID of the captured message
79
 */
80
function captureMessage(
81
  message: string, 
82
  level?: SeverityLevel, 
83
  captureContext?: CaptureContext
84
): string;
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import * as Sentry from "@sentry/node";
91

92
// Basic message capture
93
Sentry.captureMessage("User performed important action");
94

95
// Message with severity level
96
Sentry.captureMessage("Database connection slow", "warning");
97

98
// Message with context
99
Sentry.captureMessage("Payment processed successfully", "info", {
100
  tags: {
101
    component: "payment",
102
    method: "stripe",
103
  },
104
  extra: {
105
    amount: paymentAmount,
106
    currency: "USD",
107
    transactionId: txnId,
108
  },
109
});
110
```
111

112
### Custom Event Capture
113

114
Capture custom events with full control over event structure.
115

116
```typescript { .api }
117
/**
118
 * Capture a custom event and send it to Sentry
119
 * @param event - The event object to capture
120
 * @param hint - Optional hint for event processing
121
 * @returns Event ID of the captured event
122
 */
123
function captureEvent(event: Event, hint?: EventHint): string;
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
import * as Sentry from "@sentry/node";
130

131
// Capture custom event
132
Sentry.captureEvent({
133
  message: "Custom business logic event",
134
  level: "info",
135
  tags: {
136
    component: "business-logic",
137
    feature: "user-onboarding",
138
  },
139
  extra: {
140
    step: "email-verification",
141
    userId: user.id,
142
    timestamp: Date.now(),
143
  },
144
});
145

146
// Capture with fingerprint for grouping
147
Sentry.captureEvent({
148
  message: "Rate limit exceeded",
149
  level: "warning",
150
  fingerprint: ["rate-limit", "{{ default }}"],
151
  tags: {
152
    endpoint: "/api/users",
153
    method: "POST",
154
  },
155
  extra: {
156
    rateLimitKey: rateLimitKey,
157
    requestCount: currentRequestCount,
158
    timeWindow: timeWindow,
159
  },
160
});
161
```
162

163
### User Feedback Capture
164

165
Capture user feedback associated with events.
166

167
```typescript { .api }
168
/**
169
 * Capture user feedback for an event
170
 * @param feedback - User feedback object
171
 * @returns Event ID of the captured feedback
172
 */
173
function captureFeedback(feedback: UserFeedback): string;
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
import * as Sentry from "@sentry/node";
180

181
// Capture user feedback for the last event
182
const eventId = Sentry.captureException(error);
183
Sentry.captureFeedback({
184
  event_id: eventId,
185
  email: "user@example.com",
186
  name: "John Doe",
187
  comments: "The application crashed when I tried to upload a file",
188
});
189

190
// Capture feedback with all optional fields
191
Sentry.captureFeedback({
192
  event_id: lastEventId,
193
  email: user.email,
194
  name: user.name,
195
  comments: feedbackText,
196
  associatedEventId: eventId, // Alternative to event_id
197
});
198
```
199

200
### Event ID Utilities
201

202
Get the ID of the last captured event.
203

204
```typescript { .api }
205
/**
206
 * Get the ID of the last event that was sent to Sentry
207
 * @returns Event ID string or undefined if no events have been sent
208
 */
209
function lastEventId(): string | undefined;
210
```
211

212
**Usage Examples:**
213

214
```typescript
215
import * as Sentry from "@sentry/node";
216

217
// Capture an exception and get its ID
218
Sentry.captureException(new Error("Something failed"));
219
const eventId = Sentry.lastEventId();
220

221
if (eventId) {
222
  console.log(`Error reported with ID: ${eventId}`);
223
  // You could store this ID for user support tickets
224
}
225
```
226

227
### Breadcrumbs
228

229
Add breadcrumbs to provide context for captured events.
230

231
```typescript { .api }
232
/**
233
 * Add a breadcrumb to the current scope
234
 * @param breadcrumb - Breadcrumb object with message, category, and other data
235
 * @param hint - Optional hint for breadcrumb processing
236
 */
237
function addBreadcrumb(breadcrumb: Breadcrumb, hint?: BreadcrumbHint): void;
238
```
239

240
**Usage Examples:**
241

242
```typescript
243
import * as Sentry from "@sentry/node";
244

245
// Add basic breadcrumb
246
Sentry.addBreadcrumb({
247
  message: "User clicked login button",
248
  category: "ui.click",
249
  level: "info",
250
});
251

252
// Add breadcrumb with data
253
Sentry.addBreadcrumb({
254
  message: "Database query executed",
255
  category: "query",
256
  level: "info",
257
  data: {
258
    query: "SELECT * FROM users WHERE id = ?",
259
    duration: 145,
260
    rowCount: 1,
261
  },
262
});
263

264
// Add navigation breadcrumb
265
Sentry.addBreadcrumb({
266
  message: "Navigation to /dashboard",
267
  category: "navigation",
268
  level: "info",
269
  data: {
270
    from: "/login",
271
    to: "/dashboard",
272
    method: "GET",
273
  },
274
});
275

276
// Add HTTP request breadcrumb
277
Sentry.addBreadcrumb({
278
  message: "HTTP request",
279
  category: "http",
280
  level: "info",
281
  data: {
282
    url: "https://api.example.com/users",
283
    method: "POST",
284
    status_code: 201,
285
    response_time: 234,
286
  },
287
});
288
```
289

290
## Types
291

292
### Capture Context
293

294
```typescript { .api }
295
type CaptureContext = 
296
  | Partial<ScopeContext> 
297
  | ((scope: Scope) => Scope);
298

299
interface ScopeContext {
300
  /** Tags to attach to the event */
301
  tags?: { [key: string]: Primitive };
302
  /** Extra data to attach to the event */
303
  extra?: { [key: string]: any };
304
  /** Contexts to attach to the event */
305
  contexts?: { [key: string]: Context };
306
  /** User information */
307
  user?: User;
308
  /** Severity level */
309
  level?: SeverityLevel;
310
  /** Event fingerprint for grouping */
311
  fingerprint?: string[];
312
}
313
```
314

315
### Event Types
316

317
```typescript { .api }
318
interface Event {
319
  /** Event ID */
320
  event_id?: string;
321
  /** Event message */
322
  message?: string;
323
  /** Event timestamp */
324
  timestamp?: number;
325
  /** Event level */
326
  level?: SeverityLevel;
327
  /** Event platform */
328
  platform?: string;
329
  /** Event logger name */
330
  logger?: string;
331
  /** Event server name */
332
  server_name?: string;
333
  /** Event release */
334
  release?: string;
335
  /** Event environment */
336
  environment?: string;
337
  /** Event tags */
338
  tags?: { [key: string]: Primitive };
339
  /** Event extra data */
340
  extra?: { [key: string]: any };
341
  /** Event contexts */
342
  contexts?: { [key: string]: Context };
343
  /** Event user */
344
  user?: User;
345
  /** Event breadcrumbs */
346
  breadcrumbs?: Breadcrumb[];
347
  /** Event fingerprint */
348
  fingerprint?: string[];
349
  /** Event exception */
350
  exception?: {
351
    values?: Exception[];
352
  };
353
  /** Event stacktrace */
354
  stacktrace?: Stacktrace;
355
}
356

357
interface EventHint {
358
  /** Original exception object */
359
  originalException?: any;
360
  /** Synthetic exception created for the event */
361
  syntheticException?: Error;
362
  /** Event ID */
363
  event_id?: string;
364
  /** Additional context data */
365
  data?: any;
366
}
367
```
368

369
### User Feedback
370

371
```typescript { .api }
372
interface UserFeedback {
373
  /** Event ID that the feedback is associated with */
374
  event_id: string;
375
  /** User's email address */
376
  email: string;  
377
  /** User's name */
378
  name: string;
379
  /** User's feedback comments */
380
  comments: string;
381
}
382
```
383

384
### Breadcrumb Types
385

386
```typescript { .api }
387
interface Breadcrumb {
388
  /** Breadcrumb message */
389
  message?: string;
390
  /** Breadcrumb category */
391
  category?: string;
392
  /** Breadcrumb severity level */
393
  level?: SeverityLevel;
394
  /** Breadcrumb timestamp */
395
  timestamp?: number;
396
  /** Breadcrumb type */
397
  type?: string;
398
  /** Additional breadcrumb data */
399
  data?: { [key: string]: any };
400
}
401

402
interface BreadcrumbHint {
403
  /** Input data for the breadcrumb */
404
  input?: any;
405
  /** DOM event that triggered the breadcrumb */
406
  event?: Event;
407
  /** XMLHttpRequest object */
408
  xhr?: XMLHttpRequest;
409
}
410
```
411

412
### Severity Levels
413

414
```typescript { .api }
415
type SeverityLevel = "fatal" | "error" | "warning" | "log" | "info" | "debug";
416
```