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");
} ```
On 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();
if target_os == "macos" || target_os == "windows" {
let handler = env::var_os("DEP_SENTRY_NATIVE_CRASHPAD_HANDLER").unwrap();
let executable = if target_os == "macos" {
"crashpad_handler"
} else if target_os == "windows" {
"crashpad_handler.exe"
} else {
unreachable!()
};
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
std::panic::set_hook(Box::new(|_| sentry_contrib_native::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.
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 on any other platform than Windows, the development version of
curl is required.
See the Sentry Native SDK for more details.
winhttp on Windows
and curl everywhere else as the default transport.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.feature(external_doc)
and
feature(doc_cfg).When deploying a binary for MacOS or Windows, it 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.