feat(native): clarifying crashpad behavior (#13689)

Vercel previews
- [backend
tradeoffs](https://sentry-docs-lawi0tyqh.sentry.dev/platforms/native/advanced-usage/backend-tradeoffs/)
- [container
environments](https://sentry-docs-lawi0tyqh.sentry.dev/platforms/native/advanced-usage/container-environments/)

## DESCRIBE YOUR PR
(from Slack)
> lots to clarify, crashpad behavior, min version needed, docker entry
point script waiting for the handler etc.

We already have some pages that detail aspects of this, but we want to
make sure this is as clear as possible:
-
https://docs.sentry.io/platforms/native/advanced-usage/backend-tradeoffs/
- https://docs.sentry.io/platforms/native/configuration/backends/

## Current changes/fixes
- [x] repositioning `wait_for_upload` line in backend tradeoffs;
otherwise, search showed it under "When shouldn't I use the crashpad
backend?". Also added new heading above for it to fall under.
(note: search doesn't seem to update right away)
  <details>
  before
  

![image](https://github.com/user-attachments/assets/2d57893a-652d-4e72-a838-eda5525525f1)
  
  after

(this is where I'd put a screenshot of the search pointing to `Why is
crashpad the default`
([preview](https://sentry-docs-lawi0tyqh.sentry.dev/platforms/native/advanced-usage/backend-tradeoffs/#why-is-crashpad-the-default))
instead, but seems to not update on Vercel 🤔 )

  </details>

- [x] added min. version to `wait_for_upload` mention
- [x] add docker entry point script to wait for handler (for people
below 0.8.3/non-linux)


## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE -->
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [x] None: Not urgent, can wait up to 1 week+

---------

Co-authored-by: Alex Krawiec <[email protected]>

Author: 2 people

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

@@ -9,6 +9,8 @@ The Native SDK lets users decide at compile-time between three crash backends:
 * `breakpad`
 * `inproc`
 
+### Why is `crashpad` the default?
+
 Currently, `crashpad` is the default on all desktop platforms because it
 
 * 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)
@@ -26,6 +28,9 @@ Currently, `crashpad` is the default on all desktop platforms because it
   * cooperation with Epic's Easy Anti-Cheat
   * CMake build scripts (some users use our backend handler forks solely because of this reason)
 
+<Alert>
+When your deployment scenario should wait for the `crashpad_handler` to finish its work before a shutdown-after-crash (systemd, Docker), in Linux environments since SDK version [0.8.3](https://github.com/getsentry/sentry-native/releases/tag/0.8.3), you can enable the [option `crashpad_wait_for_upload`](/platforms/native/configuration/options/#crashpad-wait-for-upload) to delay application shutdown until the upload of the crash report is completed.
+</Alert>
 ### When shouldn't I use the `crashpad` backend?
 
 Sentry decided on `crashpad` as the default on all platforms because it offers numerous advantages. However, there are use cases where `crashpad` cannot be used or makes distribution or deployment much harder. We provide other backends for situations when
@@ -38,8 +43,6 @@ Sentry decided on `crashpad` as the default on all platforms because it offers n
 
 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`).
 
-When your deployment scenario should wait for the `crashpad_handler` to finish its work before a shutdown-after-crash (systemd, Docker), you can enable the option [`crashpad_wait_for_upload`](/platforms/native/configuration/options/#crashpad-wait-for-upload) to delay application shutdown until the upload of the crash report is completed.
-
 ### How do I decide between `breakpad` or `inproc`?
 
 Both backends are comparable in how they differ from `crashpad`. However, there are also considerable differences between the two:

docs/platforms/native/advanced-usage/container-environments/index.mdx

@@ -0,0 +1,31 @@
+---
+title: Container Environments
+description: "How to use the Sentry Native SDK in container environments."
+sidebar_order: 2000
+---
+
+## Database Path on a Mounted Volume
+The Sentry Native SDK uses a [database path](https://docs.sentry.io/platforms/native/configuration/options/#database-path) to store events and crash reports. When you are using a containerized environment, you may want to mount a volume to persist the database across container restarts to avoid losing this data.
+
+## Waiting for `Crashpad` to Finish
+Starting with SDK version [0.8.3](https://github.com/getsentry/sentry-native/releases/tag/0.8.3), the [option `crashpad_wait_for_upload`](https://docs.sentry.io/platforms/native/configuration/options/#crashpad-wait-for-upload) allows the application (on Linux) to wait for the `crashpad_handler` to finish before a shutdown-after-crash.
+
+In SDK versions older than 0.8.3, you could use a script similar to the example below to tie container shutdown to the `crashpad_handler` process:
+```bash
+#!/bin/bash
+
+# ./execute-main-app
+
+crashpad_timeout_s=10
+crashpad_process_name=crashpad_handler
+crashpad_pid=$(pgrep -n -f $crashpad_process_name)
+if [ -n "$crashpad_pid" ]; then
+    echo "Waiting for crashpad to finish..."
+    timeout $crashpad_timeout_s tail --pid=$crashpad_pid -f /dev/null
+    if [ $? -eq 124 ]; then
+        echo "The crashpad process did not finish within $crashpad_timeout_s seconds"
+    else
+        echo "The crashpad process finished successfully"
+    fi
+fi
+```