You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When an upload is marked as selective, Sentry only diffs the snapshots you uploaded. Any snapshot that exists in the base build but was not included in the upload is treated as unchanged (skipped) rather than removed.
62
-
63
-
### Detecting Removals and Renames in Selective Mode
64
-
65
-
By default, `--selective` cannot detect removals or renames because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset. To enable removal and rename detection, pass the full list of image file names from your test suite using one of:
66
-
67
-
-`--all-image-file-names <NAMES>` — a comma-separated list of all image file names.
68
-
-`--all-image-file-names-file <PATH>` — a path to a file (`.txt`, `.csv`, etc.) containing all image file names, one per line.
69
-
-`--all-image-file-names-as-regex <PATTERNS>` — a comma-separated list of regex patterns matching all image file names.
70
-
-`--all-image-file-names-as-regex-file <PATH>` — a path to a file containing regex patterns, one per line.
71
-
72
-
<Alertlevel="warning">
73
-
These four flags are mutually exclusive — you can only use one per upload.
With the image names or patterns provided, Sentry can tell apart three categories of missing images:
91
-
92
-
-**Skipped** — matched by the list/pattern but not uploaded (part of the test suite, just not run in this CI job).
93
-
-**Removed** — not matched and not uploaded (deliberately deleted from the test suite).
94
-
-**Renamed** — a new image has the same content hash as a missing one.
61
+
When an upload is marked as selective, Sentry only diffs the snapshots you uploaded. Any snapshot that exists in the base build but was not included in the upload is treated as unchanged rather than removed. Removals and renames cannot be detected when using `--selective`, because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset.
|`--auth-token <TOKEN>`| Sentry auth token. Can also be set via `SENTRY_AUTH_TOKEN`. |
117
84
|`-o`, `--org <ORG>`| Sentry organization slug. Can also be set via `SENTRY_ORG`. |
118
85
|`-p`, `--project <PROJECT>`| Sentry project slug. Can also be set via `SENTRY_PROJECT`. |
119
-
|`--selective`| Mark the upload as a subset. Use when uploading only a portion of your snapshots (for example, affected tests only). |
120
-
|`--all-image-file-names <NAMES>`| Comma-separated list of all image file names in the full test suite. Enables removal and rename detection in selective mode. Implicitly enables `--selective`. Mutually exclusive with the other `--all-image-*` flags. |
121
-
|`--all-image-file-names-file <PATH>`| Path to a file (`.txt`, `.csv`, etc.) containing all image file names, one per line. Enables removal and rename detection in selective mode. Implicitly enables `--selective`. Mutually exclusive with the other `--all-image-*` flags. |
122
-
|`--all-image-file-names-as-regex <PATTERNS>`| Comma-separated list of regex patterns matching all image file names in the full test suite. Enables removal and rename detection in selective mode. Implicitly enables `--selective`. Mutually exclusive with the other `--all-image-*` flags. |
123
-
|`--all-image-file-names-as-regex-file <PATH>`| Path to a file containing regex patterns matching all image file names, one per line. Enables removal and rename detection in selective mode. Implicitly enables `--selective`. Mutually exclusive with the other `--all-image-*` flags. |
124
-
|`--diff-threshold <THRESHOLD>`| Float between `0.0` and `1.0`. Sentry only reports images as changed if the percentage of changed pixels exceeds this value. |
86
+
|`--selective`| Mark the upload as a subset. Use when uploading only a portion of your snapshots (for example, affected tests only). |
87
+
|`--diff-threshold <THRESHOLD>`| Float between `0.0` and `1.0`. Sentry only reports images as changed if the percentage of changed pixels exceeds this value. |
125
88
|`--head-sha <SHA>`| Commit SHA for the upload. Auto-detected in CI. |
126
89
|`--base-sha <SHA>`| Base commit SHA for comparison (PR only). Auto-detected from merge-base. |
127
90
|`--vcs-provider <PROVIDER>`| VCS provider (for example, `github`). Auto-detected from the git remote. |
Copy file name to clipboardExpand all lines: docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx
+37-10Lines changed: 37 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,9 +3,10 @@ title: Backend Tradeoffs
3
3
description: "How to choose the right crash backend in the Native SDK."
4
4
sidebar_order: 1000
5
5
---
6
-
The Native SDK lets users decide at compile-time between three crash backends:
6
+
The Native SDK lets users decide at compile-time between multiple crash backends:
7
7
8
8
*`crashpad`
9
+
*`native`
9
10
*`breakpad`
10
11
*`inproc`
11
12
@@ -16,7 +17,7 @@ Currently, `crashpad` is the default on all desktop platforms because it
16
17
* has an external `handler` process that allows for external snapshots and sending crash reports immediately (instead of on the next successful start of your application)
17
18
* further, snapshotting, report management, and uploading outside the crashed process are safer because the `crashpad_handler` is not affected by any corruptions that led to a crash
18
19
* supports more error types on [Linux](/platforms/native/advanced-usage/signal-handling/#signals-of-interest) and Windows (`abort()` and other `fast-fail` crashes, handling of heap corruptions)
19
-
* on macOS, the `crashpad_handler` will receive `EXC_CRASH` Mach exceptions, which the kernel generates during process exit if a terminal POSIX signal hasn't been handled. None of the two other backends will catch this exception.
20
+
* on macOS, the `crashpad_handler` will receive `EXC_CRASH` Mach exceptions, which the kernel generates during process exit if a terminal POSIX signal hasn't been handled. None of the other backends will catch this exception.
20
21
* is more maintained upstream (although most changes affect new platforms like Fuchsia)
21
22
* is the primary target for Sentry-developed extensions to the upstream implementation of backend handlers (most of which aren't a particular upside vs. the other backends, but changes to reach parity), including
22
23
* client-side stack traces (this is currently not available on `breakpad`)
@@ -41,11 +42,11 @@ Sentry decided on `crashpad` as the default on all platforms because it offers n
41
42
* you want to distribute your application via the macOS App Store
42
43
* you want to define crash hooks on macOS because there, error handling happens entirely in the `crashpad_handler`, whereas on Linux and Windows, at least the initial handling happens in your process, after which `crashpad_handler` takes over and snapshots the process to send a crash report
43
44
44
-
In the above cases, if you cannot loosen the requirements of your environment, you have to choose an in-process backend (meaning either `breakpad` or `inproc`).
45
+
In the above cases, if you cannot loosen the requirements of your environment, you have to choose another backend (meaning either `native`, `breakpad`, or `inproc`).
45
46
46
-
### How do I decide between `breakpad` or`inproc`?
47
+
### How do I decide between `native`, `breakpad`, and`inproc`?
47
48
48
-
Both backends are comparable in how they differ from `crashpad`. However, there are also considerable differences between the two:
49
+
`native` is the closest alternative to `crashpad` because it keeps crash handling out of process. If your constraints rule out an additional executable, the remaining options are `breakpad` and `inproc`, which are comparable in how they differ from `crashpad` and `native`. However, there are also considerable differences between the two:
49
50
50
51
*`inproc` only provides the backtrace of the crashing thread. `breakpad` records all threads in the minidump.
51
52
* similar to `crashpad`, `breakpad` uses the lowest level error handling mechanism on each platform (macOS: mach exception ports, Windows: `UnhandledExceptionFilter`, Linux: signal handlers), it does cover a smaller range of errors, though, as mentioned above.
@@ -54,7 +55,15 @@ Both backends are comparable in how they differ from `crashpad`. However, there
54
55
* if the handler thread is unavailable (for example, because synchronization failed, the thread crashed, or never started), `inproc` falls back to processing directly in the signal handler.
55
56
* on macOS, the handler thread uses a frame-pointer-based stack walker for arm64 and x86-64, which avoids the limitations that previously made `inproc` unusable on recent macOS versions.
56
57
*`inproc` is exceptionally lightweight and written entirely in C, meaning it does not rely on a weighty C++ runtime library, which is also more often affected by ABI incompatibilities
57
-
*`breakpad` generates minidumps (like `crashpad` does), whereas `inproc` follows the Sentry event structure and primarily defers to the OS-provided unwinder and symbolication capabilities. Sentry processing infrastructure can extract more information from the provided minidump than from just a stack trace and registers. However, it also means that the crash context inside the minidump will remain opaque until it is processed in the backend. In contrast, if required, a local `relay` instance (or another application-level proxy) could process an entire `inproc` event with only JSON parsing capabilities.
58
+
*`breakpad` generates minidumps (like `crashpad` and `native` by default), whereas `inproc` follows the Sentry event structure and primarily defers to the OS-provided unwinder and symbolication capabilities. Sentry processing infrastructure can extract more information from the provided minidump than from just a stack trace and registers. However, it also means that the crash context inside the minidump will remain opaque until it is processed in the backend. In contrast, if required, a local `relay` instance (or another application-level proxy) could process an entire `inproc` event with only JSON parsing capabilities.
59
+
60
+
### So when do I choose `native`?
61
+
62
+
Since SDK version [0.13.2](https://github.com/getsentry/sentry-native/releases/tag/0.13.2), the Native SDK comes with a new experimental out-of-process backend called `native`. It is implemented as part of the Native SDK and built on the SDK's own event, envelope, transport, attachment, options, and hook infrastructure.
63
+
64
+
The main advantages are tighter integration with the Native SDK and no external crash-handler dependency. As an out-of-process backend, `native` runs crash handling in the lightweight `sentry-crash` daemon and can send crash reports at crash time, similar to `crashpad`. Because crash collection is implemented in the SDK, `native` can call SDK-level hooks such as `before_screenshot`, and can [report an event, a minidump, or both](/platforms/native/configuration/backends/native/). The backend is also fully compatible with TSAN and ASAN builds.
65
+
66
+
Consider `native` when you want out-of-process crash handling with SDK-managed crash collection, when you need sanitizer compatibility, or when `crashpad` does not fit your deployment model.
58
67
59
68
### So when do I choose `inproc`?
60
69
@@ -75,8 +84,26 @@ If you dive into the details, you will find many trade-offs in the selection of
75
84
76
85
Sentry suggests the following sequence for your backend evaluations:
77
86
78
-
*`crashpad` (default)
87
+
*`crashpad` (default on Windows, macOS, and Linux), or `native` (experimental)
79
88
*`breakpad`
80
-
*`inproc`
81
-
82
-
from most feature-complete to least, where a step down should only be triggered by environmental inhibitors. With the above, you now have exemplary decision points to help guide you before you start evaluating your error reporting scenario.
89
+
*`inproc` (default on Android)
90
+
91
+
from most feature-complete to least, where a step down should only be triggered by environmental inhibitors, as summarized in the following table:
Controls which crash report format the `native` backend sends when the application crashes. This setting only affects the `native` backend. See [Crash Reporting Modes](/platforms/native/configuration/backends/native/#crash-reporting-modes).
Controls how much memory the `native` backend captures in minidumps. This setting only affects the `native` backend and crash reporting modes that send a minidump. See [Minidump Capture Modes](/platforms/native/configuration/backends/native/#minidump-capture-modes).
Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` header for [distributed tracing](https://docs.sentry.io/platforms/native/tracing/trace-propagation/custom-instrumentation/).
Sentry makes it possible to automatically take a screenshot and include it as an <PlatformLinkto="/enriching-events/attachments/">attachment</PlatformLink> when a user experiences an error, an exception, or a crash.
10
10
11
-
This feature is currently only available on Windows and has a few limitations. For example, the `inproc` and `breakpad` backends use local exception handlers for capturing the screenshot and therefore rely on the exception handler being called. Only the `crashpad` backend with an external handler process is able to capture screenshots of fast-fail crashes that bypass Structured Exception Handling ([`SEH`](https://learn.microsoft.com/en-us/windows/win32/debug/structured-exception-handling)). Another example where a screenshot might not be available is when the event happens before the screen starts to load. So inherently, this feature is a best effort solution.
11
+
This feature is currently only available on Windows and has a few limitations. For example, the `inproc` and `breakpad` backends use local exception handlers for capturing the screenshot and therefore rely on the exception handler being called. Only the `crashpad` and `native` backends can capture screenshots of fast-fail crashes that bypass Structured Exception Handling ([`SEH`](https://learn.microsoft.com/en-us/windows/win32/debug/structured-exception-handling)) because screenshot capture happens out-of-process. However, `crashpad` does not support the `before_screenshot` hook, because the screenshot is captured out-of-process and the SDK cannot communicate the hook result to the `crashpad_handler`. The `native` backend calls `before_screenshot` during crash handling and communicates the result to the `sentry-crash` daemon, which captures the screenshot out-of-process. Another example where a screenshot might not be available is when the event happens before the screen starts to load. So inherently, this feature is a best effort solution.
Copy file name to clipboardExpand all lines: docs/platforms/native/configuration/backends/crashpad.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,4 +47,4 @@ locking in place.
47
47
48
48
When using the Crashpad backend on macOS, the status of crashed sessions can not be reliably determined, and may be classified as [`abnormal`](/product/releases/health/release-details/) exits instead.
49
49
50
-
If you want to deploy your application to the macOS App Store or distribute it "sandboxed" outside, the crashpad client will fail to start the `crashpad_handler` executable (due to sandbox restrictions). For these deployment targets, we recommend using the `breakpad` backend.
50
+
If you want to deploy your application to the macOS App Store or distribute it "sandboxed" outside, the crashpad client will fail to start the `crashpad_handler` executable (due to sandbox restrictions). For these deployment targets, use the [`native`](/platforms/native/configuration/backends/native/) backend, or `breakpad`/`inproc` if you cannot ship an additional executable.
0 commit comments