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. For the available integrations and how to use them see integrations.
Scope Management
Data is typically bound to a scope. A new scope can be introduced by pushing it
with the push_scope
function. That scope can then be
configured with configure_scope
which lets you
attach data to it that will be sent along with errors.
If a new scope is pushed the data and currently bound client are inherited. To
propagate that scope to a completely different thread a
scope_handle
can be acquired and passed to a thread
where it can be bound.
Shim Only API
This crate can also be used in "shim only" mode. This is enabled by disabling all default features of the crate. In that mode a minimal API set is retained that can be used to instrument code for Sentry without actually using Sentry. The shim is a small set of APIs that dispatch to the underlying implementations on the configured Sentry client. If the client is not there the shim will blackhole a lot of operations.
Only if a user then also uses and configures Sentry this code becomes used.
In shim mode some types are restricted in functionality. For instance the Client
in shim
mode does not retain all API functionality. To see what the APIs in shim-only
mode look like refer to the shim only docs.
Features
Functionality of the crate can be turned on and off by feature flags. This is the current list of feature flags:
default flags:
with_client_implementation
: turns on the real client implementation.with_backtrace
: enables backtrace support (automatically turned on in a few cases)with_panic
: enables the panic integrationwith_failure
: enables thefailure
integrationwith_log
: enables thelog
integrationwith_device_info
: enables the device info contextwith_rust_info
: enables the rust compiler info contextwith_debug_meta
: enables debug meta support (permits server side symbolication)
additional features:
with_error_chain
: enables the error-chain integrationwith_shim_api
: compiles the shim only api into a dummyshim
module for inspection. This API cannot be used but it can be inspected for documentation purposes.
Modules
integrations |
This module provides support for various integrations. |
protocol |
The current latest sentry protocol version. |
shim |
The shim only API (documentation only). |
utils |
Useful utilities for working with events. |
Macros
sentry_crate_release |
Returns the intended release for Sentry as an |
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. |
ScopeHandle |
A handle to the current scope. |
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_scope |
Pushes a new scope on the stack. |
scope_handle |
Returns the handle to the current scope. |
unbind_client |
Unbinds the client on the current scope. |
with_client_and_scope |
Invokes a function if the sentry client is available with client and scope. |
with_scope |
A callback based alternative to using |