Skip to content

native-options.mdx

Latest commit

 

History

History
235 lines (128 loc) · 8.69 KB

native-options.mdx

File metadata and controls

235 lines (128 loc) · 8.69 KB
title Apple Native Options
description Configure the embedded Sentry Cocoa SDK when using .NET for iOS, macOS, or Mac Catalyst.
sidebar_order 10

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.

Screenshots

Automatically attaches a screenshot when the native Cocoa SDK captures an exception. Disabled by default.

See Attach Screenshot.

App Hangs

Detects App Hangs, which are periods where the main thread is unresponsive for longer than AppHangTimeoutInterval. Disabled by default.

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.

Breadcrumbs

Automatically adds breadcrumbs for various system events (network changes, low memory warnings, etc.). Enabled by default.

See Automatic Breadcrumbs.

Performance

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

See Automatic Instrumentation.

Tracks performance of Core Data operations. Requires performance monitoring to be enabled.

See Core Data Tracing.

Tracks performance of file IO reads and writes via NSData. Requires EnableAutoPerformanceTracing and EnableSwizzling to be enabled.

See File I/O Tracing.

Tracks performance of HTTP requests and adds breadcrumbs for network activity. Requires EnableAutoPerformanceTracing and EnableSwizzling to be enabled.

See Network Tracking.

Adds breadcrumbs for each network request. Requires EnableAutoPerformanceTracing and EnableSwizzling to be enabled.

Automatically creates transactions for UIViewController subclasses.

See UIViewController Tracing.

Creates transactions for UI events such as button taps and switch toggles. Disabled by default.

See User Interaction Tracing.

How long an idle transaction waits for new child spans after all existing spans finish. Only applies to UI event transactions.

Enables tracing features on the embedded Cocoa SDK directly. When disabled, the .NET SDK still handles traces for managed code.

Swizzling

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-trace header for distributed tracing

Profiling

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();
});

Error Handling

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.

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.

Networking

Sets a custom delegate on the NSURLSession used for data transfer by the native Cocoa SDK.

Stack Traces

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.

Includes frames matching the given iOS module prefix as "in-app" in stack traces.

options.Native.AddInAppInclude("MyApp");

See In-App Include.

Session Replay

Session Replay for Apple platforms is currently experimental and must be opted into.

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.

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.

Masks all text content in session replay recordings to protect user privacy. Enabled by default.

Masks all images in session replay recordings to protect user privacy. Enabled by default.

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.

Enables faster view rendering at the cost of some visual fidelity. Disabled by default.