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.

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.

Filtering Error Events

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

Using ignoreErrors

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$/],
});

See ignoreErrors for details.

Using beforeSend

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. This hook is called for both error and message events.

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  beforeSend(event) {
    if (event.user) {
      // Don't send user's email address
      delete event.user.email;
    }
    return event;
  },
});

See beforeSend for details, and Using Hints for details on the hint object.

Using allowUrls and denyUrls

You can construct an allowed list of domains for errors. Only errors created within these domains will be captured. 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 errors created on specific URLs from being sent to Sentry.

• See allowUrls details
• See denyUrls details

Using thirdPartyErrorFilterIntegration

Available in browser-based SDKs from version 8.10.0

The thirdPartyErrorFilterIntegration allows you to filter out errors originating from third parties, such as browser extensions, code-injecting browsers, or widgets from third-party services that also use Sentry. This integration can be very helpful in reducing noise that's not related to your own application code.

This integration works by "marking" your JavaScript files with an "application key" during the build process. At runtime, if an error occurs, this integration checks application keys for each stack frame in the stack trace. This allows you to filter out errors with "unmarked" stack frames, which would indicate third-party code.

To set up this integration and to mark your JavaScript files with an application key, first pass an applicationKey option to your Sentry bundler plugin. This can be an arbitrary string that identifies your application code:

// vite.config.ts
import { defineConfig } from "vite";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  plugins: [
    sentryVitePlugin({
      applicationKey: "your-custom-application-key",
    }),
  ],
});

Next, add the thirdPartyErrorFilterIntegration to your Sentry initialization:

Sentry.init({
  integrations: [
    Sentry.thirdPartyErrorFilterIntegration({
      // Specify the application keys that you specified in the Sentry bundler plugin
      filterKeys: ["your-custom-application-key"],

      // Defines how to handle errors that contain third party stack frames.
      // Possible values are:
      // - 'drop-error-if-contains-third-party-frames'
      // - 'drop-error-if-exclusively-contains-third-party-frames'
      // - 'apply-tag-if-contains-third-party-frames'
      // - 'apply-tag-if-exclusively-contains-third-party-frames'
      behaviour: "drop-error-if-contains-third-party-frames",
    }),
  ],
});

The filterKeys option takes an array of strings that should be equal to the applicationKey value set in the bundler plugin options. Unless your website hosts files from more than one of your build-processes, this array should only contain one item.

The behaviour option defines what should happen with errors that contain stack frames from third-party code. There are four modes you can choose from:

• "drop-error-if-contains-third-party-frames": Drop error events that contain at least one third-party stack frame.
• "drop-error-if-exclusively-contains-third-party-frames": Drop error events that exclusively contain third-party stack frames.
• "apply-tag-if-contains-third-party-frames": Keep all error events, but apply a third_party_code: true tag in case the error contains at least one third-party stack frame.
• "apply-tag-if-exclusively-contains-third-party-frames": Keep all error events, but apply a third_party_code: true tag in case the error contains exclusively third-party stack frames.

If you choose a mode to only apply tags, the tags can then be used in Sentry to filter your issue stream with the third_party_code tag in the issue search bar.

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 ignoreTransactions

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$/],
});

See ignoreTransactions for details.

Using tracesSampler

You can also use the tracesSampler option to prevent certain transactions from being reported to Sentry.

See Sampling on information about how to use it.

Using beforeSendTransaction

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  beforeSendTransaction(event) {
    if (event.transaction === "/unimportant/route") {
      // Don't send the event to Sentry
      return null;
    }
    return event;
  },
});

See beforeSendTransaction for details, and Using Hints for details on the hint object.

Filtering Spans

Use the beforeSendSpan configuration option which allows you to provide a function to modify a span. This function is called for the root span and all child spans. If you want to drop the root span, including its child spans, use beforeSendTransaction instead. Please note that you cannot use beforeSendSpan to drop a span, you can only modify it and filter data on it.

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  beforeSendSpan(span) {
    if (span.description === "should be renamed") {
      span.description = "renamed span";
      span.data = {
        ...span.data,
        myExtraAttribute: true,
      };
    }

    return span;
  },
});

See beforeSendSpan for details.

Filtering Breadcrumbs

You can filter breadcrumbs by using the beforeBreadcrumb configuration option:

Sentry.init({
  // ...
  beforeBreadcrumb(breadcrumb, hint) {
    return breadcrumb.category === "ui.click" ? null : breadcrumb;
  },
});

See beforeBreadcrumb for details.

Using Hints

Hints are available in two places:

1. beforeSend / beforeBreadcrumb
2. Event processors added via Sentry.addEventProcessor()

Event and breadcrumb hints are objects containing various types of 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;
  },
});

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

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