From 8485f4fac4051bdc691d872382093adfab28c2d2 Mon Sep 17 00:00:00 2001 From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> Date: Tue, 13 May 2025 13:58:11 +0200 Subject: [PATCH 1/7] reposition line about Docker - avoid it showing up under "When shouldn't I use the `crashpad` backend" in docs searches --- .../native/advanced-usage/backend-tradeoffs/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx b/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx index 3d229dfb05af8e..5bfe638ddcc8c2 100644 --- a/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx +++ b/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx @@ -26,6 +26,8 @@ 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) +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. + ### 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 +40,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: From 5358ecc5c7b18c9b8b6d58eb370b57e8bb1a2742 Mon Sep 17 00:00:00 2001 From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> Date: Tue, 13 May 2025 14:22:03 +0200 Subject: [PATCH 2/7] add heading --- .../platforms/native/advanced-usage/backend-tradeoffs/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx b/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx index 5bfe638ddcc8c2..8ffc2574893962 100644 --- a/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx +++ b/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) From cba3210e65913a6e4f1fb5e835d19f932baf9434 Mon Sep 17 00:00:00 2001 From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> Date: Tue, 13 May 2025 14:26:36 +0200 Subject: [PATCH 3/7] Update index.mdx --- .../platforms/native/advanced-usage/backend-tradeoffs/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx b/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx index 8ffc2574893962..e11c927c585c2f 100644 --- a/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx +++ b/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx @@ -28,7 +28,7 @@ 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) -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. +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. ### When shouldn't I use the `crashpad` backend? From 0efe33d414e1f41fb57bd3093fc41fa83f5fd383 Mon Sep 17 00:00:00 2001 From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> Date: Tue, 13 May 2025 15:39:45 +0200 Subject: [PATCH 4/7] apply suggestion --- .../native/advanced-usage/backend-tradeoffs/index.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx b/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx index e11c927c585c2f..0a805eb7de21a1 100644 --- a/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx +++ b/docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx @@ -28,8 +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) -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. - + +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. + ### 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 From b919e68f67d9b2a40fff458050d5cc2849951d65 Mon Sep 17 00:00:00 2001 From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> Date: Wed, 14 May 2025 13:20:21 +0200 Subject: [PATCH 5/7] Add Container Environments page --- .../container-environments/index.mdx | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/platforms/native/advanced-usage/container-environments/index.mdx diff --git a/docs/platforms/native/advanced-usage/container-environments/index.mdx b/docs/platforms/native/advanced-usage/container-environments/index.mdx new file mode 100644 index 00000000000000..0993b1cc8cff2e --- /dev/null +++ b/docs/platforms/native/advanced-usage/container-environments/index.mdx @@ -0,0 +1,32 @@ +--- +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 +Since 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) enables waiting for the `crashpad_handler` (on Linux) to finish its work before a shutdown-after-crash. + + +In SDK versions before 0.8.3, one 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 +``` From 32a425e42b441b04ae0b20356c547e54d1a6b829 Mon Sep 17 00:00:00 2001 From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> Date: Mon, 19 May 2025 10:58:09 +0200 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Alex Krawiec --- .../native/advanced-usage/container-environments/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/native/advanced-usage/container-environments/index.mdx b/docs/platforms/native/advanced-usage/container-environments/index.mdx index 0993b1cc8cff2e..d17ccb6fa1679c 100644 --- a/docs/platforms/native/advanced-usage/container-environments/index.mdx +++ b/docs/platforms/native/advanced-usage/container-environments/index.mdx @@ -4,14 +4,14 @@ description: "How to use the Sentry Native SDK in container environments." sidebar_order: 2000 --- -## Database-path on a mounted volume +## 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 Since 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) enables waiting for the `crashpad_handler` (on Linux) to finish its work before a shutdown-after-crash. -In SDK versions before 0.8.3, one could use a script similar to the example below to tie container shutdown to the `crashpad_handler` process. +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 From 9d2ff88e51a0d478863e40bbda0ab1b4f653bd0f Mon Sep 17 00:00:00 2001 From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> Date: Mon, 19 May 2025 10:58:55 +0200 Subject: [PATCH 7/7] apply adapted suggestion from code review --- .../native/advanced-usage/container-environments/index.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/platforms/native/advanced-usage/container-environments/index.mdx b/docs/platforms/native/advanced-usage/container-environments/index.mdx index d17ccb6fa1679c..6033e8b13599e5 100644 --- a/docs/platforms/native/advanced-usage/container-environments/index.mdx +++ b/docs/platforms/native/advanced-usage/container-environments/index.mdx @@ -8,8 +8,7 @@ sidebar_order: 2000 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 -Since 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) enables waiting for the `crashpad_handler` (on Linux) to finish its work before a shutdown-after-crash. - +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