---
title: "Filtering"
description: "Learn more about how to configure your Sentry Apple SDK to filter events reported to Sentry."
url: https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering/
---

# Filtering | Sentry for macOS

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](https://docs.sentry.io/concepts/data-management/filtering.md) 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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/).

## [Filtering Error Events](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#filtering-error-events)

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

### [Using `beforeSend`](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#using-before-send)

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.

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://<key>@o<orgId>.ingest.sentry.io/<projectId>"
    options.beforeSend = { event in
        // modify event here or return nil to discard the event
        return event
    }
}
```

*Other available variations of the above snippet: Objective-C, Objective-C (SentryObjC)*

Note also that breadcrumbs can be filtered, as discussed in [our Breadcrumbs documentation](https://docs.sentry.io/product/issues/issue-details/breadcrumbs.md).

#### [Event Hints](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#event-hints)

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:

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://<key>@o<orgId>.ingest.sentry.io/<projectId>"
    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
    }
}
```

*Other available variations of the above snippet: Objective-C, Objective-C (SentryObjC)*

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

### [Using Hints](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#using-hints)

Hints are available in two places:

1. `beforeSendWithHint` / `beforeBreadcrumbWithHint`
2. 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.

#### [Hints for Events](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#hints-for-events)

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

#### [Hints for Breadcrumbs](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#hints-for-breadcrumbs)

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.

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://<key>@o<orgId>.ingest.sentry.io/<projectId>"
    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
    }
}
```

*Other available variations of the above snippet: Objective-C, Objective-C (SentryObjC)*

#### [Custom Hint Values](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#custom-hint-values)

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:

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

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

*Other available variations of the above snippet: Objective-C*

#### [Passing Hints to Capture Methods](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#passing-hints-to-capture-methods)

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:

```swift
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))
```

*Other available variations of the above snippet: Objective-C*

## [Filtering Spans](https://docs.sentry.io/platforms/apple/guides/macos/configuration/filtering.md#filtering-spans)

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.

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://<key>@o<orgId>.ingest.sentry.io/<projectId>"
    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
    }
}
```

*Other available variations of the above snippet: Objective-C, Objective-C (SentryObjC)*