Skip to content

Latest commit

 

History

History
267 lines (197 loc) · 10 KB

README.md

File metadata and controls

267 lines (197 loc) · 10 KB
Raw

sentry-contrib-native

Crates.io Libraries.io Commits since License LoC

Release: Build Docs

Master: Build Docs

Table of contents

Description

Unofficial bindings to the Sentry Native SDK for Rust. See the Alternatives section for details on the official Sentry SDK for Rust.

This crates main purpose is to enable an application to send reports to Sentry even if it crashes, which is currently not covered by the official Sentry SDK for Rust.

Branches

  • release - For releases only.
  • master - For active development inluding PR's.

Usage

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");
}

By default, on Linux, MacOS and Windows the Crashpad handler executable has to be shipped with the application, for convenience the Crashpad handler executable will be copied to Cargo's default binary output folder, so using cargo run works without any additional setup or configuration.

If you need to export the Crashpad handler executable programmatically to a specific output path, a "convenient" environment variable is provided to help with that: DEP_SENTRY_NATIVE_CRASHPAD_HANDLER.

Here is an example 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();
}

If you are using panic = abort make sure to let the panic handler call shutdown to flush remaining transport before aborting the application.

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())));

Platform support

Currently the following systems are tested with CI:

  • x86_64-unknown-linux-gnu
  • x86_64-apple-darwin
  • aarch64-apple-darwin (building only)
  • x86_64-pc-windows-msvc

See the CI itself for more detailed information. See the Sentry Native SDK for more platform and feature support details there, this crate doesn't do anything fancy, so we mostly rely on sentry-native for support.

The default backend for Linux is changed from Breakpad to Crashpad.

The default transport for Android is changed from none to Curl.

The default behaviour of including the system shared zlib is disabled and instead built from source.

Only the default backend is tested in the CI.

Build

This crate relies on sentry-contrib-native-sys which in turn builds Sentry's Native SDK. This requires CMake.

Alternatively a path to a pre-built version of Sentry's Native SDK can be provided with the SENTRY_NATIVE_INSTALL environment variable. If none is found at that path, sentry-contrib-native-sys will use that path as the build output.

Additionally, if the transport-default feature on Android, Linux and MacOS is used, the development version of Curl is required. For example on Ubuntu you can use the libcurl4-openssl-dev package.

See the Sentry Native SDK for more details.

Crate features

  • transport-default - Enabled by default, will use WinHttp on Windows and Curl everywhere else as the default transport.
  • backend-crashpad - Will use Crashpad.
  • backend-breakpad - Will use Breakpad.
  • backend-inproc - Will use InProc.
  • transport-custom - Adds helper types and methods to custom transport.

By default the selected backend will be Crashpad for Linux, MacOS and Windows and InProc for Android, even if no corresponding feature is active. See SENTRY_BACKEND for more information on backends.

Deployment

If the Crashpad backend is used, which is the default on Linux, MacOS or Windows, the application has to be shipped together with the crashpad_handler(.exe) executable. A way to programmatically export it using build.rs is provided through the DEP_SENTRY_NATIVE_CRASHPAD_HANDLER.

See the Usage section for an example.

Documentation

Tests

For correct testing the following has to be provided:

  • SENTRY_DSN environment variable has to contain a valid Sentry DSN URL.
  • SENTRY_TOKEN environment variable has to contain a valid Sentry API Token with read access to "Organization", "Project" and "Issue & Event".

Tests may easily exhaust large number of events and you may not want to expose a Sentry API token, therefore it is recommended to run tests against a Sentry onpremise server, it is quiet easy to set up.

The hidden cargo feature test is automatically activated when testing. It has the following effects:

  • Automatically sets the DSN to the SENTRY_DSN environment variable, no matter what is set through Options::set_dsn.
  • Automatically sets the database path to the OUT_DIR environment variable, no matter what is set through Options::set_database_path.
  • Automatically puts the crashpad handler path to the correct path, taking into account SENTRY_NATIVE_INSTALL, no matter what is set through Options::set_handler_path.

cargo test

Alternatives

It's recommended to use Sentry's official SDK for Rust: sentry - Crates.io.

The official SDK provides a much better user experience and customizability.

In comparison the only upside this crate can provide is application crash handling, the official SDK for Rust can only handle panics.

Changelog

See the CHANGELOG file for details.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Attribution

Used documentation from Sentry Native SDK: MIT

See the ATTRIBUTION file for more details.