sentry-contrib-native

发布版:

主分支:

目录

• 描述
• 分支
• 使用方法
• 构建
• 代码包功能
• 部署
• 文档
• 测试
• 替代方案
• 变更日志
• 许可协议
  • 贡献
  • 归属

描述

非官方对Sentry Native SDK的Rust绑定。有关官方Sentry SDK的详细信息，请参阅替代方案部分。

此代码包的主要目的是允许应用程序在崩溃时向Sentry发送报告，而目前官方的Sentry SDK for Rust尚未覆盖此功能。

分支

• 发布版 - 仅用于发布。
• 主分支 - 用于活跃开发和PR。

使用方法

use sentry_contrib_native as sentry;
use sentry::{Event, Level, Options};
use std::ptr;

fn main() {
    // set up panic handler
    sentry::set_hook(None, None);
    // start Sentry
    let mut options = Options::new();
    options.set_dsn("your-sentry-dsn.com");
    let _shutdown = options.init().expect("failed to initialize Sentry");

    // send an event to Sentry
    Event::new_message(Level::Debug, None, "test");

    // this code triggers a crash, but it will still be reported to Sentry
    unsafe { *ptr::null_mut() = true; }

    // Sentry receives an event with an attached stacktrace and message
    panic!("application should have crashed at this point");
}

默认情况下，在Linux、MacOS和Windows上，Crashpad处理程序的可执行文件需要与应用程序一起分发。为了方便，Crashpad处理程序的可执行文件将被复制到Cargo的默认二进制输出文件夹，因此使用cargo run无需任何额外设置或配置即可正常工作。

如果您需要将Crashpad处理程序的可执行文件以编程方式导出到特定的输出路径，提供了一个“方便”的环境变量来帮助完成此操作：DEP_SENTRY_NATIVE_CRASHPAD_HANDLER。

以下是一个build.rs示例。

use std::{env, fs, path::Path};

static OUTPUT_PATH: &str = "your/output/path";

fn main() {
    let target_os = env::var_os("CARGO_CFG_TARGET_OS").unwrap();

    let handler = env::var_os("DEP_SENTRY_NATIVE_CRASHPAD_HANDLER").unwrap();
    let executable = if target_os == "windows" {
        "crashpad_handler.exe"
    } else {
        "crashpad_handler"
    };

    fs::copy(handler, Path::new(OUTPUT_PATH).join(executable)).unwrap();
}

如果您使用panic = abort，请确保在终止应用程序之前，让panic处理程序调用shutdown以刷新剩余的传输。

use sentry_contrib_native as sentry;

std::panic::set_hook(Box::new(|_| sentry::shutdown()));
// or with the provided hook
sentry::set_hook(None, Some(Box::new(|_| sentry::shutdown())));

平台支持

目前，以下系统已通过CI进行了测试

• x86_64-unknown-linux-gnu
• x86_64-apple-darwin
• aarch64-apple-darwin (仅构建)
• x86_64-pc-windows-msvc

有关更多详细信息，请参阅CI本身。有关更多平台和功能支持细节，请参阅Sentry Native SDK，这个crate没有做任何特别的事情，所以我们主要依赖sentry-native进行支持。

Linux的默认后端已从Breakpad更改为Crashpad。

Android的默认传输已从无更改为Curl。

包括系统共享zlib的默认行为已被禁用，并改为从源代码构建。

CIC中仅测试了默认后端。

构建

此crate依赖于sentry-contrib-native-sys，该crate反过来又构建Sentry的Native SDK。这需要CMake。

作为替代方案，可以通过SENTRY_NATIVE_INSTALL环境变量提供Sentry的Native SDK的预构建版本的路径。如果没有在该路径下找到，sentry-contrib-native-sys将使用该路径作为构建输出。

此外，如果使用Android、Linux和MacOS上的transport-default功能，则需要Curl的开发版本。例如，在Ubuntu上，您可以使用libcurl4-openssl-dev包。

有关更多详细信息，请参阅Sentry Native SDK。

代码包功能

• transport-default - 默认启用，将在Windows上使用WinHttp，在其他所有地方使用Curl作为默认传输。
• backend-crashpad - 将使用Crashpad。
• backend-breakpad - 将使用Breakpad。
• backend-inproc - 将使用InProc。
• transport-custom - 为自定义传输添加辅助类型和方法。
• nightly - 通过feature(external_doc)和feature(doc_cfg)启用完整文档。

默认情况下，选定的后端将是Linux、MacOS和Windows上的Crashpad，以及Android上的InProc，即使没有相应的功能也如此。有关后端的更多信息，请参阅SENTRY_BACKEND。

部署

如果使用Crashpad后端（Linux、MacOS或Windows上的默认后端），则应用程序必须与crashpad_handler(.exe)可执行文件一起分发。通过DEP_SENTRY_NATIVE_CRASHPAD_HANDLER提供了使用build.rs进行编程导出的方法。

请参阅使用部分以获取示例。

文档

• 关于所使用的绑定：官方文档
• 关于crates.io上的发布：。
• 关于主分支：。

目前，需要使用nightly才能获得完整的文档：cargo doc --features nightly

如果nightly不可用，则像往常一样使用cargo doc。

测试

为了正确测试，以下信息必须提供

• SENTRY_DSN环境变量必须包含有效的Sentry DSN URL。
• SENTRY_TOKEN环境变量必须包含一个有效的Sentry API Token，具有对“组织”、“项目”和“问题 & 事件”的读取权限。

测试可能会消耗大量事件，因此您可能不希望暴露Sentry API令牌，因此建议在Sentry onpremise服务器上运行测试，设置相当简单。

当测试时，隐藏的cargo功能test会自动激活。它有以下影响

• 自动将DSN设置为SENTRY_DSN环境变量，无论通过Options::set_dsn设置的是什么。
• 自动将数据库路径设置为OUT_DIR环境变量，无论通过Options::set_database_path设置的是什么。
• 自动将crashpad处理器路径放置到正确的路径，考虑到SENTRY_NATIVE_INSTALL，无论通过Options::set_handler_path设置的是什么。

cargotest

替代方案

建议使用Sentry的官方Rust SDK：sentry - 。

官方SDK提供更好的用户体验和定制性。

相比之下，这个crate可以提供的唯一优点是应用程序崩溃处理，Rust的官方SDK只能处理panic。

变更日志

有关详细信息，请参阅CHANGELOG文件。

许可协议

许可协议为以下之一

• Apache License，版本2.0（LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）
• MIT许可证（LICENSE-MIT 或 http://opensource.org/licenses/MIT）

由您选择。

贡献

除非您明确表示，否则根据Apache-2.0许可证定义的您有意提交以包含在本作品中的任何贡献，均将按上述方式双重许可，不附加任何额外的条款或条件。

归属

使用的文档来自Sentry Native SDK：MIT

有关更多详细信息，请参阅ATTRIBUTION文件。