Skip to content

Commit 97af477

Browse files
authored
rewriting some parts for clarity
1 parent 9bb4918 commit 97af477

File tree

1 file changed

+16
-13
lines changed
  • docs/platforms/native/advanced-usage/backend-tradeoffs

1 file changed

+16
-13
lines changed

docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,17 @@ The Native SDK lets users decide at compile-time between three crash backends:
1212
Currently, `crashpad` is the default on all desktop platforms because it
1313

1414
* 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)
15-
* is the primary target for extension compared to upstream, including
16-
* client-side stack traces
15+
* 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
16+
* 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)
17+
* is more maintained upstream (although most changes affect new platforms like Fuchsia)
18+
* 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
19+
* client-side stack traces (this is currently not available on `breakpad`)
1720
* attachment handling
1821
* HTTP proxy support
19-
* CMake build scripts
2022
* GCC and MinGW support
2123
* `FirstChanceHandler` on Windows and extension of its synchronization to support Sentry hooks
2224
* cooperation with Epic's Easy Anti Cheat
23-
* 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)
24-
* is more maintained upstream (although most changes affect new platforms like Fuchsia)
25+
* CMake build scripts (some users use our backend handler forks solely because of this reason)
2526

2627
### When shouldn't I use the `crashpad` backend?
2728

@@ -32,7 +33,7 @@ Sentry decided on `crashpad` as the default on all platforms because there are a
3233
* IPC between your process and the `crashpad_handler` is inhibited by security settings or not available in your deployment target
3334
* your deployment scenario cannot wait for the `crashpad_handler` to finish its work before a shutdown-after-crash (systemd, Docker)
3435
* you want to distribute your application via the macOS App Store
35-
* 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
36+
* 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
3637

3738
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`).
3839

@@ -41,29 +42,31 @@ In the above cases, if you cannot loosen the requirements of your environment, y
4142
Both backends are comparable in how they differ from `crashpad`. However, there are also considerable differences between the two:
4243

4344
* `inproc` only provides the backtrace of the crashing thread. `breakpad` records all threads in the minidump.
44-
* 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.
45-
* `inproc`, on the other hand, uses signal handling on Linux and macOS (meaning you only get a `POSIX` compatibility layer over mach exception ports) and `UnhandledExceptionFilter` on Windows (solely errors registered by SEH)
45+
* 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.
46+
* `inproc` uses signal handling on macOS, meaning you only get a `POSIX` compatibility layer over mach exception ports. It relies on the same mechanisms as `breakpad` on Windows and Linux.
4647
* as a result of choosing signal handling on macOS, `inproc` is currently broken on macOS since Apple eliminated unwinding from signal handlers
4748
* `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
48-
* `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 can potentially extract more information from the provided minidump than simply a stack trace and registers. However, it also means that the crash context inside the minidump will be opaque until processed in the backend, whereas a local `relay` instance could process an entire `inproc` event if required.
49+
* `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 - potentially - extract more information from the provided minidump than from only a stack trace and registers. However, it also means that the crash context inside the minidump will be opaque until 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.
4950

5051
### So when do I choose `inproc`?
5152

52-
`inproc` is currently the backend of choice for `Android` because it allows us to couple it with our own fork of a powerful platform unwinder `libunwindstack` (rather than relying on a user-space interface). This allows us to support very old Android versions. In addition, stack walking on device on Android is preferred since we don't have all system symbols available for server-side symbolication. A [best-effort symbol collection exists](https://github.com/getsentry/symbol-collector), but that'll never be as reliable as stackwalking on device.
53+
`inproc` is currently the backend of choice for `Android` because it allows us to bundle it with our fork of the platform unwinder `libunwindstack` that provides a complete interface for unwinding and symbolication (rather than relying on the minimal user-space interface). This enables us to support a broad range of Android versions. In addition, stack walking on-device on Android is preferred since we don't have all system symbols available for server-side symbolication. A [best-effort symbol collection exists](https://github.com/getsentry/symbol-collector), but that'll never be as reliable as stackwalking on-device.
5354

5455
`inproc` is the right choice if you
5556

5657
* want minimal dependencies
5758
* want the smallest footprint for the resulting artifact
5859
* don't need to support the latest macOS versions
59-
* find the minimal featureset compared to `breakpad` and `crashpad` sufficient for your scenario
60+
* find the minimal feature set compared to `breakpad` and `crashpad` sufficient for your scenario
6061

6162
### Summary
6263

63-
There are many trade-offs in the selection of backends if you dive into the details. The above merely scratches the surface. Sentry suggests a sequence of evaluations like
64+
If you dive into the details, you will find many trade-offs in the selection of backends. The above merely provides a first overview. Further, the above is only a snapshot of the current capabilities, where some trade-offs are incidental and do not follow a particular strategy or technological necessity. The primary reason for providing multiple backends is to cover as many user scenarios as possible, which requires a bit of insight if you decide to deviate from the defaults.
65+
66+
Sentry suggests the following sequence for your backend evaluations:
6467

6568
* `crashpad` (default)
6669
* `breakpad`
6770
* `inproc`
6871

69-
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 for your error reporting scenario.
72+
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 that can help you before you start the evaluation of your error reporting scenario.

0 commit comments

Comments
 (0)