sentry-contrib-native
Table of contents
- Description
- Branches
- Usage
- Build
- Crate features
- Deployment
- Documentation
- Tests
- Alternatives
- Changelog
- License
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
Usage
use sentry_contrib_native as sentry;
use ;
use ptr;
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 ;
static OUTPUT_PATH: &str = "your/output/path";
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;
set_hook;
// or with the provided hook
set_hook;
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)
andfeature(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 throughOptions::set_dsn
. - Automatically sets the database path to the
OUT_DIR
environment 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
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.
Contribution
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.
Attribution
Used documentation from Sentry Native SDK: MIT
See the ATTRIBUTION file for more details.