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.
The Sentry SDKs have several configuration options to help you filter out events.
We also offer Inbound Filters to filter events in sentry.io. We recommend filtering at the client level though, because it removes the overhead of sending events you don't actually want. Learn more about the fields available in an event.
Configure your SDK to filter error events by using the before_send
callback method and configuring, enabling, or disabling integrations.
All Sentry SDKs support the before_send
callback method. 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. before_send
receives the event object as a parameter, which you can use to either modify the event’s data or drop it completely by returning null
, based on custom logic and the data available on the event.
#include <sentry.h>
sentry_value_t strip_sensitive_data(sentry_value_t event, void *hint) {
/* modify event here or return NULL to discard the event */
return event;
}
int main(void) {
sentry_options_t *options = sentry_options_new();
sentry_options_set_before_send(options, strip_sensitive_data, NULL);
sentry_init(options);
/* ... */
}
The callback is executed in the same thread as the call to sentry_capture_event
. Work performed by the function may thus block the executing thread. For this reason, consider avoiding heavy work in before_send
.
The before_send
callback implementation in sentry-native
makes it hard to distinguish between normal events and crashes. For this reason, we introduced another callback, on_crash
, which - at this point - only exists in sentry_native
:
#include <sentry.h>
static sentry_value_t
crash_cleanup(
const sentry_ucontext_t *uctx, // provides the user-space context of the crash
sentry_value_t event, // used the same way as in `before_send`
void *closure // user-data that you can provide at configuration time
)
{
// Do contextual clean-up before the crash is sent to sentry's backend infrastructure
/* ... */
// tell the backend to retain the event (+ dump)
// or to discard it, you could free the event and return a `null`:
// sentry_value_decref(event);
// return sentry_value_new_null();
return event;
}
int main(void) {
sentry_options_t *options = sentry_options_new();
sentry_options_set_on_crash(options, crash_cleanup, NULL);
sentry_init(options);
/* ... */
}
The on_crash
callback replaces before_send
as a callback for crash events only. They can be defined simultaneously, where the SDK prevents before_send
from being invoked for crash events. This allows for better differentiation between crashes and other events and gradual migration from existing before_send
implementations:
- If you have a
before_send
implementation and do not define anon_crash
callbackbefore_send
will receive both normal and crash events as before - If you only want to pre-process normal events with
before_send
, then you can define an "empty"on_crash
callback that returns the passed-in event and does nothing else. - If you are not interested in pre-processing normal events but only want to act on crashes, then only define an
on_crash
callback with the option to filter (available for all backends) or enrich (only forinproc
) the crash event.
Not Supported in Crashpad on macOS
The Crashpad backend on macOS doesn't currently support notifying the crashing process and thus can't correctly terminate sessions or call the registered before_send
or on_crash
hooks. It will also lose any events queued for sending at the time of the crash.
Limitations in Crashpad on Windows for Fast-fail Crashes
The Crashpad backend on Windows supports fast-fail crashes, which bypass SEH (Structured Exception Handling) primarily for security reasons. sentry-native
registers a WER (Windows Error Reporting) module, which signals the crashpad_handler
to send a minidump when a fast-fail crash occurs. However, since this process bypasses SEH, the application local exception handler is no longer invoked, which also means that for these kinds of crashes, before_send
and on_crash
will not be invoked before sending the minidump and thus have no effect.
Note also that breadcrumbs can be filtered, as discussed in our Breadcrumbs documentation.
The before_send
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:
The Native SDK does not pass exception information into the hint, but instead allows to set a custom hint in SDK options. To detect the exception type, inspect the event instead.
#include <string.h>
#include <sentry.h>
sentry_value_t before_send(sentry_value_t event, void *hint) {
/* sentry_value_t functions handle NULL automatically */
sentry_value_t exceptions = sentry_value_get_by_key(event, "exception");
sentry_value_t values = sentry_value_get_by_key(exceptions, "values");
sentry_value_t exception = sentry_value_get_by_index(values, 0);
sentry_value_t type = sentry_value_get_by_key(exception, "type");
const char *type_str = sentry_value_as_string(type);
/* use the data passed during initialization */
const char *custom_error = (const char *)hint;
if (type_str && strcmp(type_str, custom_error) == 0) {
sentry_value_t fingerprint = sentry_value_new_list();
sentry_value_append(fingerprint, sentry_value_new_string("custom-error"));
sentry_value_set_by_key(event, "fingerprint", fingerprint);
}
return event;
}
int main(void) {
sentry_options_t *options = sentry_options_new();
sentry_options_set_before_send(options, before_send, (void *)"CustomError");
sentry_init(options);
/* ... */
}
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 (before_send
, before_breadcrumb
or the event processor system in the SDK).
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").