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 integration
  • with_failure: enables the failure integration
  • with_log: enables the log integration
  • with_device_info: enables the device info context
  • with_rust_info: enables the rust compiler info context
  • with_debug_meta: enables debug meta support (permits server side symbolication)

additional features:

  • with_error_chain: enables the error-chain integration
  • with_shim_api: compiles the shim only api into a dummy shim 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 Option<Cow<'static, str>>.

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.

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