This crate has been deprecated in favor of crash-handler, a pure Rust alternative to relying on Sentry's C/C++ SDK.
See sentry-rust-minidump as well for more integration with Sentry.
- Description
- Branches
- Usage
- Build
- Crate features
- Deployment
- Documentation
- Tests
- Alternatives
- Changelog
- License
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.
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())));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.
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.
- 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.
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.
- For the bindings used: official documentation
- For releases on crates.io:
.
- For the master branch:
.
For correct testing the following has to be provided:
SENTRY_DSNenvironment variable has to contain a valid Sentry DSN URL.SENTRY_TOKENenvironment 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_DSNenvironment variable, no matter what is set throughOptions::set_dsn. - Automatically sets the database path to the
OUT_DIRenvironment variable, no matter what is set throughOptions::set_database_path. - Automatically puts the crashpad handler path to the correct path, taking into
account
SENTRY_NATIVE_INSTALL, no matter what is set throughOptions::set_handler_path.
cargo 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
- 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.
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 file for more details.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent