Crate sentry

Expand description

This crate provides the core of the Sentry SDK, which can be used to log events and errors.

sentry-core is meant for integration authors and third-party library authors that want to instrument their code for sentry.

Regular users who wish to integrate sentry into their applications should instead use the sentry crate, which comes with a default transport and a large set of integrations for various third-party libraries.

§Core Concepts

This crate follows the Unified API guidelines and is centered around the concepts of Client, Hub and Scope, as well as the extension points via the Integration, Transport and TransportFactory traits.

§Parallelism, Concurrency and Async

The main concurrency primitive is the Hub. In general, all concurrent code, no matter if multithreaded parallelism or futures concurrency, needs to run with its own copy of a Hub. Even though the Hub is internally synchronized, using it concurrently may lead to unexpected results up to panics.

For threads or tasks that are running concurrently or outlive the current execution context, a new Hub needs to be created and bound for the computation.

use rayon::prelude::*;
use sentry::{Hub, SentryFutureExt};
use std::sync::Arc;

// Parallel multithreaded code:
let outer_hub = Hub::current();
let results: Vec<_> = [1_u32, 2, 3]
    .into_par_iter()
    .map(|num| {
        let thread_hub = Arc::new(Hub::new_from_top(&outer_hub));
        Hub::run(thread_hub, || num * num)
    })
    .collect();

assert_eq!(&results, &[1, 4, 9]);

// Concurrent futures code:
let futures = [1_u32, 2, 3]
    .into_iter()
    .map(|num| async move { num * num }.bind_hub(Hub::new_from_top(Hub::current())));
let results = futures::future::join_all(futures).await;

assert_eq!(&results, &[1, 4, 9]);

For tasks that are not concurrent and do not outlive the current execution context, no new Hub needs to be created, but the current Hub has to be bound.

use sentry::{Hub, SentryFutureExt};

// Spawned thread that is being joined:
let hub = Hub::current();
let result = std::thread::spawn(|| Hub::run(hub, || 1_u32)).join();

assert_eq!(result.unwrap(), 1);

// Spawned future that is being awaited:
let result = tokio::spawn(async { 1_u32 }.bind_hub(Hub::current())).await;

assert_eq!(result.unwrap(), 1);

§Minimal API

By default, this crate comes with a so-called “minimal” mode. This mode will provide all the APIs needed to instrument code with sentry, and to write sentry integrations, but it will blackhole a lot of operations.

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.

§Features

feature = "client": Activates the Client type and certain Hub functionality.
feature = "test": Activates the test module, which can be used to write integration tests. It comes with a test transport which can capture all sent events for inspection.
feature = "debug-logs": Uses the log crate for debug output, instead of printing to stderr. This feature is deprecated and will be replaced by a dedicated log callback in the future.

Modules§

types: This crate provides common types for working with the Sentry protocol or the Sentry server. It’s used by the Sentry Relay infrastructure as well as the rust Sentry client.

Macros§

release_name: Returns the intended release for Sentry as an Option<Cow<'static, str>>.

Structs§

Breadcrumb: Represents a single breadcrumb.
Client: The Sentry Client.
ClientOptions: Configuration settings for the client.
Data: A smart pointer to a span’s data field.
Envelope: A Sentry Envelope.
Hub: The central object that can manage scopes and clients.
HubSwitchGuard: A Hub switch guard used to temporarily swap active hub in thread local storage.
Scope: Holds contextual data for the current scope.
ScopeGuard: A scope guard.
SentryFuture: A future that binds a Hub to its execution.
Span: A running Performance Monitoring Span.
TraceHeadersIter: An Iterator over HTTP header names and values needed for distributed tracing.
Transaction: A running Performance Monitoring Transaction.
TransactionContext: The Transaction Context used to start a new Performance Monitoring Transaction.
TransactionContextBuilder: A transaction context builder created by TransactionContext::builder.
TransactionData: Iterable for a transaction’s extra field.
User: Represents user info.

Enums§

Level: Represents the level of severity of an event or breadcrumb.
SessionMode: The Session Mode of the SDK.
TransactionOrSpan: A wrapper that groups a Transaction and a Span together.

Traits§

Integration: Integration abstraction.
IntoBreadcrumbs: A helper trait that converts self into an Iterator of Breadcrumbs.
IntoDsn: Helper trait to convert a string into an Option<Dsn>.
SentryFutureExt: Future extensions for Sentry.
Transport: The trait for transports.
TransportFactory: A factory creating transport instances.

Functions§

add_breadcrumb: Records a breadcrumb by calling a function.
capture_error: Captures a std::error::Error.
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.
end_session: End the current Release Health Session.
end_session_with_status: End the current Release Health Session with the given SessionStatus.
event_from_error: Create a sentry Event from a std::error::Error.
last_event_id: Returns the last event ID captured.
parse_type_from_debug: Parse the types name from Debug output.
start_session: Start a new session for Release Health.
start_transaction: Start a new Performance Monitoring Transaction.
with_integration: Looks up an integration on the current Hub.
with_scope: Temporarily pushes a scope for a single call optionally reconfiguring it.

Type Aliases§

BeforeCallback: Type alias for before event/breadcrumb handlers.
CustomTransactionContext: Arbitrary data passed by the caller, when starting a transaction.
TracesSampler: A function to be run for each new transaction, to determine the rate at which it should be sampled.

Crate sentryCopy item path