[−][src]Crate sentry_contrib_native
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 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"); }
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
.
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(); 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.
std::panic::set_hook(Box::new(|_| sentry_contrib_native::shutdown()));
Platform support
Currently the following systems are tested with CI:
- x86_64-unknown-linux-gnu
- x86_64-apple-darwin
- 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.
Build
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.
Crate features
- default-transport - Enabled by default, will use
winhttp
on Windows andcurl
everywhere else as the default transport. - custom-transport - Adds helper types and methods to custom transport.
- test - Corrects testing for documentation tests and examples.
- 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 crashhandler path to the correct path, taking into
account
SENTRY_NATIVE_INSTALL
, no matter what is set throughOptions::set_handler_path
.
- Automatically sets the DSN to the
- nightly - Enables full documentation through
feature(external_doc)
andfeature(doc_cfg)
.
Deployment
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.
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:
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 setup.
cargo test --features 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 for more details.
Re-exports
pub use http; |
Structs
Breadcrumb | A Sentry breadcrumb. |
Dsn | feature="custom-transport" Contains the pieces we need to send requests based on the DSN the user
set on |
Envelope | The actual body which transports send to Sentry. |
Event | A Sentry event. |
Options | The Sentry client options. |
Parts | feature="custom-transport"
|
RawEnvelope | Wrapper for the raw Envelope that we should send to Sentry. |
Shutdown | Automatically shuts down the Sentry client on drop. |
User | A Sentry user. |
Uuid | A Sentry UUID. |
Enums
Consent | The state of user consent. |
Error | [ |
Interface | Sentry event interface. |
Level | Sentry event level. |
Message | Message received for custom logger. |
TransportError | feature="custom-transport" Sentry errors. |
TransportShutdown | The return from |
Value | Represents a Sentry protocol value. |
Constants
API_VERSION | Version of the Sentry API we can communicate with, AFAICT this is just hardcoded into sentry-native, so...two can play at that game! |
ENVELOPE_MIME | The MIME type for Sentry envelopes. |
SDK_USER_AGENT | SDK Version |
Traits
BeforeSend | Trait to help pass data to |
Transport | Trait used to define a custom transport that Sentry can use to send events to a Sentry service. |
Functions
clear_modulecache | Clears the internal module cache. |
end_session | Ends a session. |
remove_context | Removes the context object with the specified key. |
remove_extra | Removes the extra with the specified |
remove_fingerprint | Removes the fingerprint. |
remove_tag | Removes the tag with the specified |
remove_transaction | Removes the transaction. |
remove_user | Removes a user. |
set_context | Sets a context object. |
set_extra | Sets extra information. |
set_fingerprint | Sets the event fingerprint. |
set_hook | Panic handler to send an |
set_level | Sets the event level. |
set_tag | Sets a tag. |
set_transaction | Sets the transaction. |
shutdown | Shuts down the Sentry client and forces transports to flush out. |
start_session | Starts a new session. |
user_consent_get | Checks the current state of user consent. |
user_consent_give | Gives user consent. |
user_consent_reset | Resets the user consent (back to unknown). |
user_consent_revoke | Revokes user consent. |
Type Definitions
Request | feature="custom-transport" The |