Filtering

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.

Filtering Error Events

Configure your SDK to filter error events by using the beforeSend callback method and configuring, enabling, or disabling integrations.

Using beforeSend

All Sentry SDKs support the beforeSend callback method. beforeSend is called immediately before the event is sent to the server, so it’s the final place where you can edit its data. It receives the event object as a parameter, so you can use that to modify the event’s data or drop it completely (by returning null) based on custom logic and the data available on the event.

import io.sentry.Sentry;

Sentry.init(options -> {
  options.setBeforeSend((event, hint) -> {
    // Modify the event here:
    event.setServerName(null); // Don't send server names.
    return event;
  });
});

Note also that breadcrumbs can be filtered, as discussed in our Breadcrumbs documentation.

Event Hints

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

import io.sentry.Sentry;

Sentry.init(options -> {
  options.setBeforeSend((event, hint) -> {
    if (hint instanceof MyHint) {
      return null;
    } else {
      return event;
    }
  });
});

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).

Using Hints

Hints are available in two places:

1. beforeSend / beforeBreadcrumb
2. eventProcessors

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.

import io.sentry.Sentry;
import java.sql.SQLException;
import java.util.Arrays;

Sentry.init(options -> {
  options.setBeforeSend((event, hint) -> {
    if (event.getThrowable() instanceof SQLException) {
      event.setFingerprints(Arrays.asList("database-connection-error"));
    }
    return event;
  });
});

Hints for Events

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.

Hints for Breadcrumbs

Decluttering Sentry

Filtering Transaction Events

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.

Using tracesSampler

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:

import io.sentry.Sentry;

Sentry.init(options -> {
  options.setTracesSampler(context -> {
    // If this is the continuation of a trace, just use that decision (rate controlled by the caller).
    Boolean parentSampled = context.getTransactionContext().getParentSampled();
    if (parentSampled != null) {
      return parentSampled ? 1.0 : 0.0;
    }
    if (/* make a decision based on `samplingContext` */) {
      // Drop this transaction, by setting its sample rate to 0%
      return 0.0;
    } else if (/* ... */) {
      // Override sample rate for other cases (replaces `options.TracesSampleRate`)
      return 0.1;
    }
    // Can return `null` to fallback to the rate configured by `options.tracesSampleRate`
    return null;
  });
});

It also allows you to sample different transactions at different rates.

Learn more about configuring the sample rate.

Using beforeSendTransaction

import io.sentry.Sentry;

Sentry.init(options -> {
  options.setBeforeSendTransaction((transaction, hint) -> {
    // Modify or drop the transaction here:
    if ("/unimportant/route".equals(transaction.getTransaction())) {
      // Don't send the transaction to Sentry
      return null;
    } else {
      return transaction;
    }
  });
});