detritus/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![cfg_attr(all(test, coverage_nightly), feature(coverage_attribute))]
3//! Client SDK for Detritus ingestion.
4//!
5//! # Features
6//!
7//! - **`minidump`** *(enabled by default)* — capture native minidumps via
8//!   `minidumper-child` on Linux, Windows, and macOS. With the feature off (or
9//!   on Android) [`install_panic_hook`] falls back to the portable
10//!   [`PanicKind::PanicTarball`] bundle and the `minidumper-child` dependency is
11//!   dropped.
12//!
13//! Public API is limited to [`Layer`], [`LayerBuilder`], [`install_panic_hook`],
14//! [`ship_pending_crashes`], [`ship_pending_crashes_with_config`],
15//! [`ship_pending_crashes_using_stored_config`],
16//! [`ship_pending_crashes_using_stored_config_with_config`], [`CrashShipper`], [`ShipConfig`],
17//! [`DEFAULT_SENT_RETENTION_DAYS`], [`PanicHookConfig`], [`PanicKind`], and
18//! [`SourceId`], and the compression and TLS configuration re-exports.
19//! Everything else is an implementation detail and may change between releases.
20//!
21//! This setup enables zstd-compressed log exports to a Detritus 0.2 receiver.
22//!
23//! ```no_run
24//! use std::{path::PathBuf, time::Duration};
25//! use detritus::{CompressionEncoding, Layer, SourceId};
26//! use secrecy::SecretString;
27//! use url::Url;
28//! use uuid::Uuid;
29//!
30//! let source = SourceId {
31//!     project: "detritus".to_owned(),
32//!     platform: "linux".to_owned(),
33//!     version: "0.1.0".to_owned(),
34//!     install_id: Uuid::nil(),
35//! };
36//! let layer = Layer::builder()
37//!     .endpoint(Url::parse("http://127.0.0.1:4317").unwrap())
38//!     .compression(CompressionEncoding::Zstd)
39//!     .token(SecretString::from("secret-token"))
40//!     .source(source)
41//!     .queue_dir(PathBuf::from("observability-spool/logs"))
42//!     .flush_interval(Duration::from_secs(5))
43//!     .build()
44//!     .unwrap();
45//! # drop(layer);
46//! ```
47//!
48//! Call [`install_default_crypto_provider`] once before constructing the first
49//! HTTPS-backed client such as the crash shipper. It is safe to call more than
50//! once; repeated calls are ignored after the first successful install.
51
52use std::sync::Once;
53
54pub mod compression;
55mod layer;
56mod panic_hook;
57mod shipper;
58mod spool;
59
60/// Build metadata type re-exported for panic-hook configuration.
61pub use detritus_protocol::{BuildInfo, SourceId};
62/// Installs aws-lc-rs as the process-wide rustls crypto provider.
63///
64/// Call this before constructing the first HTTPS client. If another provider
65/// is already installed, this function leaves it in place.
66pub fn install_default_crypto_provider() {
67    static ONCE: Once = Once::new();
68    ONCE.call_once(|| {
69        let _ = rustls::crypto::aws_lc_rs::default_provider().install_default();
70    });
71}
72/// Tracing subscriber layer API.
73pub use layer::{Layer, LayerBuilder, LayerError};
74/// Panic-hook crash capture API.
75pub use panic_hook::{PanicHookConfig, PanicHookError, PanicKind, install_panic_hook};
76/// Offline crash spool shipping API.
77pub use shipper::{
78    CrashShipper, DEFAULT_SENT_RETENTION_DAYS, ShipConfig, ShipError, ship_pending_crashes,
79    ship_pending_crashes_using_stored_config, ship_pending_crashes_using_stored_config_with_config,
80    ship_pending_crashes_with_config,
81};
82/// Supported OTLP/gRPC message compression algorithms.
83pub use tonic::codec::CompressionEncoding;
84/// TLS configuration, CA certificates, and client identities for log transport.
85pub use tonic::transport::{Certificate, ClientTlsConfig, Identity};
86
87#[cfg(test)]
88mod tests {
89    use super::install_default_crypto_provider;
90
91    #[test]
92    #[cfg_attr(coverage_nightly, coverage(off))]
93    fn install_default_crypto_provider_is_idempotent() {
94        install_default_crypto_provider();
95        install_default_crypto_provider();
96    }
97}
detritus/lib.rs

detritus/
lib.rs
