diff --git a/develop-docs/sdk/telemetry/attachments/index.mdx b/develop-docs/sdk/telemetry/attachments/index.mdx index 1eed71fd9984a..5d50f088d9eb1 100644 --- a/develop-docs/sdk/telemetry/attachments/index.mdx +++ b/develop-docs/sdk/telemetry/attachments/index.mdx @@ -153,7 +153,13 @@ SDKs **MAY** attach a `view-hierarchy.json` file following the structure describ For native SDKs (since 1.4.0), the path to the view hierarchy file **SHOULD** be configurable at SDK initialization. The SDK monitors the file and uploads it along with any event or crash: ```c -sentry_options_add_view_hierarchy(options, "./view-hierarchy.json"); +void setup_scope(sentry_scope_t *scope, void *user_data) { + sentry_value_t attachment = sentry_attachment_from_file("./view-hierarchy.json"); + sentry_attachment_set_type(attachment, SENTRY_ATTACHMENT_TYPE_VIEW_HIERARCHY); + sentry_scope_add_attachment(scope, attachment); +} + +sentry_options_set_initial_scope(options, setup_scope, NULL); ``` diff --git a/docs/platforms/native/configuration/backends/native.mdx b/docs/platforms/native/configuration/backends/native.mdx index b99de28dfd3a4..ff56ce7912041 100644 --- a/docs/platforms/native/configuration/backends/native.mdx +++ b/docs/platforms/native/configuration/backends/native.mdx @@ -15,7 +15,27 @@ cmake -B build -D SENTRY_BACKEND=native This builds the `sentry-crash` executable alongside the `sentry` library. Ship the executable with your application so the SDK can start it during -initialization. +initialization. On Windows, it also builds the `sentry-wer.dll` module for +reporting fast-fail crashes via [Windows Error Reporting](/platforms/native/advanced-usage/windows-error-reporting/). +Ship it in the same directory as `sentry-crash.exe`. + +The SDK will automatically look for a `sentry-crash` executable in the same +directory as the running application. It will also use the `.sentry-native` +directory as its database by default, relative to the current working directory +of your application. +This location temporarily hosts crash reports before they are uploaded to Sentry. + +Both of these paths can be customized like this: + +```c +sentry_options_t *options = sentry_options_new(); +sentry_options_set_handler_path(options, "path/to/sentry-crash"); +sentry_options_set_database_path(options, "sentry-db-directory"); +sentry_init(options); +``` + +It is advised to specify both the path to the `sentry-crash` executable +as well as the path to the database directory manually. ## Crash Reporting Modes diff --git a/docs/platforms/native/user-feedback/index.mdx b/docs/platforms/native/user-feedback/index.mdx index 9c1f636461b6d..19bdc1b1598e4 100644 --- a/docs/platforms/native/user-feedback/index.mdx +++ b/docs/platforms/native/user-feedback/index.mdx @@ -16,12 +16,6 @@ Sentry pairs the feedback with the original event, giving you additional insight - - -`sentry_value_new_user_feedback` and `sentry_capture_user_feedback` are deprecated. They produce the older User Report envelope item, which doesn't carry scope data or attachments. Use `sentry_value_new_feedback` and `sentry_capture_feedback` instead. - - - ### What Gets Sent With Feedback diff --git a/platform-includes/configuration/drain-example/native.mdx b/platform-includes/configuration/drain-example/native.mdx index c969121fa8ab3..41e0dfa46e1d8 100644 --- a/platform-includes/configuration/drain-example/native.mdx +++ b/platform-includes/configuration/drain-example/native.mdx @@ -4,7 +4,7 @@ sentry_close(); ``` -Calling `sentry_close()` (formerly `sentry_shutdown()`) before exiting the application is critical to avoid +Calling `sentry_close()` before exiting the application is critical to avoid data loss. After closing, the client cannot be used anymore. It's important to only call diff --git a/platform-includes/getting-started-config/native.qt.mdx b/platform-includes/getting-started-config/native.qt.mdx index 171256d96bec7..59fdb1e664455 100644 --- a/platform-includes/getting-started-config/native.qt.mdx +++ b/platform-includes/getting-started-config/native.qt.mdx @@ -28,7 +28,7 @@ Alternatively, the DSN can be passed as `SENTRY_DSN` environment variable during -Calling `sentry_close()` (formerly `sentry_shutdown()`) before exiting the application is critical. It +Calling `sentry_close()` before exiting the application is critical. It ensures that events can be sent to Sentry before execution stops. Otherwise, event data may be lost. diff --git a/platform-includes/getting-started-install/native.mdx b/platform-includes/getting-started-install/native.mdx index 0b1b9212d4df9..60797e0b8d97f 100644 --- a/platform-includes/getting-started-install/native.mdx +++ b/platform-includes/getting-started-install/native.mdx @@ -1,26 +1,25 @@ -The Native SDK currently supports **Windows**, **macOS**, and **Linux**. The Native SDK also acts as an **Android** NDK support library in downstream SDKs via the [Android SDK](/platforms/android/configuration/using-ndk/), but currently does not directly support the platform. +The Native SDK currently supports **Windows**, **macOS**, and **Linux**. The Native SDK also acts as an **Android** NDK support library in downstream SDKs via the [Android SDK](/platforms/android/configuration/using-ndk/), but currently does not directly support the platform. **Nintendo Switch**, **PlayStation**, and **Xbox** are supported via Sentry's console SDKs. See the [Nintendo Switch](/platforms/nintendo-switch/), [PlayStation](/platforms/playstation/), and [Xbox](/platforms/xbox/) documentation to get access. To build the SDK, download the latest sources from the [Releases page](https://github.com/getsentry/sentry-native/releases). The SDK is managed as a [CMake] project, which additionally supports several configuration options, such as the backend to use. -For example, `CMake` can be used like this (on macOS): +For example, `CMake` can be used like this: -```shell +```shell {tabTitle:macOS} {mdExpandTabs} # When using CMake 4 ensure you have valid SDKROOT defined in your environment. export SDKROOT=$(xcrun --sdk macosx --show-sdk-path) -# Configure the CMake build into the `build` directory with crashpad (the default -# backend on macOS, thus optional to specify). Specifying `RelWithDebInfo` as the -# `CMAKE_BUILD_TYPE` is also optional because it is the default in sentry-native -# for all generators supporting it. -cmake -B build -D SENTRY_BACKEND=crashpad -D CMAKE_BUILD_TYPE=RelWithDebInfo +# Configure the CMake build into the `build` directory with the desired backend. +# Specifying `RelWithDebInfo` as the `CMAKE_BUILD_TYPE` is optional because it +# is the default in sentry-native for all generators supporting it. +cmake -B build -D SENTRY_BACKEND=native -D CMAKE_BUILD_TYPE=RelWithDebInfo # build the project cmake --build build --parallel # install the resulting artifacts into a specific prefix cmake --install build --prefix install -# which will result in the following (on macOS): -exa --tree install --level 2 +# which will result in the following: +eza --tree install --level 2 install ├── bin -│ └── crashpad_handler +│ └── sentry-crash ├── include │ └── sentry.h └── lib @@ -28,15 +27,34 @@ install ├── libsentry.dylib └── libsentry.dylib.dSYM ``` -(For further details on the `SDKROOT` usage with CMake please consult the [macOS build section in the SDK README](https://github.com/getsentry/sentry-native?tab=readme-ov-file#building-and-installation)) -Contrast the above with the build-steps for a typical `msbuild` project on Windows: +```shell {tabTitle:Linux} +# Configure the CMake build into the `build` directory with the desired backend. +# Specifying `RelWithDebInfo` as the `CMAKE_BUILD_TYPE` is optional because it +# is the default in sentry-native for all generators supporting it. +cmake -B build -D SENTRY_BACKEND=native -D CMAKE_BUILD_TYPE=RelWithDebInfo +# build the project +cmake --build build --parallel +# install the resulting artifacts into a specific prefix +cmake --install build --prefix install +# which will result in the following: +tree install -L 2 +install +├── bin +│ └── sentry-crash +├── include +│ └── sentry.h +└── lib + ├── cmake + └── libsentry.so + +5 directories, 3 files +``` -```shell +```shell {tabTitle:Windows} # The msbuild generator ignores the CMAKE_BUILD_TYPE because it contains all -# build-types. Here we leave out the backend specification and rely on CMake -# selecting crashpad as Windows' default backend. -cmake -B build +# build-types. +cmake -B build -D SENTRY_BACKEND=native # The actual build step then requires we specify which build-type we want # to apply via the `--config` parameter. Please be aware that in msbuild # projects, the `--parallel` option has no effect. @@ -46,8 +64,9 @@ cmake --install build --prefix install --config RelWithDebInfo # which will result in the following output (ignoring non-essential lines): tree /f install ├───bin -│ crashpad_handler.exe -│ crashpad_handler.pdb +│ sentry-crash.exe +│ sentry-wer.dll +│ sentry-wer.pdb │ sentry.dll │ sentry.pdb │ @@ -56,12 +75,16 @@ tree /f install │ └───lib │ sentry.lib + │ + └───cmake ``` +(For further details on the `SDKROOT` usage with CMake please consult the [macOS build section in the SDK README](https://github.com/getsentry/sentry-native?tab=readme-ov-file#building-and-installation)) + [cmake]: https://cmake.org/cmake/help/latest/ - + -When using the _Crashpad backend_, which is the default on all supported Desktop platforms (Windows, Linux and macOS), the `crashpad_handler` binary has to be shipped alongside the application binary. See the [Crashpad documentation](/platforms/native/configuration/backends/crashpad/) for more information. +The out-of-process _Native_ and _Crashpad_ backends require shipping `sentry-crash` or `crashpad_handler`, respectively, alongside the application binary. See the [Native](/platforms/native/configuration/backends/native/) and [Crashpad](/platforms/native/configuration/backends/crashpad/) backend documentation for more information. diff --git a/platform-includes/getting-started-install/native.qt.mdx b/platform-includes/getting-started-install/native.qt.mdx index e5d8718dc4bab..b63ea47814b8d 100644 --- a/platform-includes/getting-started-install/native.qt.mdx +++ b/platform-includes/getting-started-install/native.qt.mdx @@ -11,13 +11,13 @@ If the Qt libraries are not installed in one of the predefined `CMake` [system p -For example (on macOS): +For example: ```shell # Configure the cmake build into the `build` directory, -# with crashpad, and Qt integration (on macOS). +# with the desired backend, and Qt integration. cmake -B build \ - -D SENTRY_BACKEND=crashpad \ + -D SENTRY_BACKEND=native \ -D SENTRY_INTEGRATION_QT=YES # Build the project @@ -27,10 +27,10 @@ cmake --build build --parallel cmake --install build --prefix install # Which will result in the following (on macOS): -exa --tree install --level 2 +eza --tree install --level 2 install ├── bin -│ └── crashpad_handler +│ └── sentry-crash ├── include │ └── sentry.h └── lib @@ -43,8 +43,8 @@ You can configure the Qt build for Windows analogous to the [regular build instr [cmake]: https://cmake.org/cmake/help/latest/ - + -When using the _Crashpad backend_, which is the default on Windows and macOS, the `crashpad_handler` binary has to be shipped alongside the application binary. See the [Crashpad documentation](/platforms/native/configuration/backends/crashpad/) for more information. +The out-of-process _Native_ and _Crashpad_ backends require shipping `sentry-crash` or `crashpad_handler`, respectively, alongside the application binary. See the [Native](/platforms/native/configuration/backends/native/) and [Crashpad](/platforms/native/configuration/backends/crashpad/) backend documentation for more information. diff --git a/platform-includes/getting-started-primer/native.mdx b/platform-includes/getting-started-primer/native.mdx index a4dc3e80f01e8..9f406da892298 100644 --- a/platform-includes/getting-started-primer/native.mdx +++ b/platform-includes/getting-started-primer/native.mdx @@ -1,10 +1,15 @@ The Sentry Native SDK is intended for C and C++. However, since it builds as a dynamic library and exposes C-bindings, it can be used by any language that supports interoperability with C, such as the Foreign Function Interface (FFI). - +It also provides native crash reporting for other Sentry SDKs: -Using the `sentry-native` SDK in a standalone use case is currently an experimental feature. The SDK’s primary function is to fuel our other SDKs, like [`sentry-java`](https://github.com/getsentry/sentry-java) or [`sentry-unreal`](https://github.com/getsentry/sentry-unreal). Support from our side is best effort and we do what we can to respond to issues in a timely fashion, but please understand if we won’t be able to address your issues or feature suggestions. +- [_Android (NDK)_](/platforms/android/configuration/using-ndk/) +- [_Flutter_](/platforms/dart/guides/flutter/) +- [_Godot_](/platforms/godot/) +- [_.NET_](/platforms/dotnet/) +- [_Unity_](/platforms/unity/) +- [_Unreal Engine_](/platforms/unreal/) - +Sentry's console SDKs also build on the Native SDK. See the [Nintendo Switch](/platforms/nintendo-switch/), [PlayStation](/platforms/playstation/), and [Xbox](/platforms/xbox/) documentation to get access. Sentry also offers higher-level SDKs for platforms with built-in support for native crashes: diff --git a/platform-includes/performance/add-spans-example/native.mdx b/platform-includes/performance/add-spans-example/native.mdx index 2417637a1270c..14b5ff8900b03 100644 --- a/platform-includes/performance/add-spans-example/native.mdx +++ b/platform-includes/performance/add-spans-example/native.mdx @@ -61,7 +61,7 @@ perform_checkout(); The SDK will turn off managing automatic trace boundaries via transactions once manual management of trace boundaries was requested by either a downstream SDK (using `sentry_set_trace(trace_id, parent_span_id)`) or a direct user of the -Native SDK (via `sentry_regenerate_trace()`): +Native SDK (via `sentry_start_new_trace()`): ```C sentry_options_t *options = sentry_options_new(); @@ -86,10 +86,10 @@ sentry_options_t *options = sentry_options_new(); sentry_init(options); // Generates a new random trace and span id onto the propagation_context -sentry_regenerate_trace(); +sentry_start_new_trace(); authenticate_user(); -sentry_regenerate_trace(); +sentry_start_new_trace(); // Events, transactions, and spans inside perform_checkout() will be part of // a different trace than the ones inside authenticate_user() perform_checkout(); @@ -100,6 +100,6 @@ After the client called either function, the following transactions inherit that If you interact with the Native SDK in the context of a downstream SDK (for instance Android, .NET, Unity, or Unreal), we urge you not to use - `sentry_regenerate_trace()` since it would interfere with the traces managed + `sentry_start_new_trace()` since it would interfere with the traces managed from those SDKs.