Filtering

Learn more about how to configure your Sentry Apple 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 beforeSend callback method and configuring, enabling, or disabling integrations.

All Sentry SDKs support the beforeSend 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. beforeSend 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.

Copied

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.beforeSend = { event in
        // modify event here or return nil to discard the event
        return event
    }
}

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.beforeSend = { event in
        // modify event here or return nil to discard the event
        return event
    }
}

@import Sentry;

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.beforeSend = ^SentryEvent * _Nullable(SentryEvent * _Nonnull event) {
        // modify event here or return nil to discard the event
        return event;
    };
}];

#import <SentryObjC/SentryObjC.h>

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.beforeSend = ^SentryObjCEvent * _Nullable(SentryObjCEvent * _Nonnull event) {
        // modify event here or return nil to discard the event
        return event;
    };
}];

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

If you need access to the original error, exception, or attachments that produced an event, use beforeSendWithHint instead of beforeSend. When beforeSendWithHint is configured, it is called instead of beforeSend. The callback receives both the event and a hint that holds additional context.

Typically, a hint holds the original exception so that additional data can be extracted or grouping is affected. In this example, the event is dropped if the original error belongs to a domain you want to ignore:

Copied

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.beforeSendWithHint = { event, hint in
        // Access the original error that triggered this event
        if let error = hint.originalError as NSError?,
           error.domain == "com.example.ignorable" {
            return nil // Drop the event
        }

        // Add or remove attachments before they are sent
        hint.attachments = hint.attachments.filter { $0.filename != "sensitive.txt" }

        return event
    }
}

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.beforeSendWithHint = { event, hint in
        // Access the original error that triggered this event
        if let error = hint.originalError as NSError?,
           error.domain == "com.example.ignorable" {
            return nil // Drop the event
        }

        // Add or remove attachments before they are sent
        hint.attachments = hint.attachments.filter { $0.filename != "sensitive.txt" }

        return event
    }
}

@import Sentry;

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.beforeSendWithHint = ^SentryEvent * _Nullable(SentryEvent * _Nonnull event, SentryHint * _Nonnull hint) {
        // Access the original error that triggered this event
        NSError *error = hint.originalError;
        if ([error.domain isEqualToString:@"com.example.ignorable"]) {
            return nil; // Drop the event
        }

        return event;
    };
}];

#import <SentryObjC/SentryObjC.h>

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.beforeSendWithHint = ^SentryObjCEvent * _Nullable(SentryObjCEvent * _Nonnull event, SentryObjCHint * _Nonnull hint) {
        // Access the original error that triggered this event
        NSError *error = hint.originalError;
        if ([error.domain isEqualToString:@"com.example.ignorable"]) {
            return nil; // Drop the event
        }

        return event;
    };
}];

Hints are available in Sentry Cocoa SDK version 9.28.0 and above.

beforeSendWithHint and beforeBreadcrumbWithHint are transitional APIs. In the next major version, the hint parameter will be added to beforeSend and beforeBreadcrumb directly.

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 an NSError or NSException instance. For better customization, the SDK sends these objects to certain callbacks (beforeSendWithHint, beforeBreadcrumbWithHint).

Hints are available in two places:

beforeSendWithHint / beforeBreadcrumbWithHint
The hint parameter on SentrySDK.capture methods

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 originalError, originalException, and attachments (the list of attachments that will be sent with the event, including screenshots and view hierarchies when enabled).

For breadcrumbs, hints contain the urlRequest and httpResponse when the breadcrumb originates from a network operation.

originalError

The original Error (typically an NSError) 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.

originalException

The original NSException that caused the Sentry SDK to create the event.

attachments

The attachments that will be sent alongside the event. The SDK pre-populates this list (including screenshots and view hierarchies when enabled) before the callback runs. You can add or remove attachments by modifying this array.

Similarly, when beforeBreadcrumbWithHint is configured, it is called instead of beforeBreadcrumb.

urlRequest

For breadcrumbs created from HTTP network operations, the hint contains the original URLRequest. This can be used to filter breadcrumbs by URL or extract additional request data.

httpResponse

For breadcrumbs created from HTTP network operations, the hint contains the HTTPURLResponse. This can be used to inspect status codes, headers, or other response metadata.

