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