Filtering
Learn more about how to configure your SDK to filter events reported to Sentry.
When you add Sentry to your app, you get a lot of valuable information about errors and performance. And lots of information is good -- as long as it's the right information, at a reasonable volume.
Sentry offers Inbound Filters that you can enable per project to filter out various events in sentry.io. You can use our pre-defined inbound filters (e.g. filtering known browser extensions), as well as add your own message-based filters.
However, we recommend filtering at the client-level, because it removes the overhead of sending events you don't actually want. The Sentry SDKs have several configuration options, which are described in this document, to help you filter out events. To learn more about the event fields you can use for filtering, see Event Payloads.
Configure your SDK to filter error events by using the beforeSend callback method and configuring, enabling, or disabling integrations.
You can use the ignoreErrors option to filter out errors that match a certain pattern. This option receives a list of strings and regular expressions to match against the error message. When using strings, partial matches will be filtered out. If you need to filter by exact match, use regex patterns instead.
Sentry.init({
dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
ignoreErrors: ['fb_xd_fragment', /^Exact Match Message$/],
});
You can configure a beforeSend callback method to filter error events. Because it's called immediately before the event is sent to the server, this is your last chance to decide not to send data or to edit it. beforeSend receives the event object as a parameter and, based on custom logic and the data available on the event, you can either modify the event’s data or drop it completely by returning null.
In JavaScript, you can use a function to modify the event or return a completely new one. You can either return null or an event payload - no other return value (including void) is allowed. If you return null, the event will be discarded.
Sentry.init({
dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
// Called for message and error events
beforeSend(event) {
// Modify or drop the event here
if (event.user) {
// Don't send user's email address
delete event.user.email;
}
return event;
},
});
Note also that breadcrumbs can be filtered, as discussed in our Breadcrumbs documentation.
The beforeSend callback is passed both the event and a second argument, hint, that holds one or more hints.
Typically, a hint holds the original exception so that additional data can be extracted or grouping is affected. In this example, the fingerprint is forced to a common value if an exception of a certain type has been caught:
Sentry.init({
// ...
beforeSend(event, hint) {
const error = hint.originalException;
if (
error &&
error.message &&
error.message.match(/database unavailable/i)
) {
event.fingerprint = ['database-unavailable'];
}
return event;
},
});
For information about which hints are available see hints in JavaScript.
When the SDK creates an event or breadcrumb for transmission, that transmission is typically created from some sort of source object. For instance, an error event is typically created from a log record or exception instance. For better customization, SDKs send these objects to certain callbacks (beforeSend, beforeBreadcrumb or the event processor system in the SDK).
Hints are available in two places:
beforeSend/beforeBreadcrumbeventProcessors
Event and breadcrumb hints are objects containing various information used to put together an event or a breadcrumb. Typically hints hold the original exception so that additional data can be extracted or grouping can be affected.
For events, hints contain properties such as event_id, originalException, syntheticException (used internally to generate cleaner stack trace), and any other arbitrary data that you attach.
For breadcrumbs, the use of hints is implementation dependent. For XHR requests, the hint contains the xhr object itself; for user interactions the hint contains the DOM element and event name and so forth.
Sentry.init({
// ...
beforeSend(event, hint) {
const error = hint.originalException;
if (
error &&
error.message &&
error.message.match(/database unavailable/i)
) {
event.fingerprint = ['database-unavailable'];
}
return event;
},
});
originalException
The original exception that caused the Sentry SDK to create the event. This is useful for changing how the Sentry SDK groups events or to extract additional information.
syntheticException
When a string or a non-error object is raised, Sentry creates a synthetic exception so you can get a basic stack trace. This exception is stored here for further data extraction.
level / input
For breadcrumbs created from console log interceptions. This holds the original console log level and the original input data to the log function.
request / response / event
For breadcrumbs created from HTTP requests. This holds the request and response object (from the node HTTP API) as well as the node event (response or error).
You can construct an allowed list of domains which may raise exceptions that should be sent to Sentry. For example, if your scripts are loaded from cdn.example.com and your site is example.com, you can set allowUrls to:
Sentry.init({
allowUrls: [/https?:\/\/((cdn|www)\.)?example\.com/],
});
You can also use denyUrls if you want to block specific URLs from sending exceptions to Sentry.
To prevent certain transactions from being reported to Sentry, use the tracesSampler or beforeSendTransaction configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want.
You can use the ignoreTransactions option to filter out transactions that match a certain pattern. This option receives a list of strings and regular expressions to match against the transaction name. When using strings, partial matches will be filtered out. If you need to filter by exact match, use regex patterns instead.
Sentry.init({
dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
ignoreTransactions: ['partial/match', /^Exact Transaction Name$/],
});
Note: The tracesSampler and tracesSampleRate config options are mutually exclusive. If you define a tracesSampler to filter out certain transactions, you must also handle the case of non-filtered transactions by returning the rate at which you'd like them sampled.
In its simplest form, used just for filtering the transaction, it looks like this:
Sentry.init({
// ...
tracesSampler: samplingContext => {
if ('...') {
// Drop this transaction, by setting its sample rate to 0%
return 0;
} else {
// Default sample rate for all others (replaces tracesSampleRate)
return 1;
}
},
});
It also allows you to sample different transactions at different rates.
If the transaction currently being processed has a parent transaction (from an upstream service calling this service), the parent (upstream) sampling decision will always be included in the sampling context data, so that your tracesSampler can choose whether and when to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. See Inheriting the parent sampling decision to learn more.
Learn more about configuring the sample rate.
Sentry.init({
dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
// Called for transaction events
beforeSendTransaction(event) {
// Modify or drop the event here
if (event.transaction === '/unimportant/route') {
// Don't send the event to Sentry
return null;
}
return event;
},
});
To prevent certain spans from being reported to Sentry, use the beforeSendSpan configuration option, which allows you to provide a function to evaluate the current span and drop it if it's not one you want.
Sentry.init({
dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
// Called for spans
beforeSendSpan(span) {
// Modify or drop the span here
if (span.description === 'unimportant span') {
// Don't send the span to Sentry
return null;
}
return span;
},
});
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").