alice_analytics/lib.rs
1//! ALICE-Analytics — High-Performance Telemetry & Statistical Estimation
2//!
3//! Probabilistic data structures for streaming analytics with mathematical
4//! error guarantees and minimal memory footprint.
5//!
6//! # Modules
7//!
8//! - [`sketch`]: `HyperLogLog` / `DDSketch` / Count-Min / Heavy Hitters
9//! - [`stats`]: Percentile rank, IQR, covariance, Welford streaming stats
10//! - [`window`]: Tumbling / sliding / hierarchical window aggregates
11//! - [`anomaly`]: MAD / Z-Score / EWMA / composite anomaly detectors
12//! - [`privacy`]: **deprecated, not private** (see its Security section); use `alice_crypto::dp`
13//! - [`pipeline`]: Lock-free metric aggregation pipeline
14//! - [`export`]: JSON / Prometheus export of metric snapshots
15//! - [`streaming_ops`]: Streaming aggregation operators
16//! - `law` (feature `law`): residual distribution of a fitted
17//! `alice_zip::law::SignalLaw`, summarised with a `DDSketch`
18//!
19//! # Example
20//!
21//! ```rust
22//! use alice_analytics::sketch::{DDSketch, HyperLogLog};
23//!
24//! // quantiles with a relative-error guarantee of 1 %
25//! let mut latency = DDSketch::new(0.01);
26//! for ms in 1..=1000 {
27//! latency.insert(f64::from(ms));
28//! }
29//! let p99 = latency.quantile(0.99);
30//! assert!((p99 - 990.0).abs() <= 0.01 * 990.0);
31//!
32//! // distinct count in 16 KiB of registers
33//! let mut users = HyperLogLog::new();
34//! for id in 0..10_000_u64 {
35//! users.insert(&id);
36//! }
37//! let n = users.cardinality();
38//! assert!((n - 10_000.0).abs() < 0.05 * 10_000.0);
39//! ```
40
41#![cfg_attr(not(feature = "std"), no_std)]
42
43pub(crate) mod math;
44
45pub mod anomaly;
46pub mod export;
47pub mod pipeline;
48pub mod privacy;
49pub mod sketch;
50pub mod stats;
51pub mod streaming_ops;
52pub mod window;
53
54#[cfg(feature = "law")]
55pub mod law;
56
57/// Identifier of the arithmetic every estimate in this crate is computed with
58///
59/// Quantiles, cardinalities, anomaly scores and privacy noise all read
60/// transcendentals (`ln` / `exp` / `powf`), and a transcendental is only
61/// reproducible if its implementation is pinned too: the platform `libm`
62/// differs in the last ulp between macOS, glibc, MSVC and wasm, and one ulp of
63/// `ln` moves a `DDSketch` bin boundary, which moves the reported quantile.
64/// This crate therefore routes every transcendental through
65/// [`alice_det_math`], and re-exports that crate's identifier of its own
66/// numeric behaviour here.
67///
68/// Record it next to any estimate that is stored, transmitted or merged. Two
69/// results are comparable as numbers only if they were produced under the same
70/// identifier; when it differs, the two were computed by different arithmetic
71/// and agreement between them is not guaranteed at the bit level, however
72/// close the values look.
73///
74/// Pinned as hex by `tests/determinism_golden.rs`, so a change in the
75/// arithmetic cannot reach a release unnoticed. With the `law` feature,
76/// `law::ResidualSummary::law_id` mixes this identifier with the law it
77/// summarises, giving a single value that names both (not linked here: the
78/// module is behind that feature, so the link would not resolve in a build
79/// without it).
80pub use alice_det_math::SEMANTICS_ID;