-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
docs(native): Add WER guide for sending minidumps to Sentry #18595
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
jpnurmi
wants to merge
5
commits into
master
Choose a base branch
from
jpnurmi/feat/native-wer
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+72
−0
Open
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
71 changes: 71 additions & 0 deletions
71
docs/platforms/native/advanced-usage/windows-error-reporting/index.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| --- | ||
| title: Windows Error Reporting | ||
| description: "Use the Native SDK to send minidumps captured by Windows Error Reporting (WER) to Sentry." | ||
| sidebar_order: 2200 | ||
| --- | ||
|
|
||
| [Windows Error Reporting (WER)](https://learn.microsoft.com/en-us/windows/win32/wer/windows-error-reporting) is a Windows system service that detects process crashes and generates minidumps. If you already use WER and prefer to keep it as your primary crash reporter, you can use the Native SDK (built without a crash backend) to send those locally captured minidumps to Sentry. | ||
|
|
||
| <Alert> | ||
|
|
||
| This guide describes how to use the Native SDK solely as a client to upload WER-captured minidumps to Sentry. In this mode, the SDK is not responsible for capturing crashes, so features like attachments, logs, tags, and screenshots are not available. If you don't need WER specifically, we recommend using the [crashpad](/platforms/native/configuration/backends/crashpad/) or [native](/platforms/native/configuration/backends/native/) backend instead, which can capture WER / fast-fail crashes. | ||
|
|
||
| </Alert> | ||
|
|
||
| ## Configure WER to Collect Local Dumps | ||
|
|
||
| WER can be configured to store a minidump to a local directory when a process crashes. This requires setting registry keys under `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps`, which needs administrator privileges and is typically done at installation time. | ||
|
|
||
| The following registry configuration enables local dump collection for your application: | ||
|
|
||
| | Name | Type | Value | | ||
| | ---- | ---- | ----- | | ||
| | `DumpFolder` | `REG_EXPAND_SZ` | Path to a local directory (e.g., `%LOCALAPPDATA%\YourApp\CrashDumps`) | | ||
| | `DumpType` (optional) | `REG_DWORD` | `0` ([custom dump](https://learn.microsoft.com/en-us/windows/win32/wer/collecting-user-mode-dumps)), `1` (mini dump, default), or `2` (full dump — includes heap, may contain sensitive data) | | ||
| | `DumpCount` (optional) | `REG_DWORD` | Maximum number of dumps to keep (default `10`) | | ||
|
|
||
| For example, you could deploy this from an installer by running: | ||
|
|
||
| ```batch | ||
| reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpFolder /t REG_EXPAND_SZ /d "%%LOCALAPPDATA%%\YourApp\CrashDumps" /f | ||
| reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpType /t REG_DWORD /d 1 /f | ||
| reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpCount /t REG_DWORD /d 10 /f | ||
| ``` | ||
|
|
||
| ```powershell | ||
| reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpFolder /t REG_EXPAND_SZ /d "%LOCALAPPDATA%\YourApp\CrashDumps" /f | ||
| reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpType /t REG_DWORD /d 1 /f | ||
| reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpCount /t REG_DWORD /d 10 /f | ||
| ``` | ||
|
|
||
| For more details, see [Collecting User-Mode Dumps](https://learn.microsoft.com/en-us/windows/win32/wer/collecting-user-mode-dumps). | ||
|
|
||
| ## Build the Native SDK with Crash Reporting Disabled | ||
|
|
||
| To prevent the Native SDK from capturing crashes (which would result in duplicate crash reports alongside WER), build it without a crash backend: | ||
|
|
||
| ```cmake | ||
| cmake -DSENTRY_BACKEND=none ... | ||
| ``` | ||
|
|
||
| With `SENTRY_BACKEND=none`, the SDK will not capture crashes on its own, but you can still use its API to capture and send minidumps. | ||
|
|
||
| ## Capture and Send WER Dumps to Sentry | ||
|
|
||
| On application startup, initialize the SDK and upload any minidumps WER has stored in the dump directory. For each minidump file, call `sentry_capture_minidumpw()` with its path: | ||
|
|
||
| ```c | ||
| sentry_options_t *options = sentry_options_new(); | ||
| sentry_options_set_dsn(options, "___PUBLIC_DSN___"); | ||
| sentry_init(options); | ||
|
|
||
| /* for each minidump_path in L"%LOCALAPPDATA%\\YourApp\\CrashDumps" */ { | ||
| sentry_uuid_t event_id = sentry_capture_minidumpw(minidump_path); | ||
| if (!sentry_uuid_is_nil(&event_id)) { | ||
| DeleteFileW(minidump_path); | ||
| } | ||
| } | ||
|
sentry[bot] marked this conversation as resolved.
|
||
| sentry_close(); | ||
| ``` | ||
|
|
||
| `sentry_capture_minidumpw()` processes the minidump and uploads it to Sentry as a crash event. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.