getsentry/sentry-native

[](https://conan.io/center/recipes/sentry-native) [](https://formulae.brew.sh/formula/sentry-native) [](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/se/sentry-native/package.nix) [](https://vcpkg.link/ports/sentry-native)

# Sentry C/C++ 官方 SDK [](https://github.com/getsentry/sentry-native/actions) [](https://codecov.io/gh/getsentry/sentry-native) _Sentry Native SDK_ 是一个面向原生应用的错误和崩溃报告客户端，专为 C 和 C++ 优化。Sentry 允许添加标签、面包屑和任意自定义上下文，以丰富错误报告。支持 Sentry _20.6.0_ 及更高版本。 ### 注意 在独立用例中使用 `sentry-native` SDK 目前是一个实验性功能。该 SDK 的主要功能是为我们其他的 SDK 提供支持，例如 [`sentry-java`](https://github.com/getsentry/sentry-java) 或 [`sentry-unreal`](https://github.com/getsentry/sentry-unreal)。我们将尽最大努力提供支持，并会尽快回应相关问题，但请理解，我们可能无法解决您的所有问题或功能建议。 ## 资源 - [SDK 文档](https://docs.sentry.io/platforms/native/) - 用于项目讨论的 [Discord](https://discord.gg/sentry) 服务器 - 在 X 上关注 [@sentry](https://x.com/sentry) 获取更新 ## 目录 - [下载](#downloads) - [包含内容](#what-is-inside) - [平台与功能支持](#platform-and-feature-support) - [构建与安装](#building-and-installation) - [编译时选项](#compile-time-options) - [构建目标](#build-targets) - [运行时配置](#runtime-configuration) - [已知限制](#known-limitations) - [开发](#development) ## 下载 可以从 [Releases] 页面下载该 SDK，该页面还列出了每个版本的更新日志。我们建议使用我们的发布包，但如果您想直接使用此仓库，请遵循[贡献指南](./CONTRIBUTING.md) 以更好地了解相关设置。 ### 包含内容 该 SDK 压缩包包含以下文件夹： - `include`：包含 Sentry 的头文件。请将 include 路径设置为此目录，或将头文件复制到您的源码树中，以便在构建时可用。 - `src`：构建所需的 Sentry SDK 源码。 - `ndk`：Android NDK JNI 层的源码。 - `external`：这些是通过 git submodule 获取的第三方依赖（如果您使用 git clone 而不是发布包，请使用 `git submodule update --init --recursive`）。 ## 平台与功能支持 该 SDK 目前支持并在以下操作系统/编译器组合上进行了测试： - x64/arm64 Linux 配合 GCC 14 - x64 Linux 配合 GCC 12 - x64 Linux 配合 GCC 9 - x64/arm64 Linux 配合 clang 19 - x86 Linux 配合 GCC 9（从 x64 主机交叉编译） - x86、x64 和 arm64 Windows 配合 MSVC 2022 - macOS 13、14、15、26 配合各自最新的 Apple 编译器工具链以及 LLVM clang 15 + 18 - 使用 NDK27 工具链构建的 Android API35 - 使用 NDK19 工具链构建的 Android API16 - 通过 [sentry-playstation](https://github.com/getsentry/sentry-playstation) 支持 PlayStation。请参阅 [PlayStation 文档](https://docs.sentry.io/platforms/playstation/) 获取访问权限。 - 通过 [sentry-xbox](https://github.com/getsentry/sentry-xbox) 支持 Xbox。请参阅 [Xbox 文档](https://docs.sentry.io/platforms/xbox/) 获取访问权限。 - 通过 [sentry-switch](https://github.com/getsentry/sentry-switch) 支持 Nintendo Switch。请参阅 [Nintendo Switch 文档](https://docs.sentry.io/platforms/nintendo-switch/) 获取访问权限。 此外，该 SDK 应当支持以下平台，尽管未进行自动化测试，因此可能会出现兼容性问题： - 低于 Windows 10 / Windows Server 2016 的 Windows 版本 - 使用 MSYS2 + MinGW + Clang 工具链的 Windows 构建（也会在 CI 中运行） 该 SDK 在目标平台上支持不同的功能： - **HTTP Transport** 目前仅在 Windows 和有 `curl` 库可用的平台上受支持。在其他平台上，库用户需要基于 `function transport` API 实现自己的 transport。 - **Crashpad Backend** 目前仅在 Linux、Windows 和 macOS 上受支持。 - **客户端栈回溯** 目前仅在 Linux、Windows 和 macOS 上受支持。 ## 构建与安装 该 SDK 作为 [CMake] 项目进行开发和发布。 CMake 会根据平台自动选择合适的编译器和构建系统工具链，并且还可以配置为交叉编译。 也可以通过 CMake 对生成的 Sentry 库进行系统范围的安装。 构建的前提条件因平台和后端而异。您始终需要 `CMake` 来构建代码。此外，当使用 `crashpad` 后端时，需要用到 `zlib`。在 Linux 和 macOS 上，`libcurl` 是一个前提条件。有关更多详细信息，请查看[贡献指南](./CONTRIBUTING.md)。 构建 Breakpad 和 Crashpad 后端需要兼容 `C++17` 的编译器。 **构建示例**： ``` # 配置 cmake 构建到 `build` 目录，并附带 crashpad（在 macOS 上） $ cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo # 构建项目 $ cmake --build build --parallel # 将生成的 artifacts 安装到特定的 prefix 中（在 Windows 上使用正确的 config） $ cmake --install build --prefix install --config RelWithDebInfo # 将会产生以下结果（在 macOS 上）： $ exa --tree install install ├── bin │ └── crashpad_handler ├── include │ └── sentry.h └── lib ├── cmake │ └── sentry ├── libsentry.dylib └── libsentry.dylib.dSYM ``` 更多详细信息，请参阅 CMake 手册。 **Android**： CMake 项目也可以配置为与 Android NDK 正常配合使用，有关如何将其与 Gradle 集成或在命令行上使用的详细信息，请参阅专门的 [CMake Guide]。 `ndk` 文件夹提供了一个为 Android 添加 Java JNI 层的 Gradle 项目，适合从 Java 访问 sentry-native SDK。有关此主题的更多详细信息，请参阅 [NDK Readme]。 **MinGW**： 目前仅支持 64 位平台。 此处必须使用 LLVM + Clang：生成 .pdb 文件需要用到它们，而 Crashpad 在生成报告时需要使用 .pdb 文件。 为了使您的应用程序生成相应的 .pdb 输出，您需要在应用程序目标上激活 CodeView 文件格式生成。为此，请使用类似 `target_compile_options(${yourApplicationTarget} PRIVATE -gcodeview)` 的内容更新您自己的 CMakeLists.txt。 如果您使用 MSYS2 环境进行 MinGW 编译，请确保： - 创建一个名为 `MINGW_ROOT` 的环境变量（例如：`C:/msys64/mingw64`） - 从 `mingw64.exe` 中运行：`pacman -S --needed - < ./toolchains/msys2-mingw64-pkglist.txt` - 按如下方式进行构建： ``` # 使用 Ninja 作为 generator 进行配置，并使用 MSYS2 toolchain 文件 $ cmake -GNinja -Bbuild -H. -DCMAKE_TOOLCHAIN_FILE=toolchains/msys2.cmake # 使用 Ninja 构建 $ ninja -C build ``` **MacOS**： 使用 [`CMAKE_OSX_ARCHITECTURES`](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html) 变量，无论是使用 `Xcode` 生成器还是默认生成器，都可以直接构建通用二进制文件/库： ``` # 使用 Xcode generator： $ cmake -B xcodebuild -GXcode -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" $ xcodebuild build -project xcodebuild/Sentry-Native.xcodeproj $ lipo -info xcodebuild/Debug/libsentry.dylib Architectures in the fat file: xcodebuild/Debug/libsentry.dylib are: x86_64 arm64 # 使用默认 generator： $ cmake -B defaultbuild -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" $ cmake --build defaultbuild --parallel $ lipo -info defaultbuild/libsentry.dylib Architectures in the fat file: defaultbuild/libsentry.dylib are: x86_64 arm64 ``` 确保使用 macOS SDK 11 或更高版本（我们目前仅针对 13 及以上版本进行测试）。这可能需要指定 `SDKROOT`： ``` $ export SDKROOT=$(xcrun --sdk macosx --show-sdk-path) ``` 如果您在 macOS 上使用 _CMake 4_ 进行构建，那么您_必须_指定 `SDKROOT`，因为 [CMake 4 默认将 `CMAKE_OSX_SYSROOT` 设为空](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html)，这可能会导致 CMake 在稍后构建中尝试收集 `sysroot` 时出现包含路径不一致的情况。 ### 编译时选项 在运行 cmake 生成器时可以设置以下选项，例如使用 `cmake -D BUILD_SHARED_LIBS=OFF ..`。 - `SENTRY_BUILD_SHARED_LIBS`（默认：`ON`）： 默认情况下，`sentry` 被构建为共享库。将此选项设置为 `OFF` 会将 `sentry` 构建为静态库。 如果 sentry 作为另一个项目的子目录使用，默认情况下将继承 `BUILD_SHARED_LIBS` 的值。 当将 `sentry` 用作静态库时，请确保在包含 sentry 头文件之前加上 `#define SENTRY_BUILD_STATIC 1`。 - `SENTRY_PIC`（默认：`ON`）： 默认情况下，`sentry` 被构建为位置无关库。 - `SENTRY_BUILD_RUNTIMESTATIC`（默认：`OFF`）： 启用与静态 MSVC runtime 的链接。如果编译器不是 MSVC，则无效。 - `SENTRY_LINK_PTHREAD`（默认：`ON`）： 在 UNIX 目标上链接平台线程库，如 `pthread`。 - `SENTRY_BUILD_FORCE32`（默认：`OFF`）： 强制从 64 位主机交叉编译到 32 位目标。仅影响 Linux。 - `CMAKE_SYSTEM_VERSION`（默认：取决于 Windows SDK 版本）： 设置可以保证 sentry-native 运行的最低 Windows 版本。 可选值： - `5.1` (Windows XP) - `5.2` (Windows XP 64-bit / Server 2003 / Server 2003 R2) - `6.0` (Windows Vista / Server 2008) - `6.1` (Windows 7 / Server 2008 R2) - `6.2` (Windows 8.0 / Server 2012) - `6.3` (Windows 8.1 / Server 2012 R2) - `10` (Windows 10 / Server 2016 / Server 2019) 对于低于 `6.0` 的 Windows 版本，如果使用 MSVC 编译器，还需要使用 XP 工具链（将 `-T v141_xp` 传递给 CMake 命令行）。 - `SENTRY_TRANSPORT`（默认：取决于平台）： Sentry 可以使用不同的 HTTP 库将报告发送到服务器。 - **curl**：使用 `curl` 库进行 HTTP 处理。这要求该包的开发版本可用。 - **winhttp**：使用 `winhttp` 系统库，仅在 Windows 上受支持，并且是那里的默认选项。 - **none**：不构建任何 HTTP transport。如果用户想自己处理上传，则应使用此选项。 - `SENTRY_BACKEND`（默认：取决于平台）： Sentry 可以根据平台使用不同的后端。 - **crashpad**：使用进程外的 crashpad 处理程序。目前仅在桌面操作系统上受支持，并在 Windows、Linux 和 macOS 上作为默认选项。 - **breakpad**：使用进程内的 breakpad 处理程序。目前仅在桌面操作系统上受支持。 - **inproc**：一个支持所有平台的小型进程内处理程序，并在 Android 上作为默认选项。 - **native**：**(实验性)** 一个进程外的崩溃处理程序，使用轻量级守护进程来监控应用程序、生成 minidump 并发送崩溃报告。支持 Linux、macOS 和 Windows。兼容 TSAN 和 ASAN 清理器。此后端正在积极开发中。 - **none**：这将构建没有后端的 `sentry-native`，因此它不处理崩溃。主要用于测试。 - `SENTRY_INTEGRATION_QT`（默认：`OFF`）： 构建 Qt 集成，将 Qt 日志消息转换为面包屑。 - `SENTRY_BREAKPAD_SYSTEM`（默认：`OFF`）： 指示构建系统使用系统安装的 breakpad 库，而不是树内版本。 - `SENTRY_LIBUNWIND_SYSTEM`（默认：`OFF`，仅适用于 Linux）： 指示构建系统使用系统安装的 `libunwind`（通过 `pkg-config` 找到），而不是 `vendor/libunwind` 中的自带副本。 与始终构建为静态存档并链接到生成的共享库中或与其他静态构建产物放在一起的自带 `libunwind` 相反，当 `SENTRY_LIBUNWIND_SYSTEM=ON` 时，库的类型（共享或静态）由主机发行版的包决定。`SENTRY_BUILD_SHARED_LIBS` 选项仅控制如何将依赖项暴露给使用它的 CMake 项目，而不控制系统 `libunwind` 本身的库类型。使用系统包时，请确保构建和目标环境相匹配。 - `SENTRY_TRANSPORT_COMPRESSION`（默认：`OFF`）： 添加 Gzip transport 压缩。需要 `zlib`。 - `SENTRY_FOLDER`（默认：未定义）： 为支持项目层级的生成器（如 Microsoft Visual Studio）设置 sentry-native 项目文件夹名称。要使用此功能，您需要通过 [`USE_FOLDERS` property](https://cmake.org/cmake/help/latest/prop_gbl/USE_FOLDERS.html) 启用层级结构。 - `CRASHPAD_ENABLE_STACKTRACE`（默认：`OFF`）： 这在使用 crashpad 后端时启用客户端栈回溯。栈展开将在客户端计算机上执行，并且结果将作为附件提交给 Sentry 并附加到生成的 minidump 中。**请注意，此功能目前仍实验阶段**。 - `SENTRY_SDK_NAME`（默认：`sentry.native` 或 `sentry.native.android`）： 设置应包含在报告事件中的 SDK 名称。如果您覆盖此项，还需在包含 `sentry.h` 的您自己的目标上使用 `target_compile_definitions()` 定义相同的值。 - `SENTRY_HANDLER_STACK_SIZE`（默认：`64`）： 以 KiB 为单位指定为崩溃处理程序保留的栈大小（包括 Windows、Linux 上的 `on_crash` 和 `before_send` 等 hook，以及 macOS 上的 `inproc` 后端）。在发生栈溢出时，保留栈是必要的，否则处理程序可能无法继续执行。此参数允许用户以 KiB 为单位指定目标栈大小，因为某些应用程序可能需要与我们的默认值不同的值。该值可以小至 16KiB（在 `crashpad` 和 `breakpad` 上）以保证处理程序正常工作，但我们建议将 64 位系统上的下限设为 32KiB。**该值应为页面大小的倍数**。 - `SENTRY_THREAD_STACK_GUARANTEE_FACTOR`（默认：`10`，仅适用于 Windows）： 定义线程的栈保留空间必须超过指定处理程序保证大小的倍数。 _示例_：如果 `SENTRY_HANDLER_STACK_SIZE` 定义为 64KiB，则该线程的栈保留空间必须至少为 640KiB。 - `SENTRY_THREAD_STACK_GUARANTEE_AUTO_INIT`（默认：`ON`，仅适用于 Windows）： 确保在 SDK 初始化之后创建的所有线程都将配置为使用 `SENTRY_HANDLER_STACK_SIZE` 作为其处理程序的栈保证。 _注意_：将其分配给所有线程仅在将 SDK 构建为共享库时有效。如果将其构建为静态库，并且启用了此选项，则只有 `sentry_init()` 所在线程会拥有处理程序的栈保证（其他线程必须通过 `sentry_set_thread_stack_guarantee()` 手动初始化）。 - `SENTRY_THREAD_STACK_GUARANTEE_VERBOSE_LOG`（默认：`OFF`，仅适用于 Windows）： 为每次成功设置的线程栈保证添加 info 级别的日志。此项默认为 `OFF`，因为根据（所有依赖项）使用的线程数量，这可能会淹没日志。但这对于任何调整线程栈保证参数的人来说都会很有帮助。在设置线程栈保证的过程中出现的警告和错误将始终被记录。 ### 支持矩阵 | 功能 | Windows | macOS | Linux | Android | iOS | |------------|---------|-------|-------|---------|------| | Transports | | | | | | | - curl | | ☑ | ☑ | (✓)** | | | - winhttp | ☑ | | | | | | - none | ✓ | ✓ | ✓ | ☑ | ☑ | | | | | | | | | Backends | | | | | | | - crashpad | ☑ | ☑ | ☑ | | | | - breakpad | ✓ | ✓ | ✓ | (✓)* | (✓)* | | - inproc | ✓ | ✓ | ✓ | ☑ | | | - none | ✓ | ✓ | ✓ | ✓ | | 图例： - ☑ 默认 - ✓ 支持 - (✓) 支持但有限制 - `*`：Android 和 iOS 上的 `breakpad` 可以构建，并且按照上游说明应当可以工作，但未经测试。 - `**`：作为 transport 的 `curl` 可以在 Android 上运行，但在任何受支持的配置中并未使用它，以减小我们的构建产物体积。 除了平台支持之外，SDK 文档的“高级用法”部分现在还[描述了](https://docs.sentry.io/platforms/native/advanced-usage/backend-tradeoffs/) 在为特定用例选择合适的后端时所涉及的权衡。 ### 构建目标 - `sentry`：这是主库，也是唯一的默认构建目标。 - `crashpad_handler`：当配置了 `crashpad` 后端时，这是进程外的崩溃处理程序，需要将其与项目的可执行文件一起安装。 - `sentry_test_unit`：这些是主要的单元测试，通过顶层 makefile 构建也非常方便。 - `sentry_example`：这是一个突出展示 API 的小型示例程序，可以通过命令行参数进行控制，同时也用于集成测试。 ## 运行时配置 一个最小工作示例如下所示。有关更详细的示例，请参见 [example.c](examples/example.c) 文件，该文件也用于运行 sentry 的集成测试。 ``` sentry_options_t *options = sentry_options_new(); sentry_options_set_dsn(options, "https://YOUR_KEY@oORG_ID.ingest.sentry.io/PROJECT_ID"); sentry_init(options); // your application code … sentry_close(); ``` 其他重要的配置选项包括： - `sentry_options_set_database_path`：Sentry 需要在应用程序重启期间持久化一些缓存数据，特别是为了正确处理 release health 会话。建议设置一个与应用程序缓存目录相对应的显式绝对路径（相当于 Windows 上的 `AppData/Local` 和 Linux 上的 `XDG_CACHE_HOME`）。Sentry 应该有自己独立的目录，不要与其他应用程序数据共享，因为 SDK 将枚举并可能删除该目录中的文件。例如可以是 `$XDG_CACHE_HOME/your-app/sentry`。 如果未显式设置，Sentry 将在当前工作目录中创建并使用 `.sentry-native` 目录。 - `sentry_options_set_handler_path`：使用 crashpad 后端时，Sentry 将在正在运行的可执行文件所在的同一目录中查找 `crashpad_handler` 可执行文件。建议根据应用程序的安装位置将其设置为显式的绝对路径。 - `sentry_options_set_release`：Sentry 中的某些功能（包括 release health）需要设置发布版本。这对应于应用程序的版本，需要显式设置。有关更多信息，请参见 [Releases](https://docs.sentry.io/product/releases/)。 ## 已知限制 - macOS 上的 crashpad 后端目前不支持通知崩溃进程，因此无法正确终止会话或调用已注册的 `before_send` 或 `on_crash` hook。它还会丢失在崩溃发生时排队等待发送的所有事件。 - 在 Windows 上，crashpad 和 native 后端支持快速失败崩溃，这主要出于安全原因绕过了 SEH（结构化异常处理）。`sentry-native` 注册了一个 WER（Windows 错误报告）模块，当发生快速失败崩溃时，该模块会向进程外的崩溃处理程序发送信号。 但是由于此过程绕过了 SEH，因此不再调用应用程序的本地异常处理程序，这也意味着对于这些类型的崩溃，在发送崩溃报告之前不会调用 `before_send` 和 `on_crash`，因此不会产生任何作用。 ## 基准测试 每次推送到 `master` 分支时，SDK 都会在 CI 中自动进行基准测试。基准测试涵盖以下场景： - **SDK 初始化时间**：测量 `sentry_init()` 调用的持续时间，代表 SDK 的整体初始化时间。 - **后端启动时间**：SDK 初始化时间的一个子集，侧重于初始化 `inproc`、`breakpad` 或 `crashpad` 后端所需的时间。 基准测试在 Windows、macOS 和 Linux 上运行，结果发布在 [GitHub Pages](https://getsentry.github.io/sentry-native/) 上。 如果您想在本地运行基准测试，请遵循[贡献指南](./CONTRIBUTING.md) 中的说明。 ## 开发 请参阅[贡献指南](./CONTRIBUTING.md)。

标签：Bash脚本, C/C++, Sentry, SOC Prime, 事务性I/O, 客户端加密, 崩溃报告, 开发工具, 异常监控, 错误追踪