feat(native): add backend trade-offs to Advanced Usage #11721

supervacuus · 2024-11-04T13:38:30Z

DESCRIBE YOUR PR

I try to cover some of the surface area of the tradeoffs involved when choosing a backend in the Native SDK. This was requested by downstream SDK maintainers (ref: issues below).

Fixes: getsentry/sentry-native#908
Fixes: getsentry/sentry-native#1070

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.):
Other deadline:
None: Not urgent, can wait up to 1 week+

SLA

Teamwork makes the dream work, so please add a reviewer to your PRs.
Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

Sentry Docs contributor guide

vercel · 2024-11-04T13:38:35Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
changelog	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 8, 2024 8:49am
sentry-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 8, 2024 8:49am

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
develop-docs	⬜️ Ignored (Inspect)	Visit Preview		Nov 8, 2024 8:49am

codecov · 2024-11-04T13:38:45Z

Bundle Report

Changes will increase total bundle size by 193.14kB (1.28%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-server-cjs	8.5MB	193.14kB (2.33%) ⬆️
sentry-docs-client-array-push	6.44MB	6 bytes (-0.0%) ⬇️

kahest

thanks, IMO very helpful as an overview. left some small suggestions

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

vaind

Thank you, this is very helpful. Some questions/improvement ideas below:

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

vaind · 2024-11-04T13:57:19Z

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

+
+* `inproc` only provides the backtrace of the crashing thread. `breakpad` records all threads in the minidump.
+* 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.
+* `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)


(solely errors registered by SEH)

This could use further clarification on differences between inproc and breakpad

I wanted to say here that they use the same mechanism, and UnhandledExceptionFilter and SEH have equivalent meanings in this case. I can see how this easily reads as a distinction between breakpad and inproc. Should I remove it?

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

Co-authored-by: Karl Heinz Struggl <[email protected]>

Co-authored-by: Ivan Dlugos <[email protected]>

Co-authored-by: Karl Heinz Struggl <[email protected]>

JoshuaMoelans

LGTM (+ small grammar nit)

docs/platforms/native/configuration/backends/index.mdx

bruno-garcia

This is really, really helpful stuff. Thank you.

I left some questions to help novices on the matter like me better understand things

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

bruno-garcia · 2024-11-05T03:42:50Z

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

+
+* 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)
+* is the primary target for extension compared to upstream, including
+  * client-side stack traces


sorry if this is a dumb question, but what does this mean? Is that vs "server-side stack traces"?
Don't we create a minidump with crashpad and hence stack walk on the server?

That's not at all a dumb question. We currently have an "experimental" implementation of client-side stack traces for crashpad (which you can enable at compile time) for users who prefer to deploy to environments where they can unwind and symbolicate locally instead of managing their debug symbols at build time.

Minidumps don't preclude adding additional data; in this case, we unwind and symbolicate locally and write a separate stack trace Minidump stream known in the processing pipeline:

https://github.com/getsentry/symbolicator/blob/3d241153e8bbd06bb6bb689f597bdb76c1b7c44e/crates/symbolicator-native/src/symbolication/minidump_stacktraces.rs#L1-L94

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

bruno-garcia · 2024-11-05T03:46:07Z

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

+
+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
+
+* you cannot package or deploy an additional executable (the `crashpad_handler`)


is it useful to add 'or spawn'? Given environments where there's a sandbox and we can't create child processes? (Xbox and UWP I believe?)

Suggested change

* you cannot package or deploy an additional executable (the `crashpad_handler`)

* you cannot package, deploy or spawn an additional executable (the `crashpad_handler`)

I see this might be covered in the next two lines though

I wanted to differentiate cases in which even packaging separate executables was a problem from cases in which a runtime inhibition exists.

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

Co-authored-by: Bruno Garcia <[email protected]>

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

bruno-garcia · 2024-11-10T18:02:43Z

This is a big step forward in documenting our native support. Thank you Mischan!

* master: (39 commits) getsentry/relay@403f2bf feat(native): add backend trade-offs to Advanced Usage (#11721) 🔧 chore(api): add additional troubleshooting instructions to publish api docs (#11772) Bump API schema to 02adb960 (#11773) Update metric-alert-config.mdx (#11760) update w-9 tax form (#11764) chore: silence fetch cache error due to size limit (#11767) fix Ureal engine DSN placeholder (#11769) feat: Banner pathname regex (#11761) docs(nuxt): Add troubleshoot pnpm (#11720) Docker Desktop to Colima fix (#11752) Bump API schema to d51784a6 (#11759) ref(feedback): update user feedback docs to include external issue linking & auto issue creation (#11729) getsentry/relay@d23c39a Changed /store to /envelope (because /store does not exist anymore (#11755) Refactor arcade embeds (#11722) feat(js): Add `skipBrowserExtensionCheck` documentation (#11693) getsentry/relay@a7d9096 fix mermaid charts in dark mode (#11754) fix: Log4j configurations and wording (#11395) ...

* feat(native): add backend trade-offs to Advanced Usage * Add hook on macOS exception * Update docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx Co-authored-by: Karl Heinz Struggl <[email protected]> * Update docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx Co-authored-by: Karl Heinz Struggl <[email protected]> * Update docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx Co-authored-by: Karl Heinz Struggl <[email protected]> * Update docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx Co-authored-by: Karl Heinz Struggl <[email protected]> * Update docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx Co-authored-by: Ivan Dlugos <[email protected]> * Update docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx Co-authored-by: Ivan Dlugos <[email protected]> * Update docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx Co-authored-by: Karl Heinz Struggl <[email protected]> * Highlight inproc macOS breakage * grammar inproc macOS 13 breakage * Update docs/platforms/native/advanced-usage/backend-tradeoffs/index.mdx Co-authored-by: Bruno Garcia <[email protected]> * rewriting some parts for clarity --------- Co-authored-by: Karl Heinz Struggl <[email protected]> Co-authored-by: Ivan Dlugos <[email protected]> Co-authored-by: Bruno Garcia <[email protected]>

feat(native): add backend trade-offs to Advanced Usage

fbf3759

supervacuus requested a review from JoshuaMoelans November 4, 2024 13:38

supervacuus requested review from bruno-garcia, kahest and vaind November 4, 2024 13:38

vercel bot deployed to Preview – sentry-docs November 4, 2024 13:51 View deployment

kahest approved these changes Nov 4, 2024

View reviewed changes

vaind reviewed Nov 4, 2024

View reviewed changes

Add hook on macOS exception

d447fb2

vercel bot deployed to Preview – changelog November 4, 2024 14:05 View deployment

supervacuus and others added 7 commits November 4, 2024 15:06

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

260265a

Co-authored-by: Karl Heinz Struggl <[email protected]>

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

a6396e2

Co-authored-by: Karl Heinz Struggl <[email protected]>

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

812149e

Co-authored-by: Karl Heinz Struggl <[email protected]>

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

2c50cd1

Co-authored-by: Karl Heinz Struggl <[email protected]>

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

7d5b8bd

Co-authored-by: Ivan Dlugos <[email protected]>

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

a92cf86

Co-authored-by: Ivan Dlugos <[email protected]>

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

1b641e1

Co-authored-by: Karl Heinz Struggl <[email protected]>

vercel bot deployed to Preview – changelog November 4, 2024 14:13 View deployment

Highlight inproc macOS breakage

48eb26a

vercel bot deployed to Preview – changelog November 4, 2024 14:37 View deployment

supervacuus mentioned this pull request Nov 4, 2024

docs: clarify macOS support of the inproc backend getsentry/sentry-native#1072

Merged

vercel bot deployed to Preview – sentry-docs November 4, 2024 14:56 View deployment

JoshuaMoelans approved these changes Nov 4, 2024

View reviewed changes

docs/platforms/native/configuration/backends/index.mdx Outdated Show resolved Hide resolved

grammar inproc macOS 13 breakage

8b260aa

vercel bot deployed to Preview – changelog November 4, 2024 15:32 View deployment

vercel bot deployed to Preview – sentry-docs November 4, 2024 15:47 View deployment

bruno-garcia approved these changes Nov 5, 2024

View reviewed changes

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

9bb4918

Co-authored-by: Bruno Garcia <[email protected]>

vercel bot deployed to Preview – changelog November 8, 2024 06:52 View deployment

vercel bot deployed to Preview – sentry-docs November 8, 2024 07:07 View deployment

rewriting some parts for clarity

97af477

vercel bot deployed to Preview – changelog November 8, 2024 08:34 View deployment

vercel bot deployed to Preview – sentry-docs November 8, 2024 08:49 View deployment

bruno-garcia approved these changes Nov 10, 2024

View reviewed changes

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

bruno-garcia merged commit 19ea857 into master Nov 10, 2024
11 checks passed

bruno-garcia deleted the feat/native_section_for_backend_tradeoffs branch November 10, 2024 18:02

github-actions bot locked and limited conversation to collaborators Nov 26, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(native): add backend trade-offs to Advanced Usage #11721

feat(native): add backend trade-offs to Advanced Usage #11721

supervacuus commented Nov 4, 2024

vercel bot commented Nov 4, 2024 •

edited

Loading

codecov bot commented Nov 4, 2024 •

edited

Loading

kahest left a comment

vaind left a comment

vaind Nov 4, 2024

supervacuus Nov 4, 2024

JoshuaMoelans left a comment

bruno-garcia left a comment

bruno-garcia Nov 5, 2024

supervacuus Nov 8, 2024

bruno-garcia Nov 5, 2024

supervacuus Nov 8, 2024

bruno-garcia commented Nov 10, 2024


		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

		* you cannot package or deploy an additional executable (the `crashpad_handler`)

	* you cannot package or deploy an additional executable (the `crashpad_handler`)
	* you cannot package, deploy or spawn an additional executable (the `crashpad_handler`)

feat(native): add backend trade-offs to Advanced Usage #11721

feat(native): add backend trade-offs to Advanced Usage #11721

Conversation

supervacuus commented Nov 4, 2024

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

LEGAL BOILERPLATE

EXTRA RESOURCES

vercel bot commented Nov 4, 2024 • edited Loading

codecov bot commented Nov 4, 2024 • edited Loading

Bundle Report

kahest left a comment

Choose a reason for hiding this comment

vaind left a comment

Choose a reason for hiding this comment

vaind Nov 4, 2024

Choose a reason for hiding this comment

supervacuus Nov 4, 2024

Choose a reason for hiding this comment

JoshuaMoelans left a comment

Choose a reason for hiding this comment

bruno-garcia left a comment

Choose a reason for hiding this comment

bruno-garcia Nov 5, 2024

Choose a reason for hiding this comment

supervacuus Nov 8, 2024

Choose a reason for hiding this comment

bruno-garcia Nov 5, 2024

Choose a reason for hiding this comment

supervacuus Nov 8, 2024

Choose a reason for hiding this comment

bruno-garcia commented Nov 10, 2024

vercel bot commented Nov 4, 2024 •

edited

Loading

codecov bot commented Nov 4, 2024 •

edited

Loading