//! Opt-in engineering observations, never a guest ABI or a source of GC roots. //! Timing distributions are bounded logarithmic histograms in nanoseconds. #[derive(Debug, Clone, PartialEq, Eq)] pub struct BudgetSnapshot { /// RuntimeResource discriminant order; depth/individual string size are checked, /// not reserved, so their current usage remains zero and their peak records checks. pub used: [u64; 8], pub peaks: [u64; 8], /// Includes refused speculative capacity growth that may fall back to exact growth. pub refusals: [u64; 8], pub limits: [u64; 8], } #[derive(Debug, Clone)] pub struct DurationHistogram { buckets: [u64; 64], pub count: u64, pub max_ns: u64, } impl Default for DurationHistogram { fn default() -> Self { Self { buckets: [0; 64], count: 0, max_ns: 0 } } } impl DurationHistogram { pub(crate) fn record(&mut self, elapsed: std::time::Duration) { let ns = elapsed.as_nanos().min(u64::MAX as u128) as u64; let bucket = (63 - ns.max(1).leading_zeros()) as usize; self.buckets[bucket] += 1; self.count += 1; self.max_ns = self.max_ns.max(ns); } /// Inclusive upper bound for the percentile's bucket, capped by observed max. pub fn percentile_upper_ns(&self, percentile: u64) -> u64 { assert!((1..=100).contains(&percentile)); if self.count == 0 { return 0; } let rank = (self.count as u128 * percentile as u128).div_ceil(100); let mut seen = 0u128; for (i, &count) in self.buckets.iter().enumerate() { seen += count as u128; if seen >= rank { return (u64::MAX >> (63 - i)).min(self.max_ns); } } self.max_ns } } #[derive(Debug, Default, Clone)] pub struct GcDiagnostics { pub collections: u64, pub reclaimed: u64, pub mark: DurationHistogram, pub sweep: DurationHistogram, pub total: DurationHistogram, pub string_reconciliation: DurationHistogram, } #[derive(Debug, Clone)] pub struct ResourceSnapshot { pub budget: BudgetSnapshot, pub live_objects: usize, pub free_handles: usize, pub retired_handles: usize, pub tracked_strings: usize, pub call_depth: usize, pub peak_call_depth: usize, pub cycles: u64, pub gc: GcDiagnostics, } #[cfg(test)] mod tests { use super::*; #[test] fn bounded_histogram_reports_upper_bounds_and_exact_max() { let mut h = DurationHistogram::default(); assert_eq!(h.percentile_upper_ns(99), 0); for ns in 0..100 { h.record(std::time::Duration::from_nanos(ns)); } assert_eq!(h.count, 100); assert_eq!(h.percentile_upper_ns(50), 63); assert_eq!(h.percentile_upper_ns(95), 99); assert_eq!(h.max_ns, 99); } } /// Non-owning storage observations for engineering qualification. These values /// never retain a guest object or a native string owner and cannot write storage. #[derive(Debug, Clone, PartialEq, Eq)] pub enum StorageValue { Null, Int32(i32), Int64(i64), FloatBits(u64), Boolean(bool), Reference(prometeu_bytecode::HeapRef), StringIdentity { address: usize, bytes: usize }, } impl StorageValue { pub(crate) fn observe(value: &prometeu_bytecode::Value) -> Self { use prometeu_bytecode::Value; match value { Value::Null => Self::Null, Value::Int32(n) => Self::Int32(*n), Value::Int64(n) => Self::Int64(*n), Value::Float(n) => Self::FloatBits(n.to_bits()), Value::Boolean(n) => Self::Boolean(*n), Value::HeapRef(r) => Self::Reference(*r), Value::String(s) => Self::StringIdentity { address: std::sync::Arc::as_ptr(s) as *const () as usize, bytes: s.len(), }, } } } #[derive(Debug, Clone, PartialEq, Eq)] pub struct StorageObject { pub reference: prometeu_bytecode::HeapRef, pub type_id: prometeu_bytecode::registry::TypeId, pub groups: Vec>, }