metrics_lib/
lib.rs

1//! # Ultimate Metrics Library
2//!
3//! The most powerful, lightweight, and efficient metrics library ever built.
4//!
5//! ## Features
6//!
7//! - **Sub-nanosecond operations** - Counter increments in ~2-3ns
8//! - **Lock-free everything** - No locks anywhere in hot paths
9//! - **System health monitoring** - Built-in CPU/memory tracking
10//! - **Dynamic configuration** - Runtime tuning without restarts
11//! - **Circuit breakers** - Fault tolerance with auto-recovery
12//! - **Dead simple API** - `METRICS.counter("requests").inc()`
13//!
14//! ## Quick Start
15//!
16//! ```rust
17//! use metrics_lib::{init, metrics};
18//!
19//! // Initialize metrics (do this once at startup)
20//! init();
21//!
22//! // Counters (sub-nanosecond)
23//! metrics().counter("requests").inc();
24//! metrics().counter("errors").add(5);
25//!
26//! // Gauges (atomic)  
27//! metrics().gauge("cpu_usage").set(87.3);
28//! metrics().gauge("memory_mb").set(1024.5);
29//!
30//! // Timers (high precision)
31//! let timer_metric = metrics().timer("api_call");
32//! let timer = timer_metric.start();
33//! // ... do work ...
34//! timer.stop(); // Auto-records
35//!
36//! // Or even simpler
37//! let result = metrics().time("db_query", || {
38//!     // Simulated database query
39//!     "user data"
40//! });
41//!
42//! // System health
43//! let cpu_pct = metrics().system().cpu_used();
44//! let mem_mb = metrics().system().mem_used_mb();
45//!
46//! // Rate limiting
47//! metrics().rate("api_calls").tick();
48//! let rate_per_sec = metrics().rate("api_calls").rate();
49//! ```
50
51#![warn(missing_docs)]
52#![allow(unsafe_code)] // For atomic optimizations
53
54use std::sync::OnceLock;
55
56mod adaptive;
57mod async_support;
58mod counter;
59mod gauge;
60mod rate_meter;
61mod registry;
62mod system_health;
63mod timer;
64
65pub use adaptive::{
66    AdaptiveSampler, BackpressureController, MetricCircuitBreaker, SamplingStrategy,
67};
68pub use async_support::{AsyncMetricBatch, AsyncTimerExt, AsyncTimerGuard};
69pub use counter::*;
70pub use gauge::{Gauge, GaugeStats};
71pub use rate_meter::{RateMeter, RateStats};
72pub use registry::*;
73pub use system_health::*;
74pub use timer::*;
75
76// Re-export specialized modules with qualified names to avoid conflicts
77pub use gauge::specialized as gauge_specialized;
78pub use rate_meter::specialized as rate_meter_specialized;
79
80/// Global metrics instance - initialize once, use everywhere
81pub static METRICS: OnceLock<MetricsCore> = OnceLock::new();
82
83/// Initialize the global metrics instance
84///
85/// Call this once at the start of your application
86pub fn init() -> &'static MetricsCore {
87    METRICS.get_or_init(MetricsCore::new)
88}
89
90/// Get the global metrics instance
91///
92/// Panics if not initialized - call `init()` first.
93///
94/// Panic conditions:
95/// - If [`init()`] has not been called yet, this function will panic with a clear message.
96///   Prefer passing `&MetricsCore` explicitly in library code to avoid relying on globals.
97pub fn metrics() -> &'static MetricsCore {
98    METRICS
99        .get()
100        .expect("Metrics not initialized - call metrics_lib::init() first")
101}
102
103/// Main metrics interface - the core of everything
104#[repr(align(64))] // Cache line aligned
105pub struct MetricsCore {
106    registry: Registry,
107    system: SystemHealth,
108}
109
110impl MetricsCore {
111    /// Create new metrics core
112    pub fn new() -> Self {
113        Self {
114            registry: Registry::new(),
115            system: SystemHealth::new(),
116        }
117    }
118
119    /// Get or create a counter
120    #[inline(always)]
121    pub fn counter(&self, name: &'static str) -> std::sync::Arc<Counter> {
122        self.registry.get_or_create_counter(name)
123    }
124
125    /// Get or create a gauge
126    #[inline(always)]
127    pub fn gauge(&self, name: &'static str) -> std::sync::Arc<Gauge> {
128        self.registry.get_or_create_gauge(name)
129    }
130
131    /// Get or create a timer
132    #[inline(always)]
133    pub fn timer(&self, name: &'static str) -> std::sync::Arc<Timer> {
134        self.registry.get_or_create_timer(name)
135    }
136
137    /// Get or create a rate meter
138    #[inline(always)]
139    pub fn rate(&self, name: &'static str) -> std::sync::Arc<RateMeter> {
140        self.registry.get_or_create_rate_meter(name)
141    }
142
143    /// Time a closure and record the result
144    #[inline]
145    pub fn time<T>(&self, name: &'static str, f: impl FnOnce() -> T) -> T {
146        let binding = self.timer(name);
147        let timer = binding.start();
148        let result = f();
149        timer.stop();
150        result
151    }
152
153    /// Get system health interface
154    #[inline(always)]
155    pub fn system(&self) -> &SystemHealth {
156        &self.system
157    }
158
159    /// Get registry for advanced operations
160    #[inline(always)]
161    pub fn registry(&self) -> &Registry {
162        &self.registry
163    }
164}
165
166impl Default for MetricsCore {
167    fn default() -> Self {
168        Self::new()
169    }
170}
171
172/// Common result type for metrics operations
173pub type Result<T> = std::result::Result<T, MetricsError>;
174
175/// Metrics errors
176#[derive(Debug, Clone, PartialEq)]
177pub enum MetricsError {
178    /// Circuit breaker is open and the operation is not allowed.
179    CircuitOpen,
180    /// System is overloaded (e.g., adaptive sampler reduced acceptance) and rejected the operation.
181    Overloaded,
182    /// Invalid metric name (empty, overly long, or otherwise rejected by a policy).
183    InvalidName,
184    /// Invalid value supplied (NaN, non-finite, out-of-range, or otherwise invalid).
185    InvalidValue {
186        /// Short, static explanation of why the value was invalid (e.g., "value is not finite").
187        reason: &'static str,
188    },
189    /// Arithmetic would overflow the counter or index (checked variants only).
190    Overflow,
191    /// Arithmetic would underflow (checked variants only).
192    Underflow,
193    /// Operation would exceed a configured limit (rate limiting, quotas, etc.).
194    OverLimit,
195    /// Operation would block and a non-blocking/try path was requested.
196    WouldBlock,
197    /// Global metrics were not initialized and the operation requires initialization.
198    NotInitialized,
199    /// Configuration error with details.
200    Config(String),
201}
202
203impl std::fmt::Display for MetricsError {
204    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
205        match self {
206            MetricsError::CircuitOpen => write!(f, "Circuit breaker is open"),
207            MetricsError::Overloaded => write!(f, "System is overloaded"),
208            MetricsError::InvalidName => write!(f, "Invalid metric name"),
209            MetricsError::InvalidValue { reason } => write!(f, "Invalid value: {reason}"),
210            MetricsError::Overflow => write!(f, "Operation would overflow"),
211            MetricsError::Underflow => write!(f, "Operation would underflow"),
212            MetricsError::OverLimit => write!(f, "Operation would exceed limit"),
213            MetricsError::WouldBlock => write!(f, "Operation would block"),
214            MetricsError::NotInitialized => write!(f, "Global metrics not initialized"),
215            MetricsError::Config(msg) => write!(f, "Configuration error: {msg}"),
216        }
217    }
218}
219
220impl std::error::Error for MetricsError {}
221
222/// Prelude for convenient imports
223pub mod prelude {
224    pub use crate::{init, metrics, MetricsCore, MetricsError, Result, METRICS};
225    pub use crate::{Counter, Gauge, RateMeter, Registry, SystemHealth, Timer};
226}
227
228#[cfg(test)]
229mod tests {
230    use super::*;
231
232    #[test]
233    fn test_metrics_initialization() {
234        let metrics = MetricsCore::new();
235
236        // Test basic operations work
237        metrics.counter("test").inc();
238        assert_eq!(metrics.counter("test").get(), 1);
239
240        metrics.gauge("test").set(42.5);
241        assert_eq!(metrics.gauge("test").get(), 42.5);
242
243        // Test system health
244        let _cpu = metrics.system().cpu_used();
245        let _mem = metrics.system().mem_used_mb();
246    }
247
248    #[test]
249    fn test_global_metrics() {
250        let _metrics = init();
251
252        // Test global access
253        metrics().counter("global_test").inc();
254        assert_eq!(metrics().counter("global_test").get(), 1);
255    }
256
257    #[test]
258    fn test_time_function_records_and_returns() {
259        let metrics = MetricsCore::new();
260
261        let result = metrics.time("timed_op", || 123usize);
262        assert_eq!(result, 123);
263        // Ensure timer recorded exactly one sample
264        assert_eq!(metrics.timer("timed_op").count(), 1);
265    }
266
267    #[test]
268    fn test_accessors_system_and_registry() {
269        let metrics = MetricsCore::new();
270
271        // Access system and call a method to ensure it is used
272        let _ = metrics.system().cpu_used();
273
274        // Access registry and use it to create a metric directly
275        let reg = metrics.registry();
276        let c = reg.get_or_create_counter("from_registry");
277        c.add(2);
278        assert_eq!(metrics.counter("from_registry").get(), 2);
279    }
280
281    #[test]
282    fn test_default_impl() {
283        let metrics: MetricsCore = Default::default();
284        metrics.counter("default_impl").inc();
285        assert_eq!(metrics.counter("default_impl").get(), 1);
286    }
287
288    #[test]
289    fn test_metrics_error_display() {
290        let e1 = MetricsError::CircuitOpen;
291        let e2 = MetricsError::Overloaded;
292        let e3 = MetricsError::InvalidName;
293        let e4 = MetricsError::Config("bad cfg".to_string());
294
295        let s1 = format!("{e1}");
296        let s2 = format!("{e2}");
297        let s3 = format!("{e3}");
298        let s4 = format!("{e4}");
299
300        assert!(s1.contains("Circuit breaker is open"));
301        assert!(s2.contains("System is overloaded"));
302        assert!(s3.contains("Invalid metric name"));
303        assert!(s4.contains("Configuration error"));
304        assert!(s4.contains("bad cfg"));
305    }
306}
metrics_lib/lib.rs

metrics_lib/
lib.rs
