[−][src]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. Keep the guard around or sending events
will not work.
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.
Scopes, Threads and Hubs
Data is typically bound to a Scope
. Scopes are stored in a hidden stack
on a Hub
. Once the library has been initialized a hub is automatically
available. In the default config a new hub is created for each thread and they act
independently.
The thread that calls sentry::init
initializes the first hub which then automatically becomes
the base of new hubs (You can get that hub by calling Hub::main()
). If a new thread is
spawned it gets a new hub based on that one (the thread calls Hub::new_from_top(Hub::main())
).
The current thread's hub is returned from Hub::current()
. Any hub that is wrapped in an Arc
can be temporarily bound to a thread with Hub::run
. For more information see
Hub
.
Users are expected to reconfigure the scope with configure_scope
.
For more elaborate scope management the hub needs to be interfaced with directly.
In some situations (particularly in async code) it's often not possible to use the thread local hub. In that case a hub can be explicitly created and passed around. However due to the nature of some integrations some functionality like automatic breadcrumb recording depends on the thread local hub being correctly configured.
Minimal API
This crate can also be used in "minimal" 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 minimal API is a small set of APIs that dispatch to the underlying implementations on the configured Sentry client. If the client is not there the minimal API will blackhole a lot of operations.
Only if a user then also uses and configures Sentry this code becomes used.
In minimal mode some types are restricted in functionality. For instance the Client
is not
available and the Hub
does not retain all API functionality. To see what the APIs in mnimal
mode look like you can build the docs for this crate without any features enabled.
Features
Functionality of the crate can be turned on and off by feature flags. This is the current list of feature flags:
Default features:
with_client_implementation
: Turns on the real client implementation.with_default_transport
: Compiles in the default HTTP transport (see below).with_backtrace
: Enables backtrace support (automatically turned on in a few cases).with_panic
: Enables the panic integration.with_failure
: Enables thefailure
integration.with_device_info
: Enables the device info context.with_rust_info
: Enables the rust compiler info context instead of printing to stderr when debug is enabled on the hub.
Additional context:
with_debug_meta
: Adds debug meta to reported events (permits server side symbolication).
Additional integrations:
with_log
: Enables thelog
integration.with_env_logger
: Enables theenv_logger
integration.with_debug_to_log
: When enabled sentry will debug log to a debug log at all times.with_error_chain
: Enables the error-chain integration.
Additional transports:
with_reqwest_transport
: Enables the reqwest transport explicitly. This is currently the default transport.with_curl_transport
: Enables the curl transport.with_rustls
: Enables therustls
TLS implementation. This is currently the default when using thewith_reqwest_transport
feature.with_native_tls
: Enables thedefault-tls
feature of thereqwest
library.
Testing:
with_test_support
: Enables the test support module.
Modules
integrations | This module provides support for various integrations. |
internals | Useful internals. |
protocol | The current latest sentry protocol version. |
test | This provides testing functionality for building tests. |
transports | The provided transports. |
utils | Useful utilities for working with events. |
Macros
release_name | Returns the intended release for Sentry as an |
Structs
Breadcrumb | Represents a single breadcrumb. |
Client | The Sentry client object. |
ClientOptions | Configuration settings for the client. |
Hub | The central object that can manages scopes and clients. |
Scope | Holds contextual data for the current scope. |
User | Represents user info. |
Enums
Level | Represents the level of severity of an event or breadcrumb. |
Functions
add_breadcrumb | Records a breadcrumb by calling a function. |
capture_event | Captures an event on the currently active client if any. |
capture_message | Captures an arbitrary message. |
configure_scope | Invokes a function that can modify the current scope. |
init | Creates the Sentry client for a given client config and binds it. |
last_event_id | Returns the last event ID captured. |
with_scope | Temporarily pushes a scope for a single call optionally reconfiguring it. |