Apple Native Options
Configure the embedded Sentry Cocoa SDK when using .NET for iOS, macOS, or Mac Catalyst.
When you use the .NET for Apple platforms integration, Sentry embeds the Sentry Cocoa SDK to provide native crash reporting and other platform-specific features. The options.Native property exposes configuration for this embedded SDK.
SentrySdk.Init(options =>
{
options.Dsn = "___PUBLIC_DSN___";
// Native Cocoa SDK options:
options.Native.EnableAppHangTracking = true;
options.Native.AttachScreenshot = true;
});
These options are also available in MAUI when targeting iOS or Mac Catalyst.
Native.AttachScreenshot
| Type | bool |
|---|---|
| Default | false |
Automatically attaches a screenshot when the native Cocoa SDK captures an exception. Disabled by default.
See Attach Screenshot.
Native.EnableAppHangTracking
| Type | bool |
|---|---|
| Default | false |
Detects App Hangs, which are periods where the main thread is unresponsive for longer than AppHangTimeoutInterval. Disabled by default.
Native.AppHangTimeoutInterval
| Type | TimeSpan |
|---|---|
| Default | TimeSpan.FromSeconds(2) |
The minimum duration the main thread must be unresponsive before it's classified as an App Hang. Avoid values below 100ms, which may generate excessive events. Default is 2 seconds.
Requires EnableAppHangTracking to be true.
See App Hangs.
Native.EnableAutoBreadcrumbTracking
| Type | bool |
|---|---|
| Default | true |
Automatically adds breadcrumbs for various system events (network changes, low memory warnings, etc.). Enabled by default.
Native.EnableAutoPerformanceTracing
| Type | bool |
|---|---|
| Default | true |
Automatically tracks performance for UIViewController subclasses, HTTP requests, app start time, and slow/frozen frames. Enabled by default.
Requires performance monitoring to be configured (i.e. TracesSampleRate or TracesSampler).
Native.EnableCoreDataTracing
| Type | bool |
|---|---|
| Default | true |
Tracks performance of Core Data operations. Requires performance monitoring to be enabled.
See Core Data Tracing.
Native.EnableFileIOTracing
| Type | bool |
|---|---|
| Default | true |
Tracks performance of file IO reads and writes via NSData. Requires EnableAutoPerformanceTracing and EnableSwizzling to be enabled.
See File I/O Tracing.
Native.EnableNetworkTracking
| Type | bool |
|---|---|
| Default | true |
Tracks performance of HTTP requests and adds breadcrumbs for network activity. Requires EnableAutoPerformanceTracing and EnableSwizzling to be enabled.
See Network Tracking.
Native.EnableNetworkBreadcrumbs
| Type | bool |
|---|---|
| Default | true |
Adds breadcrumbs for each network request. Requires EnableAutoPerformanceTracing and EnableSwizzling to be enabled.
Native.EnableUIViewControllerTracing
| Type | bool |
|---|---|
| Default | true |
Automatically creates transactions for UIViewController subclasses.
Native.EnableUserInteractionTracing
| Type | bool |
|---|---|
| Default | false |
Creates transactions for UI events such as button taps and switch toggles. Disabled by default.
Native.IdleTimeout
| Type | TimeSpan |
|---|---|
| Default | TimeSpan.FromSeconds(3) |
How long an idle transaction waits for new child spans after all existing spans finish. Only applies to UI event transactions.
Native.EnableTracing
| Type | bool |
|---|---|
| Default | false |
Enables tracing features on the embedded Cocoa SDK directly. When disabled, the .NET SDK still handles traces for managed code.
Native.EnableSwizzling
| Type | bool |
|---|---|
| Default | true |
Controls whether the SDK uses method swizzling to instrument the app automatically. When disabled, the following features are also disabled:
- Breadcrumbs for touch events and navigation
- Automatic instrumentation for
UIViewController, HTTP requests, and file IO - Automatic injection of the
sentry-traceheader for distributed tracing
Call AddProfilingIntegration() on SentryOptions.Native to enable native profiling on Apple platforms. This is automatically added by the SDK, but you can call it explicitly if needed.
SentrySdk.Init(options =>
{
options.Dsn = "___PUBLIC_DSN___";
options.Native.AddProfilingIntegration();
});
Native.SuppressSignalAborts
| Type | bool |
|---|---|
| Default | false |
Suppresses native SIGABRT errors from being captured by the Cocoa SDK.
When managed code results in a NullReferenceException, this also causes a SIGABRT. Without suppression, Sentry may capture duplicate events — one from managed code and one from the native SDK. Enabling this option prevents the native duplicate, but also suppresses genuine native SIGABRT crashes.
Native.SuppressExcBadAccess
| Type | bool |
|---|---|
| Default | false |
Suppresses native EXC_BAD_ACCESS errors from being captured by the Cocoa SDK.
NullReferenceException in managed code also triggers EXC_BAD_ACCESS. Enabling this option prevents native duplicates but may also suppress genuine native memory access errors.
Native.UrlSessionDelegate
| Type | NSUrlSessionDelegate? |
|---|---|
| Default | null |
Sets a custom delegate on the NSURLSession used for data transfer by the native Cocoa SDK.
Use this method to control which iOS modules are considered "in-app" in stack traces. Note that this uses iOS module names, not .NET namespaces.
Native.AddInAppInclude(prefix)
| Type | method |
|---|
Includes frames matching the given iOS module prefix as "in-app" in stack traces.
options.Native.AddInAppInclude("MyApp");
See In-App Include.
Session Replay for Apple platforms is currently experimental and must be opted into.
Native.ExperimentalOptions.SessionReplay.SessionSampleRate
| Type | double? |
|---|---|
| Default | null |
Sample rate for all sessions, between 0.0 and 1.0. Set to 0.0 or leave as null to disable session replay for regular sessions.
Native.ExperimentalOptions.SessionReplay.OnErrorSampleRate
| Type | double? |
|---|---|
| Default | null |
Sample rate for buffered replays that are triggered when an error occurs. The SDK keeps the previous minute of activity and continues until the session ends when an error is sampled.
Native.ExperimentalOptions.SessionReplay.MaskAllText
| Type | bool |
|---|---|
| Default | true |
Masks all text content in session replay recordings to protect user privacy. Enabled by default.
Native.ExperimentalOptions.SessionReplay.MaskAllImages
| Type | bool |
|---|---|
| Default | true |
Masks all images in session replay recordings to protect user privacy. Enabled by default.
Native.ExperimentalOptions.SessionReplay.EnableViewRendererV2
| Type | bool |
|---|---|
| Default | true |
Captures session replay on a background thread to avoid interfering with the main thread and reduce potential frame drops. This is a recommended setting; disable only if you encounter specific issues.
Native.ExperimentalOptions.SessionReplay.EnableFastViewRendering
| Type | bool |
|---|---|
| Default | false |
Enables faster view rendering at the cost of some visual fidelity. Disabled by default.
Native.ExperimentalOptions.SessionReplay.EnableSessionReplayInUnreliableEnvironment
| Type | bool |
|---|---|
| Default | false |
Due to potential masking issues, session replay is disabled on iOS 26+ with Liquid Glass. If you understand these issues and want to force Session Replay to be enabled anyway, you can use this setting to enable it.
Enabling this option on iOS 26+ may result in PII (text and images) not being masked as expected.
See sentry-cocoa#6389 for details.
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").