Crate sentry

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 init.
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.