---
title: "Options"
description: "Learn more about how the Sentry Unity SDK can be configured via options. These are being passed to the init function and therefore set when the SDK is first initialized."
url: https://docs.sentry.io/platforms/unity/configuration/options/
---

# Options for Unity

## [Programmatic Configuration](https://docs.sentry.io/platforms/unity/configuration/options.md#programmatic-configuration)

The SDK provides a configuration window that allows you to set most of Sentry's options directly in the Unity Editor. Some options, like the `BeforeSend` callback, can only be set programmatically. Take a look at our documentation about [how to configure the SDK programmatically](https://docs.sentry.io/platforms/unity/configuration/options/programmatic-configuration.md) for more information.

## [Core Options](https://docs.sentry.io/platforms/unity/configuration/options.md#core-options)



### [Dsn](https://docs.sentry.io/platforms/unity/configuration/options.md#Dsn)

| Type | `string` |
| ---- | -------- |

The DSN tells the SDK where to send the events. Without a DSN, the SDK is disabled and doesn't send any events. The SDK doesn't read the DSN from the environment variable.

Learn more about [DSN utilization](https://docs.sentry.io/concepts/key-terms/dsn-explainer.md#dsn-utilization).

### [Environment](https://docs.sentry.io/platforms/unity/configuration/options.md#Environment)

| Type    | `string`     |
| ------- | ------------ |
| Default | `production` |

Sets the environment. This string is freeform and set by default. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `prod` or similar).

By default, the SDK reports `editor` when running inside the Unity Editor. Otherwise, the default environment is `production`.

### [Release](https://docs.sentry.io/platforms/unity/configuration/options.md#Release)

| Type | `string` |
| ---- | -------- |

