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.
```rust,shouldpanic use sentrycontrib_native as sentry; use sentry::{Event, Level, Options}; use std::ptr;
fn main() { // set up panic handler sentry::sethook(None, None); // start Sentry let mut options = Options::new(); options.setdsn("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.
```rust,no_run use std::{env, fs, path::Path};
static OUTPUT_PATH: &str = "your/output/path";
fn main() { let targetos = env::varos("CARGOCFGTARGET_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.
```rust use sentrycontribnative as sentry;
std::panic::sethook(Box::new(|| sentry::shutdown())); // or with the provided hook sentry::sethook(None, Some(Box::new(|| sentry::shutdown()))); ```
Currently the following systems are tested with CI:
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.
Only the default backend is tested in the CI.
This crate relies on
sentry-contrib-native-sys
which in turn builds
Sentry's Native SDK. This requires
CMake or alternatively a pre-installed version can be
provided with the SENTRY_NATIVE_INSTALL environment variable.
Additionally, if the transport-default feature on Android, Linux and MacOS is
used, the development version of Curl is required.
See the Sentry Native SDK for more details.
SENTRY_BACKEND at the
Sentry Native SDK.SENTRY_BACKEND at the
Sentry Native SDK.SENTRY_BACKEND at the
Sentry Native SDK.SENTRY_BACKEND at the
Sentry Native SDK.feature(external_doc)
and
feature(doc_cfg).SENTRY_DSN environment variable, no
matter what is set through Options::set_dsn.OUT_DIR environment variable,
no matter what is set through Options::set_database_path.SENTRY_NATIVE_INSTALL, no matter what is set through
Options::set_handler_path.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.
.
.Currently, nightly is needed for full documentation:
cargo doc --features nightly
If nightly isn't available, use cargo doc as usual.
For correct testing the following has to be provided:
feature = "test" has to be enabled.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.
cargo test --features test
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.
See the CHANGELOG file for details.
Licensed under either of
at your option.
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.
Used documentation from Sentry Native SDK: MIT
See the ATTRIBUTION for more details.