Copied

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.beforeBreadcrumbWithHint = { breadcrumb, hint in
        // Access the original HTTP request for network breadcrumbs
        if let request = hint.urlRequest {
            if request.url?.host == "internal-api.example.com" {
                return nil // Drop breadcrumbs for internal API calls
            }
        }

        return breadcrumb
    }
}

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.beforeBreadcrumbWithHint = { breadcrumb, hint in
        // Access the original HTTP request for network breadcrumbs
        if let request = hint.urlRequest {
            if request.url?.host == "internal-api.example.com" {
                return nil // Drop breadcrumbs for internal API calls
            }
        }

        return breadcrumb
    }
}

@import Sentry;

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.beforeBreadcrumbWithHint = ^SentryBreadcrumb * _Nullable(SentryBreadcrumb * _Nonnull breadcrumb, SentryHint * _Nonnull hint) {
        // Access the original HTTP request for network breadcrumbs
        NSURLRequest *request = hint.urlRequest;
        if ([request.URL.host isEqualToString:@"internal-api.example.com"]) {
            return nil; // Drop breadcrumbs for internal API calls
        }

        return breadcrumb;
    };
}];

#import <SentryObjC/SentryObjC.h>

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.beforeBreadcrumbWithHint = ^SentryObjCBreadcrumb * _Nullable(SentryObjCBreadcrumb * _Nonnull breadcrumb, SentryObjCHint * _Nonnull hint) {
        // Access the original HTTP request for network breadcrumbs
        NSURLRequest *request = hint.urlRequest;
        if ([request.URL.host isEqualToString:@"internal-api.example.com"]) {
            return nil; // Drop breadcrumbs for internal API calls
        }

        return breadcrumb;
    };
}];

You can store arbitrary key-value data on a hint using setHintValue(_:forKey:) and hintValue(forKey:). This is useful when passing hints through the capture methods:

Copied

let hint = Hint()
hint.setHintValue("custom-data", forKey: "myKey")

SentrySDK.capture(event: event, hint: hint)

let hint = Hint()
hint.setHintValue("custom-data", forKey: "myKey")

SentrySDK.capture(event: event, hint: hint)

SentryHint *hint = [[SentryHint alloc] init];
[hint setHintValue:@"custom-data" forKey:@"myKey"];

[SentrySDK captureEvent:event withScope:SentrySDK.currentHub.scope hint:hint];

All public capture methods on SentrySDK accept an optional hint parameter. The hint is passed through to beforeSendWithHint, allowing you to forward contextual information from the capture site to the callback:

Copied

import Sentry

// Capture an error with a hint
let hint = Hint(error: myError)
hint.setHintValue("checkout-flow", forKey: "source")
SentrySDK.capture(error: myError, hint: hint)

// Capture an event with a hint
SentrySDK.capture(event: event, hint: hint)

// Capture an exception with a hint
SentrySDK.capture(exception: myException, hint: Hint(exception: myException))

import Sentry

// Capture an error with a hint
let hint = Hint(error: myError)
hint.setHintValue("checkout-flow", forKey: "source")
SentrySDK.capture(error: myError, hint: hint)

// Capture an event with a hint
SentrySDK.capture(event: event, hint: hint)

// Capture an exception with a hint
SentrySDK.capture(exception: myException, hint: Hint(exception: myException))

@import Sentry;

// Capture an error with a hint
SentryHint *hint = [[SentryHint alloc] initWithError:myError];
[hint setHintValue:@"checkout-flow" forKey:@"source"];
[SentrySDK captureError:myError withScope:SentrySDK.currentHub.scope hint:hint];

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. This API is available from Cocoa SDK version 8.30.0 and above.

Copied

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.beforeSendSpan = { span in
        // Modify or drop the span here
        if (span.description == "unimportant span") {
            // Don't send the span to Sentry
            return nil
        }
        return span
    }
}

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.beforeSendSpan = { span in
        // Modify or drop the span here
        if (span.description == "unimportant span") {
            // Don't send the span to Sentry
            return nil
        }
        return span
    }
}

@import Sentry;

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.beforeSendSpan = ^id<SentrySpan> _Nullable (id<SentrySpan> _Nonnull span) {
        // Modify or drop the span here
        if ([span.description isEqualToString:@"unimportant span"]) {
            // Don't send the span to Sentry
            return nil;
        }
        return span;
    };
}];

#import <SentryObjC/SentryObjC.h>

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.beforeSendSpan = ^id<SentryObjCSpan> _Nullable (id<SentryObjCSpan> _Nonnull span) {
        // Modify or drop the span here
        if ([span.description isEqualToString:@"unimportant span"]) {
            // Don't send the span to Sentry
            return nil;
        }
        return span;
    };
}];

Was this helpful?

Help improve this content
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").

How to contribute | Edit this page | Create a docs issue | Get support