|
| 1 | +--- |
| 2 | +title: Backend Tradeoffs |
| 3 | +description: "How to choose the right backend in the Native SDK." |
| 4 | +sidebar_order: 1000 |
| 5 | +--- |
| 6 | +The Native SDK lets users decide at compile-time between three backends: |
| 7 | + |
| 8 | +* `crashpad` |
| 9 | +* `breakpad` |
| 10 | +* `inproc` |
| 11 | + |
| 12 | +Currently, `crashpad` is the default on all platforms because it |
| 13 | + |
| 14 | +* has an external `handler` process that allows for external snapshots and immediate sending of crash reports (instead of the next successful start of your application) |
| 15 | +* is the primary target for extension compared to upstream, including |
| 16 | + * client-side stack traces |
| 17 | + * attachment handling |
| 18 | + * HTTP proxy support |
| 19 | + * CMake build scripts |
| 20 | + * GCC and MinGW support |
| 21 | + * `FirstChanceHandler` on Windows and extension of its synchronization to support sentry hooks |
| 22 | + * 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 | + |
| 26 | +### When shouldn't I use the `crashpad` backend? |
| 27 | + |
| 28 | +Sentry decided on `crashpad` as the default on all platforms because there are a lot of upsides. However, there are use cases where `crashpad` cannot be used or makes distribution or deployment much harder. We provide other backends for situations when |
| 29 | + |
| 30 | +* you cannot package or deploy an additional executable (the `crashpad_handler`) |
| 31 | +* you cannot allow a secondary process to connect via `ptrace` to your application (AWS Lambda, Flatpak-, Snap-Sandboxes) |
| 32 | +* IPC between your process and the `crashpad_handler` is inhibited by security settings or not available in your deployment target |
| 33 | +* your deployment scenario cannot wait for the `crashpad_handler` to finish its work before a shutdown-after-crash (systemd, Docker) |
| 34 | +* you want to distribute your application via the macOS App Store |
| 35 | + |
| 36 | +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`). |
| 37 | + |
| 38 | +### How do I decide between `breakpad` or `inproc`? |
| 39 | + |
| 40 | +Both backends are comparable in how they differ from `crashpad`. However, there are also considerable differences between the two: |
| 41 | + |
| 42 | +* `inproc` only provides the backtrace of the crashing thread. `breakpad` records all threads in the minidump. |
| 43 | +* 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. |
| 44 | +* `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 | +* as a result of choosing signal handling on macOS, `inproc` is currently broken on macOS since Apple eliminated unwinding from signal handlers |
| 46 | +* `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 |
| 47 | +* `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. |
| 48 | + |
| 49 | +### So when do I choose `inproc`? |
| 50 | + |
| 51 | +`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. |
| 52 | + |
| 53 | +`inproc` is the right choice if you want |
| 54 | + |
| 55 | +* want minimal dependencies |
| 56 | +* want the smallest footprint for the resulting artifact |
| 57 | +* don't need to support the latest macOS versions |
| 58 | +* find the minimal featureset compared to `breakpad` and `crashpad` sufficient for your scenario |
| 59 | + |
| 60 | +### Summary |
| 61 | + |
| 62 | +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 |
| 63 | + |
| 64 | +* `crashpad` (default) |
| 65 | +* `breakpad` |
| 66 | +* `inproc` |
| 67 | + |
| 68 | +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. |
0 commit comments