The captureException function captures an exception or error and sends it to Sentry.
Function Signature
export function captureException(
exception: unknown,
captureContext?: CaptureContext
): string
Parameters
The exception to capture. Can be an Error object, string, or any value.
Additional context for the exception. Can be:
- A Scope object
- A partial ScopeContext object
- A callback function receiving the current scope
Returns
The unique ID of the captured event.
Basic Usage
import * as Sentry from '@sentry/node';
try {
riskyOperation();
} catch (error) {
Sentry.captureException(error);
}
With Context
Using Object Context
import * as Sentry from '@sentry/node';
try {
await processPayment(userId, amount);
} catch (error) {
Sentry.captureException(error, {
tags: {
payment_method: 'credit_card',
currency: 'USD'
},
extra: {
userId,
amount,
timestamp: Date.now()
},
level: 'error'
});
}
Using Scope Callback
import * as Sentry from '@sentry/node';
try {
await fetchUserData(userId);
} catch (error) {
Sentry.captureException(error, (scope) => {
scope.setTag('operation', 'fetch_user');
scope.setContext('user', {
id: userId,
action: 'data_fetch'
});
scope.setLevel('warning');
return scope;
});
}
Advanced Examples
With User Context
import * as Sentry from '@sentry/node';
try {
authenticateUser(credentials);
} catch (error) {
Sentry.captureException(error, {
user: {
id: credentials.userId,
email: credentials.email,
ip_address: '{{auto}}'
},
tags: {
auth_method: 'oauth'
}
});
}
With Fingerprinting
Control how errors are grouped in Sentry:
import * as Sentry from '@sentry/node';
try {
connectToDatabase();
} catch (error) {
Sentry.captureException(error, {
fingerprint: ['database-connection', process.env.DB_HOST],
tags: {
database: 'postgresql',
host: process.env.DB_HOST
}
});
}
With Attachments
import * as Sentry from '@sentry/node';
import { Scope } from '@sentry/node';
try {
processFile(filePath);
} catch (error) {
Sentry.captureException(error, (scope) => {
scope.addAttachment({
filename: 'error-log.txt',
data: logBuffer,
contentType: 'text/plain'
});
return scope;
});
}
Implementation Details
From packages/core/src/client.ts:
public captureException(
exception: unknown,
hint?: EventHint,
scope?: Scope
): string {
const eventId = uuid4();
// Ensure we haven't captured this very object before
if (checkOrSetAlreadyCaught(exception)) {
DEBUG_BUILD && debug.log(ALREADY_SEEN_ERROR);
return eventId;
}
const hintWithEventId = {
event_id: eventId,
...hint,
};
this._process(
() =>
this.eventFromException(exception, hintWithEventId)
.then(event => this._captureEvent(event, hintWithEventId, scope))
.then(res => res),
'error',
);
return hintWithEventId.event_id;
}
Event Processing
Exceptions go through several processing steps:
- Duplicate Check: Ensures the same error object isn’t captured twice
- Event Creation: Converts the exception into an event
- Scope Application: Applies scope data (breadcrumbs, tags, context)
- Event Processors: Runs through event processors
- Sampling: Applies sample rate
- beforeSend: Runs the beforeSend callback
- Transport: Sends to Sentry via transport
Error Types
Error Objects
try {
throw new Error('Something went wrong');
} catch (error) {
Sentry.captureException(error);
}
Custom Errors
class ValidationError extends Error {
constructor(message: string, public field: string) {
super(message);
this.name = 'ValidationError';
}
}
try {
throw new ValidationError('Invalid email', 'email');
} catch (error) {
Sentry.captureException(error, {
tags: {
error_type: 'validation',
field: (error as ValidationError).field
}
});
}
Non-Error Values
// String
Sentry.captureException('Something went wrong');
// Object
Sentry.captureException({
message: 'API Error',
statusCode: 500,
endpoint: '/api/users'
});
// Number
Sentry.captureException(404);
Best Practices
1. Always Include Context
// Bad
Sentry.captureException(error);
// Good
Sentry.captureException(error, {
tags: { operation: 'checkout' },
extra: { orderId, customerId }
});
2. Use Appropriate Severity Levels
try {
await optionalFeature();
} catch (error) {
// Non-critical error
Sentry.captureException(error, {
level: 'warning'
});
}
3. Add Breadcrumbs for Context
import * as Sentry from '@sentry/node';
Sentry.addBreadcrumb({
category: 'api',
message: 'Starting payment process',
level: 'info'
});
try {
await processPayment();
} catch (error) {
// Breadcrumb will be included automatically
Sentry.captureException(error);
}
4. Handle Async Errors
// Promise rejection
fetchData()
.catch(error => {
Sentry.captureException(error);
});
// Async/await
async function handleRequest() {
try {
await processRequest();
} catch (error) {
Sentry.captureException(error);
throw error; // Re-throw if needed
}
}
