Crate sentry_contrib_native

Expand description

sentry-contrib-native

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

For the bindings used: official documentation
For releases on crates.io: .
For the master branch: .

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 - .

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

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.

Re-exports

pub use http;

Structs

Breadcrumb

A Sentry breadcrumb.

Dsn

Contains the pieces that are needed to build correct headers for a request based on the given DSN.

Envelope

The actual body which transports send to Sentry.

Event

A Sentry event.

Options

The Sentry client options.

Parts

Parts aquired from Dsn::into_parts.

RawEnvelope

Wrapper for the raw envelope that we should send to Sentry.

Shutdown

Automatically shuts down the Sentry client on drop.

User

A Sentry user.

Uuid

A Sentry UUID.

Enums

Consent

The state of user consent.

Error

Errors for this crate.

Interface

Sentry event interface.

Level

Sentry event level.

Message

Message received for custom logger.

TransportError

Sentry errors.

TransportShutdown

The return from Transport::shutdown, which determines if we tell the Sentry SDK if we were able to send all requests to the remote service or not in the allotted time.

Value

Represents a Sentry protocol value.