Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/platforms/unreal/configuration/native-backend/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
title: Native Backend
sidebar_order: 12
description: "Learn how to use the experimental native crash backend as an alternative to Crashpad on Windows and Linux."
---

The Sentry Unreal SDK uses Crashpad as the default crash reporting backend on Windows and Linux. As an alternative, you can enable the experimental native backend, which uses a different crash handling architecture built into the sentry-native SDK.

<Alert level="warning">

The native backend is experimental and under active development. It may have incomplete features or unexpected behavior. It is currently not supported in the FAB version of the plugin.

</Alert>

<Alert>

This feature is supported on Windows and Linux only.

</Alert>

## Configuration

The native backend is disabled by default. To enable it, navigate to **Project Settings > Plugins > Sentry > General > Native** and toggle **Use native crash backend (Experimental)**.

Alternatively, add the following to your project's configuration file:

```ini {filename:DefaultEngine.ini}
[/Script/Sentry.SentrySettings]
UseNativeBackend=True
```

Changing this setting requires a rebuild of the project.

### Minidump Mode

Controls how much memory is captured in crash minidumps. You can adjust this in **Project Settings > Plugins > Sentry > General > Native > Minidump capture mode**.

Available modes:
- `StackOnly` - Capture only stack memory. Fastest and smallest, suitable for production environments with high crash volumes.
- `Smart` (default) - Capture stack and heap around the crash site. Balanced mode providing good crash analysis without excessive overhead.
- `Full` - Capture full process memory. Most comprehensive but slowest to generate and upload. Best for development or staging environments.

### Crash Reporting Mode

Controls how crash data is collected and sent to Sentry. You can adjust this in **Project Settings > Plugins > Sentry > General > Native > Crash reporting mode**.

Available modes:
- `Minidump` - Write and send a minidump for server-side symbolication. No client-side stack unwinding is performed.
- `NativeStackwalking` - Walk the stack client-side in the crash daemon and send a JSON event with stack traces. No minidump is generated, resulting in faster uploads and smaller payloads.
- `NativeStackwalkingWithMinidump` (default) - Perform client-side stack unwinding and also attach a minidump for deep debugging when needed.
16 changes: 15 additions & 1 deletion docs/platforms/unreal/configuration/options.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,20 @@ On Windows, capturing GPU crashes requires [modifying the Unreal Engine source c

</SdkOption>

<SdkOption name="UseNativeBackend" type="bool" defaultValue="false">

When enabled, the SDK uses the experimental native backend for crash reporting instead of the default Crashpad backend on Windows and Linux. This option requires a rebuild after changing.

See <PlatformLink to="/configuration/native-backend/">Native Backend</PlatformLink> for details and additional configuration options.

<Alert level="warning">

This feature is experimental and under active development. Supported on Windows and Linux only.

</Alert>

</SdkOption>

<SdkOption name="CrashpadWaitForUpload" type="bool" defaultValue="false">

When enabled, application shutdown is delayed until the upload of the crash report is complete. This is useful for deployment in `Docker` environment (Linux and Windows containers) where the life cycle of all processes is bound by the root process (typically the application being monitored).
Expand All @@ -161,7 +175,7 @@ This option is turned off by default.

<Alert>

This feature is supported only for Crashpad backend on Windows and Linux (default for the `github` plugin package).
This feature is supported only for Crashpad backend on Windows and Linux (default for the `github` plugin package). This option has no effect when <PlatformIdentifier name="UseNativeBackend" /> is enabled.

</Alert>

Expand Down
Loading