Crates.io | sentry-contrib-native |
lib.rs | sentry-contrib-native |
version | 0.3.1 |
source | src |
created_at | 2020-06-09 10:51:19.635302 |
updated_at | 2021-04-23 13:39:27.76175 |
description | Unofficial bindings to the Sentry Native SDK for Rust. |
homepage | |
repository | https://github.com/daxpedda/sentry-contrib-native |
max_upload_size | |
id | 251861 |
size | 281,274 |
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:
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.
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.
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:
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:
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
.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
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.