Sets the release. The SDK will try to automatically configure a release out of the box. Release names are strings, but some formats are detected by Sentry and might be rendered differently. Learn more about how to send release data so Sentry can tell you about regressions between releases and identify the potential source in [the releases documentation](https://docs.sentry.io/product/releases.md) or the [sandbox](https://sandbox.sentry.io/?scenario=releases\&source=docs).

By default, the SDK creates the release from `Application.productName` and `Application.version`, in the format `{productName}@{version}`. In the product name, line breaks, tabs, `/`, `\`, `..` and `@` are each replaced with `_`. If the product name is empty, only whitespace, or only dots, the release is just `Application.version`.

### [Debug](https://docs.sentry.io/platforms/unity/configuration/options.md#Debug)

| Type    | `bool`                                      |
| ------- | ------------------------------------------- |
| Default | `true` (false with a manual SentrySdk.Init) |

Turns debug mode on or off. If debug is enabled, the SDK prints useful debugging information if something goes wrong with sending the event. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns.

In the editor window, **Enable Debug Output** is on and **Only In Editor** is checked, so the SDK prints its diagnostic logs in the Editor but not in builds. Uncheck **Only In Editor** to get them in builds too.

### [DiagnosticLevel](https://docs.sentry.io/platforms/unity/configuration/options.md#DiagnosticLevel)

| Type    | `SentryLevel`                                                          |
| ------- | ---------------------------------------------------------------------- |
| Default | `SentryLevel.Warning` (SentryLevel.Debug with a manual SentrySdk.Init) |

Sets the minimum level of the SDK's diagnostic logs when `debug` mode is on. In the editor window, this is **Verbosity Level**.

* `SentryLevel.Debug`: The most verbose mode
* `SentryLevel.Info`: Informational messages
* `SentryLevel.Warning`: Warning that something might not be right
* `SentryLevel.Error`: Only SDK internal errors are printed
* `SentryLevel.Fatal`: Only critical errors are printed

To write the logs somewhere else, such as a file, [customize the SDK's diagnostic logger](https://docs.sentry.io/platforms/unity/configuration/diagnostic-logger.md).

### [Enabled](https://docs.sentry.io/platforms/unity/configuration/options.md#Enabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns the SDK on or off. When set to `false`, the SDK doesn't initialize.

### [CaptureInEditor](https://docs.sentry.io/platforms/unity/configuration/options.md#CaptureInEditor)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Controls whether the SDK initializes while the game runs in the Unity Editor. When set to `false`, the SDK sends nothing from Play Mode.

### [DiagnosticLogger](https://docs.sentry.io/platforms/unity/configuration/options.md#DiagnosticLogger)

| Type | `IDiagnosticLogger` |
| ---- | ------------------- |

Sets the logger for the SDK's own diagnostic messages. The SDK uses it only when `Debug` is on. If you don't set one, the SDK writes to the Unity Console. There's no field for it in the configuration window. Learn more in [Diagnostic Logger](https://docs.sentry.io/platforms/unity/configuration/diagnostic-logger.md).

## [Filtering Options](https://docs.sentry.io/platforms/unity/configuration/options.md#filtering-options)

### [SampleRate](https://docs.sentry.io/platforms/unity/configuration/options.md#SampleRate)

| Type    | `float?` |
| ------- | -------- |
| Default | `null`   |

The sample rate for error events, greater than `0` and up to `1`. When `null`, the SDK sends every error event. In the configuration window, it's the **Event Sample Rate** field, which accepts `0.01` to `1`, where `1` means `null`. Native crashes on Android, iOS, and macOS with the Cocoa backend follow this rate too. On Windows, Linux, macOS with the Native backend, and game consoles, the native SDK always sends crashes. Learn more in [Sampling](https://docs.sentry.io/platforms/unity/configuration/sampling.md).

### [Throttler](https://docs.sentry.io/platforms/unity/configuration/options.md#Throttler)

| Type    | `IThrottler` |
| ------- | ------------ |
| Default | `null`       |

Limits repeated errors, breadcrumbs, and structured logs that come from Unity logging. Turning on **Enable Error Event Throttling** in the configuration window sets a throttler that only limits error events, unless your options configuration script already set one. Implement `IThrottler` to also limit breadcrumbs and structured logs.

### [FilterBadGatewayExceptions](https://docs.sentry.io/platforms/unity/configuration/options.md#FilterBadGatewayExceptions)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Drops exceptions of type `System.Exception` whose message starts with `Error: HTTP/1.1 502 Bad Gateway`.

Set it to `false` to keep these exceptions. This works in the window, in `Configure`, and when you initialize the SDK with `SentrySdk.Init`.

On iOS with `BuildTime` native initialization, this option also makes the iOS SDK drop events for requests to `operate-sdk-telemetry.unity3d.com`. The iOS SDK takes this value from the window and `Configure` at build time, so setting it in `SentrySdk.Init` doesn't change it.

### [DisableBadGatewayExceptionFilter](https://docs.sentry.io/platforms/unity/configuration/options.md#DisableBadGatewayExceptionFilter)

| Type | `method` |
| ---- | -------- |

Removes the filter that drops Bad Gateway exceptions. It leaves `FilterBadGatewayExceptions` set to `true`, so on iOS with `BuildTime` native initialization, the iOS SDK still drops events for requests to `operate-sdk-telemetry.unity3d.com`. To turn off both, set `FilterBadGatewayExceptions` to `false` in the window or in `Configure` instead.

### [DisableWebExceptionFilter](https://docs.sentry.io/platforms/unity/configuration/options.md#DisableWebExceptionFilter)

| Type | `method` |
| ---- | -------- |

Removes the filter that drops `System.Net.WebException` with the message `Error: ConnectFailure (The requested address is not valid in this context)`. In the configuration window, it's the **WebException** toggle.

### [DisableSocketExceptionFilter](https://docs.sentry.io/platforms/unity/configuration/options.md#DisableSocketExceptionFilter)

| Type | `method` |
| ---- | -------- |

Removes the filter that drops `System.Net.Sockets.SocketException` with error code 10049 (`The requested address is not valid in this context`). In the configuration window, it's the **SocketException** toggle.

### [AddExceptionFilter](https://docs.sentry.io/platforms/unity/configuration/options.md#AddExceptionFilter)

| Type | `method` |
| ---- | -------- |

Adds an `IExceptionFilter`. The SDK drops exceptions for which the filter returns `true`. To drop an exception type and the types derived from it, call `AddExceptionFilterForType<TException>()`.

### [DeduplicateMode](https://docs.sentry.io/platforms/unity/configuration/options.md#DeduplicateMode)

| Type    | `DeduplicateMode`      |
| ------- | ---------------------- |
| Default | `All ^ InnerException` |

Controls which duplicate events the SDK drops: the same event (`SameEvent`), the same exception instance (`SameExceptionInstance`), an already captured exception that's the inner exception of a new one (`InnerException`), or part of an `AggregateException` (`AggregateException`). By default, the SDK drops all of these except inner exceptions. There's no field for it in the configuration window.

## [Logging & Breadcrumbs Options](https://docs.sentry.io/platforms/unity/configuration/options.md#logging--breadcrumbs-options)

### [AddBreadcrumbsForLogType](https://docs.sentry.io/platforms/unity/configuration/options.md#AddBreadcrumbsForLogType)

| Type    | `Dictionary<LogType, bool>`                  |
| ------- | -------------------------------------------- |
| Default | `true` (for Log, Warning, Assert, and Error) |

Controls, for each Unity `LogType`, whether the SDK adds log messages as breadcrumbs. In the configuration window, these are the breadcrumb toggles on the **Logging** tab. Learn more in [Breadcrumbs](https://docs.sentry.io/platforms/unity/enriching-events/breadcrumbs.md).

### [DisableUnityLoggingIntegration](https://docs.sentry.io/platforms/unity/configuration/options.md#DisableUnityLoggingIntegration)

| Type | `method` |
| ---- | -------- |

Stops the SDK from capturing `Debug.Log`, `Debug.LogWarning`, `Debug.LogAssertion`, and `Debug.LogError` calls as events, breadcrumbs, and structured logs.

### [DisableUnhandledExceptionCapture](https://docs.sentry.io/platforms/unity/configuration/options.md#DisableUnhandledExceptionCapture)

| Type | `method` |
| ---- | -------- |

Stops the SDK from capturing exceptions that reach Unity's log handler: uncaught exceptions and `Debug.LogException` calls. The .NET `AppDomain` and unobserved-task handlers keep capturing; turn them off with `DisableAppDomainUnhandledExceptionCapture()` and `DisableUnobservedTaskExceptionCapture()`.

## [Data Enrichment & Attachments](https://docs.sentry.io/platforms/unity/configuration/options.md#data-enrichment--attachments)

### [AddInAppInclude](https://docs.sentry.io/platforms/unity/configuration/options.md#AddInAppInclude)

| Type | `function` |
| ---- | ---------- |

Adds a prefix of module names that belong to the app. Call `options.AddInAppInclude("MyCompany.")` with a string prefix, or pass a `Regex`, or use `options.AddInAppIncludeRegex(pattern)`. Includes take precedence over excludes.

Sentry differentiates stack frames that are directly related to your game ("in application") from stack frames that come from other packages such as the standard library, third party plugins, or other dependencies. The game's code that is part of the 'Assembly-CSharp' is automatically marked as `inApp`. The difference is visible in [sentry.io](https://sentry.io), where only the "in application" frames are displayed by default.

### [AddInAppExclude](https://docs.sentry.io/platforms/unity/configuration/options.md#AddInAppExclude)

| Type | `function` |
| ---- | ---------- |

Adds a prefix of module names that don't belong to the app, but to third-party packages. Call `options.AddInAppExclude("ThirdParty.")` with a string prefix, or pass a `Regex`, or use `options.AddInAppExcludeRegex(pattern)`. Modules considered not part of the app will be hidden from stack traces by default.

The Unity SDK excludes `UnityEngine`, `UnityEditor`, `Cysharp` and `DG.Tweening` by default. Use `AddInAppInclude` to override an exclude.

### [MaxBreadcrumbs](https://docs.sentry.io/platforms/unity/configuration/options.md#MaxBreadcrumbs)

| Type    | `int` |
| ------- | ----- |
| Default | `100` |

This variable controls the total amount of breadcrumbs that should be captured. This defaults to `100`, but you can set this to any number. However, you should be aware that Sentry has a [maximum payload size](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) and any events exceeding that payload size will be dropped.

### [AttachStacktrace](https://docs.sentry.io/platforms/unity/configuration/options.md#AttachStacktrace)

| Type    | `bool`                                      |
| ------- | ------------------------------------------- |
| Default | `false` (true with a manual SentrySdk.Init) |

When enabled, stack traces are automatically attached to all messages logged. Stack traces are always attached to exceptions; however, when this option is set, stack traces are also sent with messages. This option, for instance, means that stack traces appear next to all log messages.

Grouping in Sentry is different for events with stack traces and without. As a result, you will get new groups as you enable or disable this flag for certain events.

### [AttachScreenshot](https://docs.sentry.io/platforms/unity/configuration/options.md#AttachScreenshot)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Attaches a screenshot of the game to events, such as errors and messages, and sends it in the same envelope as the event. Screenshots aren't attached in the Editor, in batch mode, or on WebGL. On iOS and Windows, native crashes also get a screenshot, taken by the native SDK. Learn more about enriching events with screenshots in our [Screenshots documentation](https://docs.sentry.io/platforms/unity/enriching-events/screenshots.md).

### [ScreenshotQuality](https://docs.sentry.io/platforms/unity/configuration/options.md#ScreenshotQuality)

| Type    | `enum` |
| ------- | ------ |
| Default | `high` |

The resolution of the attached screenshot. `Full` keeps the game's resolution, while `High`, `Medium`, and `Low` scale it down so that its longest side is at most 1920, 1280, or 854 pixels.

### [ScreenshotCompression](https://docs.sentry.io/platforms/unity/configuration/options.md#ScreenshotCompression)

| Type    | `int` |
| ------- | ----- |
| Default | `75`  |

The JPEG quality of the attached screenshot, from 1 to 100. Higher values result in better quality and larger files.

### [AttachViewHierarchy](https://docs.sentry.io/platforms/unity/configuration/options.md#AttachViewHierarchy)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Captures the currently active scene's hierarchy and creates a `ViewHierarchy` when an error happens and includes it as an attachment. The creation is influenced by `MaxViewHierarchyRootObjects`, `MaxViewHierarchyDepth`, and `MaxViewHierarchyObjectChildCount`.

### [SendClientReports](https://docs.sentry.io/platforms/unity/configuration/options.md#SendClientReports)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Set this boolean to `false` to disable sending of client reports. Client reports are a protocol feature that let clients send status reports about themselves to Sentry. They are currently mainly used to emit outcomes for events that were never sent.

### [CaptureFailedRequests](https://docs.sentry.io/platforms/unity/configuration/options.md#CaptureFailedRequests)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry.

It applies to requests sent with an `HttpClient` that uses `SentryHttpMessageHandler`, for example `new HttpClient(new SentryHttpMessageHandler())`. Requests sent with `UnityWebRequest` aren't captured. On iOS and macOS, the option is also passed to the native Cocoa SDK, unless the app initializes that SDK itself. The status codes that count as failed are set by `FailedRequestStatusCodes`, which defaults to 500–599. Both options can only be set in code.

### [FailedRequestStatusCodes](https://docs.sentry.io/platforms/unity/configuration/options.md#FailedRequestStatusCodes)

| Type    | `IList<HttpStatusCodeRange>` |
| ------- | ---------------------------- |
| Default | `500-599`                    |

The response status codes that count as failed requests for `CaptureFailedRequests`. There's no field for it in the configuration window.

### [FailedRequestTargets](https://docs.sentry.io/platforms/unity/configuration/options.md#FailedRequestTargets)

| Type    | `IList<StringOrRegex>` |
| ------- | ---------------------- |
| Default | `.*`                   |

The request URLs that `CaptureFailedRequests` applies to, as substrings or regular expressions. Adding an item removes the default `.*`. There's no field for it in the configuration window.

### [IsGlobalModeEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#IsGlobalModeEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Defaults to `true`. Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications.

### [Distribution](https://docs.sentry.io/platforms/unity/configuration/options.md#Distribution)

| Type | `string` |
| ---- | -------- |

Sets the distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. The dist has a max length of 64 characters.

### [ReportAssembliesMode](https://docs.sentry.io/platforms/unity/configuration/options.md#ReportAssembliesMode)

| Type    | `ReportAssembliesMode` |
| ------- | ---------------------- |
| Default | `Version`              |

Controls whether events list the loaded assemblies, and which version they report: `None`, `Version`, or `InformationalVersion`. If an assembly has no informational version, `InformationalVersion` reports the assembly version.

### [DefaultTags](https://docs.sentry.io/platforms/unity/configuration/options.md#DefaultTags)

| Type | `Dictionary<string, string>` |
| ---- | ---------------------------- |

Tags the SDK adds to every event. If an event already has a tag with the same key, it keeps its own value. Add tags to the dictionary, for example `options.DefaultTags["level"] = "forest";`. There's no field for it in the configuration window. Learn more in [Tags](https://docs.sentry.io/platforms/unity/enriching-events/tags.md).

### [TagFilters](https://docs.sentry.io/platforms/unity/configuration/options.md#TagFilters)

| Type | `IList<StringOrRegex>` |
| ---- | ---------------------- |

Tag keys the SDK ignores, as substrings or regular expressions. Setting a tag whose key matches has no effect. There's no field for it in the configuration window.

## [Privacy & PII](https://docs.sentry.io/platforms/unity/configuration/options.md#privacy--pii)

### [SendDefaultPii](https://docs.sentry.io/platforms/unity/configuration/options.md#SendDefaultPii)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent.

In Unity, it adds the device name (`device.name`) and the device's unique identifier to events. Native crashes on Windows, Linux, macOS with the Native backend, and game consoles carry the device name only with this option, too. Native crashes on iOS, Android, and macOS with the Cocoa backend don't include the device name. With `IsEnvironmentUser`, it also adds the user name. Learn more in [Data Collected](https://docs.sentry.io/platforms/unity/data-management/data-collected.md).

If you are using Sentry in your mobile app, read our [frequently asked questions about mobile data privacy](https://docs.sentry.io/security-legal-pii/security/mobile-privacy.md) to assist with Apple App Store and Google Play app privacy details.

This option is turned off by default.

If you enable this option, be sure to manually remove what you don't want to send using our features for managing [*Sensitive Data*](https://docs.sentry.io/platforms/unity/data-management/sensitive-data.md).

### [IsEnvironmentUser](https://docs.sentry.io/platforms/unity/configuration/options.md#IsEnvironmentUser)

| Type    | `bool`                                |
| ------- | ------------------------------------- |
| Default | `false` (in the configuration window) |

Reports `Environment.UserName` as the user of each event. It applies only when `SendDefaultPii` is on and the event has no user set.

The default depends on where the options come from:

* Configuration window (**Auto Set UserName**): `false`. An options configuration script sees the window's value.
* `new SentryUnityOptions()` and `SentrySdk.Init`: `true` in Windows, macOS, and Linux players and dedicated servers, and `false` everywhere else, including the Unity Editor, Android, iOS, and consoles.

## [Hooks](https://docs.sentry.io/platforms/unity/configuration/options.md#hooks)

These options can be used to hook the SDK in various ways to customize the reporting of events.

The callbacks you set as hooks will be called on the thread where the event happened. So you can only use thread-safe APIs and only use Unity-specific APIs after you've checked that you're on the UI thread.

### [SetBeforeSend](https://docs.sentry.io/platforms/unity/configuration/options.md#SetBeforeSend)

| Type | `function` |
| ---- | ---------- |

This function is called with an SDK-specific message or error event object, and can return a modified event object, or `null` to skip reporting the event. This can be used, for instance, for manual PII stripping before sending.

By the time `SetBeforeSend` is executed, all scope data has already been applied to the event. Further modification of the scope won't have any effect.

### [SetBeforeBreadcrumb](https://docs.sentry.io/platforms/unity/configuration/options.md#SetBeforeBreadcrumb)

| Type | `function` |
| ---- | ---------- |

This function is called with an SDK-specific breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object. The callback typically gets a second argument (called a "hint") which contains the original object from which the breadcrumb was created to further customize what the breadcrumb should look like.

### [SetBeforeSendTransaction](https://docs.sentry.io/platforms/unity/configuration/options.md#SetBeforeSendTransaction)

| Type | `function` |
| ---- | ---------- |

This function is called with an SDK-specific transaction object, and can return a modified transaction object, or `null` to skip reporting the transaction. This can be used, for instance, for manual PII-stripping before sending.

By the time `SetBeforeSendTransaction` is executed, all scope data has already been applied to the event and further modification of the scope won't have any effect.

### [SetBeforeCaptureScreenshot](https://docs.sentry.io/platforms/unity/configuration/options.md#SetBeforeCaptureScreenshot)

| Type | `function` |
| ---- | ---------- |

A callback function that controls screenshot capture behavior. Return `false` to prevent a screenshot from being attached to a specific event. It can run on a background thread and runs before `SetBeforeSend` and sampling. Setting it turns off screenshots for native crashes on iOS, as it can't run during a crash. Learn more in our [Screenshots documentation](https://docs.sentry.io/platforms/unity/enriching-events/screenshots.md).

### [SetBeforeSendScreenshot](https://docs.sentry.io/platforms/unity/configuration/options.md#SetBeforeSendScreenshot)

| Type | `function` |
| ---- | ---------- |

A callback function that receives the screenshot as a `Texture2D` before it gets compressed, along with the event it belongs to. Modify or replace the texture and return it, or return `null` to discard the screenshot. Setting it makes the SDK read and compress screenshots on the main thread, and turns off screenshots for native crashes on iOS, as it can't run during a crash. Learn more in our [Screenshots documentation](https://docs.sentry.io/platforms/unity/enriching-events/screenshots.md).

### [SetBeforeCaptureViewHierarchy](https://docs.sentry.io/platforms/unity/configuration/options.md#SetBeforeCaptureViewHierarchy)

| Type | `function` |
| ---- | ---------- |

A callback function that controls view hierarchy capture behavior. Return `false` to prevent the view hierarchy from being captured for a specific event. This allows for fine-grained control over when view hierarchies are included with error reports.

### [SetBeforeSendViewHierarchy](https://docs.sentry.io/platforms/unity/configuration/options.md#SetBeforeSendViewHierarchy)

| Type | `function` |
| ---- | ---------- |

A callback function that receives the captured view hierarchy before the SDK serializes it, along with the event it belongs to. Modify the hierarchy and return it, or return `null` to discard it. Learn more in [View Hierarchy](https://docs.sentry.io/platforms/unity/enriching-events/view-hierarchy.md).

### [SetBeforeSendFeedback](https://docs.sentry.io/platforms/unity/configuration/options.md#SetBeforeSendFeedback)

| Type | `function` |
| ---- | ---------- |

A callback function that receives user feedback before the SDK sends it. Return the feedback event, modified or not, or return `null` to drop it. Learn more in [User Feedback](https://docs.sentry.io/platforms/unity/user-feedback.md).

### [AddEventProcessor](https://docs.sentry.io/platforms/unity/configuration/options.md#AddEventProcessor)

| Type | `method` |
| ---- | -------- |

Adds an `ISentryEventProcessor` that runs for every event. A processor can change the event, or return `null` to drop it.

## [Transport & Network Options](https://docs.sentry.io/platforms/unity/configuration/options.md#transport--network-options)

Transports are used to send events to Sentry. Transports can be customized to some degree to better support highly specific deployments.

### [Transport](https://docs.sentry.io/platforms/unity/configuration/options.md#Transport)

| Type | `ITransport` |
| ---- | ------------ |

Switches out the transport used to send events. It can, for instance, be used to capture events for unit-testing or to send it through some more complex setup that requires proxy authentication. On WebGL and Nintendo Switch, this option has no effect: the SDK always sends events with `UnityWebRequest` there.

### [MaxCacheItems](https://docs.sentry.io/platforms/unity/configuration/options.md#MaxCacheItems)

| Type    | `int` |
| ------- | ----- |
| Default | `30`  |

The maximum number of [envelopes](https://develop.sentry.dev/sdk/data-model/envelopes/) to keep in cache. The SDKs use envelopes to send data, such as events, attachments, user feedback, and sessions to sentry.io. An envelope can contain multiple items, such as an event with a session and two attachments. Depending on the usage of the SDK, the size of an envelope can differ. If the number of envelopes in the local cache exceeds `max-cache-items`, the SDK deletes the oldest envelope and migrates the sessions to the next envelope to maintain the integrity of your release health stats. The default is `30`.

### [HttpProxy](https://docs.sentry.io/platforms/unity/configuration/options.md#HttpProxy)

| Type | `IWebProxy` |
| ---- | ----------- |

Sets the proxy the SDK uses to send events to Sentry, for both HTTP and HTTPS. On WebGL and Nintendo Switch, this option has no effect.

### [InitCacheFlushTimeout](https://docs.sentry.io/platforms/unity/configuration/options.md#InitCacheFlushTimeout)

| Type    | `TimeSpan`      |
| ------- | --------------- |
| Default | `TimeSpan.Zero` |

When caching is enabled (that is, `CacheDirectoryPath` is set), this option controls the timeout that limits how long the SDK will attempt to flush existing cache during initialization. Note that flushing the cache involves sending the payload to Sentry in a blocking operation. Setting this option to zero means that Sentry will **not** attempt to flush the cache during initialization, but instead will do so when the next payload is queued up.

The default is zero, so the SDK doesn't block during initialization to flush the cache.

### [ShutdownTimeout](https://docs.sentry.io/platforms/unity/configuration/options.md#ShutdownTimeout)

| Type    | `TimeSpan`                |
| ------- | ------------------------- |
| Default | `TimeSpan.FromSeconds(2)` |

Controls how long to wait before shutting down. Sentry SDKs send events from a background queue. This queue is given a certain amount of time to drain pending events. The default is two seconds. Setting this value too low may cause problems for sending events from command line applications. Setting the value too high will cause the application to block for a long time for users experiencing network connectivity problems.

### [CacheDirectoryPath](https://docs.sentry.io/platforms/unity/configuration/options.md#CacheDirectoryPath)

| Type    | `string`                                                               |
| ------- | ---------------------------------------------------------------------- |
| Default | `Application.persistentDataPath` (not set on Nintendo Switch and Xbox) |

The directory where the SDK stores events before it sends them, so they survive restarts and network outages. Set it to `null` to turn offline caching off. Turning off **Enable Offline Caching** in the configuration window sets it to `null`.

### [MaxQueueItems](https://docs.sentry.io/platforms/unity/configuration/options.md#MaxQueueItems)

| Type    | `int` |
| ------- | ----- |
| Default | `30`  |

The maximum number of events the SDK keeps in memory while it sends them. Set it to at least `1`.

### [FlushTimeout](https://docs.sentry.io/platforms/unity/configuration/options.md#FlushTimeout)

| Type    | `TimeSpan`                |
| ------- | ------------------------- |
| Default | `TimeSpan.FromSeconds(2)` |

How long `SentrySdk.Flush()` waits for queued events to be sent. There's no field for it in the configuration window.

### [RequestBodyCompressionLevel](https://docs.sentry.io/platforms/unity/configuration/options.md#RequestBodyCompressionLevel)

| Type    | `CompressionLevelWithAuto` |
| ------- | -------------------------- |
| Default | `NoCompression`            |

How the SDK compresses the requests it sends to Sentry: `NoCompression`, `Optimal`, `Fastest`, or `Auto`, which uses `NoCompression`. IL2CPP doesn't support `Optimal` and `Fastest`. There's no field for it in the configuration window.

### [EnableBackpressureHandling](https://docs.sentry.io/platforms/unity/configuration/options.md#EnableBackpressureHandling)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Lets the SDK lower the sample rate of events and transactions while the system is under load. There's no field for it in the configuration window.

## [Tracing Options](https://docs.sentry.io/platforms/unity/configuration/options.md#tracing-options)

### [TracesSampleRate](https://docs.sentry.io/platforms/unity/configuration/options.md#TracesSampleRate)

| Type    | `float` |
| ------- | ------- |
| Default | `0.0`   |

A number between `0` and `1`, controlling the percentage chance a given transaction will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. The automatic startup, scene-load and `Awake` instrumentation only runs when this is greater than `0`.

### [TracesSampler](https://docs.sentry.io/platforms/unity/configuration/options.md#TracesSampler)

| Type | `function` |
| ---- | ---------- |

A function responsible for determining the percentage chance a given transaction will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering transactions, by returning 0 for those that are unwanted. A `TracesSampler` on its own enables tracing for the transactions you create. The automatic instrumentation also needs `TracesSampleRate` to be greater than `0`.

### [AutoStartupTraces](https://docs.sentry.io/platforms/unity/configuration/options.md#AutoStartupTraces)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Controls whether the SDK will automatically trace the app's startup. Requires `TracesSampleRate` to be greater than `0`.

### [AutoSceneLoadTraces](https://docs.sentry.io/platforms/unity/configuration/options.md#AutoSceneLoadTraces)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Controls whether the SDK will automatically trace when loading scenes. Requires `TracesSampleRate` to be greater than `0`.

### [PerformanceAutoInstrumentationEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#PerformanceAutoInstrumentationEnabled)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Adds spans for `Awake` calls during startup and scene loading. In the configuration window, it's the **Spans for Awake Calls** toggle. The SDK reads this option only during the build, when it instruments the game's code, and only if `TracesSampleRate` is greater than `0`. Setting it at runtime has no effect. Learn more in [Automatic Instrumentation](https://docs.sentry.io/platforms/unity/tracing/instrumentation/automatic-instrumentation.md).

### [IgnoreTransactions](https://docs.sentry.io/platforms/unity/configuration/options.md#IgnoreTransactions)

| Type | `IList<StringOrRegex>` |
| ---- | ---------------------- |

Transaction names to drop, as substrings or regular expressions. The SDK drops matching transactions before `SetBeforeSendTransaction` runs. There's no field for it in the configuration window.

### [TracePropagationTargets](https://docs.sentry.io/platforms/unity/configuration/options.md#TracePropagationTargets)

| Type    | `IList<StringOrRegex>` |
| ------- | ---------------------- |
| Default | `.*`                   |

The outgoing HTTP requests that get the `sentry-trace` and `baggage` headers, matched by URL as substrings or regular expressions. It applies to requests sent through `SentryHttpMessageHandler`. Adding an item removes the default `.*`, and an empty list turns propagation off. There's no field for it in the configuration window. Learn more in [Trace Propagation](https://docs.sentry.io/platforms/unity/tracing/trace-propagation.md).

### [PropagateTraceparent](https://docs.sentry.io/platforms/unity/configuration/options.md#PropagateTraceparent)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Also sends the W3C `traceparent` header with requests that match `TracePropagationTargets`. There's no field for it in the configuration window.

### [StrictTraceContinuation](https://docs.sentry.io/platforms/unity/configuration/options.md#StrictTraceContinuation)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

When set to `true`, the SDK continues an incoming trace only if it has the same org ID as yours. Otherwise, it starts a new trace. When set to `false`, the SDK also continues incoming traces that have no org ID. A trace with a different org ID always starts a new trace. There's no field for it in the configuration window.

### [OrgId](https://docs.sentry.io/platforms/unity/configuration/options.md#OrgId)

| Type | `string` |
| ---- | -------- |

The org ID the SDK uses for trace propagation and `StrictTraceContinuation`. By default, the SDK reads it from the DSN. Set it when your DSN doesn't contain it, for example with self-hosted Sentry or a local Relay. There's no field for it in the configuration window.

## [App Hang and ANR Options](https://docs.sentry.io/platforms/unity/configuration/options.md#app-hang-and-anr-options)

Use these options to configure app hang and ANR detection. For supported platforms, detector behavior, and avoiding duplicate events, see [App Hangs and ANRs](https://docs.sentry.io/platforms/unity/app-hangs.md).

### [EnableAppHangTracking](https://docs.sentry.io/platforms/unity/configuration/options.md#EnableAppHangTracking)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Enables experimental app hang detection. When the main thread is unresponsive for longer than `AppHangTimeout`, the SDK captures an `AppHang` event with a native stack trace.

### [AppHangTimeout](https://docs.sentry.io/platforms/unity/configuration/options.md#AppHangTimeout)

| Type    | `TimeSpan`                |
| ------- | ------------------------- |
| Default | `TimeSpan.FromSeconds(5)` |

Sets how long the main thread must be unresponsive before the SDK captures an app hang. This timeout is also used by native app hang tracking. With sentry-native, keep it at 2 seconds or more, since the SDK sends a heartbeat once per second.

### [AnrDetectionEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#AnrDetectionEnabled)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

**Deprecated:** Use `EnableAppHangTracking` instead.

Controls the managed C# watchdog. You can only set it in the editor window, under **Advanced > Automatic Behaviour > C# Watchdog (Deprecated)**. Programmatic initialization doesn't add the watchdog.

### [AnrTimeout](https://docs.sentry.io/platforms/unity/configuration/options.md#AnrTimeout)

| Type    | `TimeSpan`                |
| ------- | ------------------------- |
| Default | `TimeSpan.FromSeconds(5)` |

**Deprecated:** Use `AppHangTimeout` instead.

Sets how long the Unity main thread must be unresponsive before the managed watchdog reports an ANR event.

### [AndroidNativeAnrEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#AndroidNativeAnrEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Enables Android JVM ANR detection. On Android 11 and later, the SDK reports ANRs recorded by the operating system when the app next starts. On earlier Android versions, it uses an in-process watchdog.

### [AndroidReportHistoricalAnrs](https://docs.sentry.io/platforms/unity/configuration/options.md#AndroidReportHistoricalAnrs)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Reports historical Android ANRs recorded by the operating system. This option requires `AndroidNativeAnrEnabled` and applies only when Android native initialization runs at runtime.

### [AndroidAttachAnrThreadDump](https://docs.sentry.io/platforms/unity/configuration/options.md#AndroidAttachAnrThreadDump)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Attaches the Android operating system's thread dump to ANR events. This option requires `AndroidNativeAnrEnabled`.

## [Native Support Options](https://docs.sentry.io/platforms/unity/configuration/options.md#native-support-options)

These options control the native SDKs that the Unity SDK includes. Learn more in [Native Support](https://docs.sentry.io/platforms/unity/native-support.md).

### [IosNativeSupportEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#IosNativeSupportEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns on native support on iOS through the [iOS SDK](https://docs.sentry.io/platforms/apple/guides/ios.md).

### [AndroidNativeSupportEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#AndroidNativeSupportEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns on native support on Android through the [Android SDK](https://docs.sentry.io/platforms/android.md). Android native support requires the IL2CPP scripting backend: with Mono, this option and the other Android options have no effect.

### [NdkIntegrationEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#NdkIntegrationEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns on the Android NDK integration, which captures native crashes in C and C++ code. Requires `AndroidNativeSupportEnabled`.

### [NdkScopeSyncEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#NdkScopeSyncEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Syncs the scope, such as breadcrumbs, tags, and the user, to the Android NDK layer, so native crashes include it. Requires `NdkIntegrationEnabled`.

### [WindowsNativeSupportEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#WindowsNativeSupportEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns on native support on Windows.

### [MacosNativeSupportEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#MacosNativeSupportEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns on native support on macOS.

### [LinuxNativeSupportEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#LinuxNativeSupportEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns on native support on Linux.

### [XboxNativeSupportEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#XboxNativeSupportEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns on native support on Xbox. Learn more in [Game Consoles](https://docs.sentry.io/platforms/unity/game-consoles.md).

### [PlayStationNativeSupportEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#PlayStationNativeSupportEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Turns on native support on PlayStation. Learn more in [Game Consoles](https://docs.sentry.io/platforms/unity/game-consoles.md).

### [SwitchNativeSupportEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#SwitchNativeSupportEnabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Syncs the scope to the native layer on Nintendo Switch and Switch 2. Learn more in [Game Consoles](https://docs.sentry.io/platforms/unity/game-consoles.md).

### [IosNativeInitializationType](https://docs.sentry.io/platforms/unity/configuration/options.md#IosNativeInitializationType)

| Type    | `NativeInitializationType` |
| ------- | -------------------------- |
| Default | `Runtime`                  |

When the iOS SDK initializes: `Runtime`, `BuildTime`, or `External`. `External` is experimental and is for [Unity as a Library](https://docs.sentry.io/platforms/unity/native-support/unity-as-a-library.md). The SDK reads it during the build to set up the Xcode project, so set it in an [options configuration script](https://docs.sentry.io/platforms/unity/configuration/options/programmatic-configuration.md), which also runs during the build.

### [AndroidNativeInitializationType](https://docs.sentry.io/platforms/unity/configuration/options.md#AndroidNativeInitializationType)

| Type    | `NativeInitializationType` |
| ------- | -------------------------- |
| Default | `Runtime`                  |

When the Android SDK initializes: `Runtime`, `BuildTime`, or `External`. `External` is experimental and is for [Unity as a Library](https://docs.sentry.io/platforms/unity/native-support/unity-as-a-library.md). The SDK reads it during the build to set up the Gradle project, so set it in an [options configuration script](https://docs.sentry.io/platforms/unity/configuration/options/programmatic-configuration.md), which also runs during the build.

### [IosWatchdogTerminationIntegrationEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#IosWatchdogTerminationIntegrationEnabled)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Turns on [watchdog termination tracking](https://docs.sentry.io/platforms/apple/guides/ios/configuration/watchdog-terminations.md) in the iOS SDK. There's no field for it in the configuration window.

### [AndroidTombstoneEnabled](https://docs.sentry.io/platforms/unity/configuration/options.md#AndroidTombstoneEnabled)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Reports native crashes that Android records as tombstones, which the Android SDK reads through `ApplicationExitInfo`. There's no field for it in the configuration window.

### [AndroidReportHistoricalTombstones](https://docs.sentry.io/platforms/unity/configuration/options.md#AndroidReportHistoricalTombstones)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Also reports tombstones that Android recorded in earlier runs. Requires `AndroidTombstoneEnabled`. There's no field for it in the configuration window.

### [PostGenerateGradleProjectCallbackOrder](https://docs.sentry.io/platforms/unity/configuration/options.md#PostGenerateGradleProjectCallbackOrder)

| Type    | `int` |
| ------- | ----- |
| Default | `1`   |

The `callbackOrder` of the build step in which the SDK changes the generated Gradle project. Change it if another `IPostGenerateGradleAndroidProject` step must run before or after the SDK's. There's no field for it in the configuration window.

### [NativeHandlerPath](https://docs.sentry.io/platforms/unity/configuration/options.md#NativeHandlerPath)

| Available since | `4.11.0` |
| --------------- | -------- |
| Type            | `string` |

The path to the out-of-process crash handler executable. By default, the SDK looks for it next to the player executable. It applies on Windows, Linux, and on macOS with the `Native` backend. There's no field for it in the configuration window.

### [Experimental.WindowsBackend](https://docs.sentry.io/platforms/unity/configuration/options.md#Experimental.WindowsBackend)

| Type    | `WindowsBackend` |
| ------- | ---------------- |
| Default | `Crashpad`       |

The native backend on Windows. `Crashpad` uses `crashpad_handler.exe`. `Native` is experimental and uses the out-of-process `sentry-crash.exe` handler, which uploads crashes right away.

### [Experimental.MacosBackend](https://docs.sentry.io/platforms/unity/configuration/options.md#Experimental.MacosBackend)

| Type    | `MacosBackend` |
| ------- | -------------- |
| Default | `Cocoa`        |

The native backend on macOS. `Cocoa` uses the [macOS SDK](https://docs.sentry.io/platforms/apple/guides/macos.md) and requires IL2CPP. `Native` is experimental and uses the [Native SDK](https://docs.sentry.io/platforms/native.md) with an out-of-process handler, which uploads crashes right away. It works with IL2CPP and Mono.

### [Experimental.LinuxBackend](https://docs.sentry.io/platforms/unity/configuration/options.md#Experimental.LinuxBackend)

| Type    | `LinuxBackend` |
| ------- | -------------- |
| Default | `Breakpad`     |

The native backend on Linux. `Breakpad` captures crashes in process and uploads them on the next launch. `Native` is experimental and uses the out-of-process `sentry-crash` handler, which uploads crashes right away.

When any of these backends is set to `Native`, the SDK raises `ShutdownTimeout` to at least 10 seconds, so the handler has time to upload before the player exits. When you initialize the SDK with `SentrySdk.Init`, set `ShutdownTimeout` yourself.

## [Metrics Options](https://docs.sentry.io/platforms/unity/configuration/options.md#metrics-options)

These options are experimental. They make the SDK collect game metrics and send them to Sentry. Learn more in [Metrics](https://docs.sentry.io/platforms/unity/metrics.md).

### [AutoFrameMetrics](https://docs.sentry.io/platforms/unity/configuration/options.md#AutoFrameMetrics)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Collects frame metrics, such as frame time, FPS, and CPU thread timings.

### [FrameMetricsInterval](https://docs.sentry.io/platforms/unity/configuration/options.md#FrameMetricsInterval)

| Type    | `TimeSpan`                |
| ------- | ------------------------- |
| Default | `TimeSpan.FromSeconds(1)` |

How often the SDK samples frame metrics. The minimum is one second.

### [AutoMemoryMetrics](https://docs.sentry.io/platforms/unity/configuration/options.md#AutoMemoryMetrics)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Collects memory usage.

### [MemoryMetricsInterval](https://docs.sentry.io/platforms/unity/configuration/options.md#MemoryMetricsInterval)

| Type    | `TimeSpan`                 |
| ------- | -------------------------- |
| Default | `TimeSpan.FromSeconds(60)` |

How often the SDK samples memory metrics. The minimum is one second.

### [AutoGcMetrics](https://docs.sentry.io/platforms/unity/configuration/options.md#AutoGcMetrics)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Collects garbage collection counts for each generation.

### [GcMetricsInterval](https://docs.sentry.io/platforms/unity/configuration/options.md#GcMetricsInterval)

| Type    | `TimeSpan`                 |
| ------- | -------------------------- |
| Default | `TimeSpan.FromSeconds(60)` |

How often the SDK samples garbage collection metrics. The minimum is one second.

### [AutoNetworkMetrics](https://docs.sentry.io/platforms/unity/configuration/options.md#AutoNetworkMetrics)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Collects multiplayer network metrics: the round-trip time on clients and the number of connected clients on the server. Requires the Netcode for GameObjects package.

### [NetworkMetricsInterval](https://docs.sentry.io/platforms/unity/configuration/options.md#NetworkMetricsInterval)

| Type    | `TimeSpan`                 |
| ------- | -------------------------- |
| Default | `TimeSpan.FromSeconds(10)` |

How often the SDK samples network metrics. The minimum is one second.

## Pages in this section

- [Programmatic Configuration](https://docs.sentry.io/platforms/unity/configuration/options/programmatic-configuration.md)
- [Sentry CLI Options](https://docs.sentry.io/platforms/unity/configuration/options/cli-options.md)
