observability

📊 RUST OBSERVABILITY PATTERNS

TL;DR: Comprehensive observability patterns for Rust applications, including lock-free metrics collection, distributed tracing, health checks, and monitoring integration.

🔍 OBSERVABILITY STRATEGY

graph TD
    Start["Observability Needs"] --> MetricsQ{"Metrics<br>Required?"}
    Start --> TracingQ{"Distributed<br>Tracing?"}
    Start --> HealthQ{"Health<br>Checks?"}

    MetricsQ -->|Yes| MetricsType{"Metrics<br>Type?"}
    MetricsType -->|Counters| Counters["Lock-free Counters"]
    MetricsType -->|Histograms| Histograms["Response Time Tracking"]
    MetricsType -->|Gauges| Gauges["Current State Metrics"]

    TracingQ -->|Yes| TracingType{"Tracing<br>Scope?"}
    TracingType -->|Application| AppTracing["Application Tracing"]
    TracingType -->|Distributed| DistTracing["Distributed Tracing"]

    HealthQ -->|Yes| HealthType{"Health Check<br>Type?"}
    HealthType -->|Simple| SimpleHealth["Basic Health Checks"]
    HealthType -->|Complex| ComplexHealth["Dependency Health Checks"]

    Counters --> Collection["Metrics Collection"]
    Histograms --> Collection
    Gauges --> Collection

    AppTracing --> TracingCollection["Trace Collection"]
    DistTracing --> TracingCollection

    SimpleHealth --> HealthCollection["Health Monitoring"]
    ComplexHealth --> HealthCollection

    Collection --> Export["Export & Integration"]
    TracingCollection --> Export
    HealthCollection --> Export

    Export --> Production["Production Observability"]

    style Start fill:#4da6ff,stroke:#0066cc,color:white
    style Counters fill:#4dbb5f,stroke:#36873f,color:white
    style AppTracing fill:#ffa64d,stroke:#cc7a30,color:white
    style SimpleHealth fill:#d94dbb,stroke:#a3378a,color:white

🎯 METRICS COLLECTION PATTERNS

Lock-Free Metrics for High Performance

use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use dashmap::DashMap;
use prometheus::{Counter, Histogram, Gauge, Registry, Opts, HistogramOpts};

// ✅ Lock-free atomic counter for high-throughput scenarios
#[derive(Debug)]
pub struct AtomicCounter {
    value: AtomicU64,
}

impl AtomicCounter {
    pub fn new() -> Self {
        Self {
            value: AtomicU64::new(0),
        }
    }

    pub fn increment(&self) -> u64 {
        self.value.fetch_add(1, Ordering::Relaxed)
    }

    pub fn add(&self, value: u64) -> u64 {
        self.value.fetch_add(value, Ordering::Relaxed)
    }

    pub fn get(&self) -> u64 {
        self.value.load(Ordering::Relaxed)
    }

    pub fn reset(&self) -> u64 {
        self.value.swap(0, Ordering::Relaxed)
    }
}

impl Default for AtomicCounter {
    fn default() -> Self {
        Self::new()
    }
}

// ✅ Comprehensive metrics collector
pub struct MetricsCollector {
    counters: DashMap<String, Arc<AtomicCounter>>,
    prometheus_counters: DashMap<String, Counter>,
    prometheus_histograms: DashMap<String, Histogram>,
    prometheus_gauges: DashMap<String, Gauge>,
    registry: Registry,
}

impl MetricsCollector {
    pub fn new() -> Self {
        Self {
            counters: DashMap::new(),
            prometheus_counters: DashMap::new(),
            prometheus_histograms: DashMap::new(),
            prometheus_gauges: DashMap::new(),
            registry: Registry::new(),
        }
    }

    /// Get or create a counter
    pub fn counter(&self, name: &str) -> Arc<AtomicCounter> {
        self.counters
            .entry(name.to_string())
            .or_insert_with(|| Arc::new(AtomicCounter::new()))
            .clone()
    }

    /// Get or create a Prometheus counter
    pub fn prometheus_counter(&self, name: &str, help: &str) -> Result<Counter, MetricsError> {
        if let Some(counter) = self.prometheus_counters.get(name) {
            return Ok(counter.clone());
        }

        let opts = Opts::new(name, help);
        let counter = Counter::with_opts(opts)?;
        self.registry.register(Box::new(counter.clone()))?;
        self.prometheus_counters.insert(name.to_string(), counter.clone());

        Ok(counter)
    }

    /// Get or create a Prometheus histogram
    pub fn prometheus_histogram(&self, name: &str, help: &str, buckets: Vec<f64>) -> Result<Histogram, MetricsError> {
        if let Some(histogram) = self.prometheus_histograms.get(name) {
            return Ok(histogram.clone());
        }

        let opts = HistogramOpts::new(name, help).buckets(buckets);
        let histogram = Histogram::with_opts(opts)?;
        self.registry.register(Box::new(histogram.clone()))?;
        self.prometheus_histograms.insert(name.to_string(), histogram.clone());

        Ok(histogram)
    }

    /// Get or create a Prometheus gauge
    pub fn prometheus_gauge(&self, name: &str, help: &str) -> Result<Gauge, MetricsError> {
        if let Some(gauge) = self.prometheus_gauges.get(name) {
            return Ok(gauge.clone());
        }

        let opts = Opts::new(name, help);
        let gauge = Gauge::with_opts(opts)?;
        self.registry.register(Box::new(gauge.clone()))?;
        self.prometheus_gauges.insert(name.to_string(), gauge.clone());

        Ok(gauge)
    }

    /// Export metrics in Prometheus format
    pub fn export_prometheus(&self) -> Result<String, MetricsError> {
        use prometheus::Encoder;
        let encoder = prometheus::TextEncoder::new();
        let metric_families = self.registry.gather();

        let mut buffer = Vec::new();
        encoder.encode(&metric_families, &mut buffer)?;

        Ok(String::from_utf8(buffer)?)
    }

    /// Get all counter values as a snapshot
    pub fn counter_snapshot(&self) -> std::collections::HashMap<String, u64> {
        self.counters
            .iter()
            .map(|entry| (entry.key().clone(), entry.value().get()))
            .collect()
    }
}

impl Default for MetricsCollector {
    fn default() -> Self {
        Self::new()
    }
}