Crate sentry_contrib_native[−][src]

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.
nightly - Enables full documentation through feature(external_doc) and feature(doc_cfg).

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

Currently, nightly is needed for full documentation: cargo doc --features nightly

If nightly isn’t available, use cargo doc as usual.

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.

Breadcrumb	A Sentry breadcrumb.
Dsn	`transport-custom` 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	`transport-custom` `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	`transport-custom` 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.

Constants

API_VERSION	Version of the Sentry API we can communicate with, AFAICT this is just hardcoded into sentry-native, so … two can play at that game!
ENVELOPE_MIME	The MIME type for Sentry envelopes.
SDK_USER_AGENT	SDK Version

Traits

BeforeSend	Trait to help pass data to `Options::set_before_send`.
Logger	Trait to help pass data to `Options::set_logger`.
Map	Convenience trait to simplify passing a `Value::Map`.
Transport	Trait used to define a custom transport that Sentry can use to send events to a Sentry service.

Functions

clear_modulecache	Clears the internal module cache.
end_session	Prematurely end a session before it is done automatically by `shutdown`.
modules_list	This will lazily load and cache a list of all the loaded libraries.
reinstall_backend	Re-initializes the Sentry backend.
remove_context	Removes the context object with the specified key.
remove_extra	Removes the extra with the specified `key`.
remove_fingerprint	Removes the fingerprint.
remove_tag	Removes the tag with the specified `key`.
remove_transaction	Removes the transaction.
remove_user	Removes a user.
set_context	Sets a context object.
set_extra	Sets extra information.
set_fingerprint	Sets the event fingerprint.
set_hook	Panic handler to send an `Event` with the current stacktrace to Sentry.
set_level	Sets the event level.
set_tag	Sets a tag.
set_transaction	Sets the transaction.
set_user_consent	Resets the user consent (back to unknown).
shutdown	Shuts down the Sentry client and forces transports to flush out.
start_session	Starts a new session. By default sessions are started automatically on `Options::init`.
user_consent	Checks the current state of user consent.

Type Definitions

Request

transport-custom

The http::Request request your Transport is expected to send.

Crate sentry_contrib_native[−][src]

sentry-contrib-native

Table of contents

Description

Branches

Usage

Platform support

Build

Crate features

Deployment

Documentation

Tests

Alternatives

Changelog

License

Contribution

Attribution

Re-exports

Structs

Enums

Constants

Traits

Functions

Type Definitions

Crate sentry_contrib_native⎘[−][src]

Crate sentry_contrib_native[−][src]