Crate sentry [−] [src]
This crate provides support for logging events and errors / panics to the Sentry error logging service. It integrates with the standard panic system in Rust as well as a few popular error handling setups.
Quickstart
To use the crate you need to create a client first. When a client is created
it's typically bound to the current thread by calling bind_client
. By default
this happens by using the sentry::init
convenience function. When the client
is bound to the main thread it also becomes the default client for future
threads created but it is always possible to override the client for a thread
later by explicitly binding it.
The sentry::init
function returns a guard that when dropped will flush
Events that were not yet sent to the sentry service. It has a two second
deadline for this so shutdown of applications might slightly delay as a result
of this.
extern crate sentry; fn main() { let _guard = sentry::init("https://key@sentry.io/42"); sentry::capture_message("Hello World!", sentry::Level::Info); // when the guard goes out of scope here, the client will wait up to two // seconds to send remaining events to the service. }
Integrations
What makes this crate useful are the various integrations that exist. Some of them are enabled by default, some uncommon ones or for deprecated parts of the ecosystem a feature flag needs to be enabled.
Panic Handler
Feature: always available
A panic handler can be installed that will automatically dispatch all errors to Sentry that are caused by a panic:
use sentry::integrations::panic::register_panic_handler; register_panic_handler();
Failure
Feature: enabled by default (with_failure
)
Failure errors and Fail
objects can be logged with the failure integration.
This works really well if you use the failure::Error
type or if you have
failure::Fail
objects that use the failure context internally to gain a
backtrace.
Example usage:
use sentry::integrations::failure::capture_error; let result = match function_that_might_fail() { Ok(result) => result, Err(err) => { capture_error(&err); return Err(err); } };
To capture fails and not errors use capture_fail
.
Log
Feature: enabled by default (with_log
)
The log
crate is supported in two ways. First events can be captured as
breadcrumbs for later, secondly error events can be logged as events to
Sentry. By default anything above Info
is recorded as breadcrumb and
anything above Error
is captured as error event.
However due to how log systems in Rust work this currently requires you to slightly change your log setup. This is an example with the pretty env logger crate:
let mut log_builder = pretty_env_logger::formatted_builder().unwrap(); log_builder.parse("info"); // or env::var("RUST_LOG") sentry::integrations::log::init(Some( Box::new(log_builder.build())), Default::default());
Modules
integrations |
This module provides support for various integrations. |
protocol |
The current latest sentry protocol version. |
utils |
Useful utilities for working with events. |
Structs
Client |
The Sentry client object. |
ClientInitGuard |
Helper struct that is returned from |
ClientOptions |
Configuration settings for the client. |
Dsn |
Represents a Sentry dsn. |
ProjectId |
Represents a project ID. |
Scope |
Holds contextual data for the current scope. |
ScopeGuard |
A scope guard. |
User |
Represents user info. |
Enums
DsnParseError |
Represents a dsn url parsing error. |
Level |
Represents the level of severity of an event or breadcrumb |
ProjectIdParseError |
Raised if a project ID cannot be parsed from a string. |
Traits
IntoClientConfig |
Helper trait to convert an object into a client config for create. |
Functions
add_breadcrumb |
Records a breadcrumb by calling a function. |
bind_client |
Rebinds the client on the current scope. |
capture_event |
Captures an event on the currently active client if any. |
capture_exception |
Captures an error. |
capture_message |
Captures an arbitrary message. |
configure_scope |
Invokes a function that can modify the current scope. |
current_client |
Returns the currently bound client if there is one. |
drain_events |
Drain events that are not yet sent of the current client. |
init |
Creates the Sentry client for a given client config and binds it. |
push_and_configure_scope |
Shortcut for pushing and configuring a scope in one go. |
push_scope |
Pushes a new scope on the stack. |