32 releases

0.32.2 Jan 30, 2024
0.32.1 Dec 18, 2023
0.32.0 Nov 28, 2023
0.31.5 Jun 16, 2023
0.19.0 Jun 18, 2020

#761 in Debugging

Download history 114171/week @ 2023-11-21 152962/week @ 2023-11-28 125227/week @ 2023-12-05 128043/week @ 2023-12-12 127280/week @ 2023-12-19 30073/week @ 2023-12-26 108158/week @ 2024-01-02 103316/week @ 2024-01-09 106642/week @ 2024-01-16 127584/week @ 2024-01-23 113425/week @ 2024-01-30 117570/week @ 2024-02-06 120028/week @ 2024-02-13 96821/week @ 2024-02-20 132030/week @ 2024-02-27 89625/week @ 2024-03-05

457,182 downloads per month
Used in 70 crates (17 directly)

Apache-2.0

365KB
7.5K SLoC

Sentry

Sentry Rust SDK: sentry-core

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.

Resources

License: Apache-2.0

Dependencies

~3–4.5MB
~118K SLoC