featherdb_query/

metrics.rs

//! Query metrics and performance tracking
//!
//! Provides infrastructure for tracking query execution metrics using atomic counters.
//! Metrics are thread-safe and can be shared across multiple query executions.

use std::sync::atomic::{AtomicU64, Ordering};

/// Thread-safe query metrics using atomic counters
#[derive(Debug, Default)]
pub struct QueryMetrics {
    /// Total number of queries executed
    queries_executed: AtomicU64,
    /// Total parse time in microseconds
    total_parse_time_us: AtomicU64,
    /// Total planning time in microseconds
    total_plan_time_us: AtomicU64,
    /// Total execution time in microseconds
    total_exec_time_us: AtomicU64,
    /// Total rows scanned during execution
    rows_scanned: AtomicU64,
    /// Total rows returned to client
    rows_returned: AtomicU64,
}

/// Snapshot of query metrics at a point in time
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct QueryMetricsSnapshot {
    /// Total number of queries executed
    pub queries_executed: u64,
    /// Total parse time in microseconds
    pub total_parse_time_us: u64,
    /// Total planning time in microseconds
    pub total_plan_time_us: u64,
    /// Total execution time in microseconds
    pub total_exec_time_us: u64,
    /// Total rows scanned during execution
    pub rows_scanned: u64,
    /// Total rows returned to client
    pub rows_returned: u64,
}

impl QueryMetrics {
    /// Create a new QueryMetrics instance
    pub fn new() -> Self {
        Self::default()
    }

    /// Record parse time in microseconds
    pub fn record_parse_time(&self, micros: u64) {
        self.total_parse_time_us
            .fetch_add(micros, Ordering::Relaxed);
    }

    /// Record planning time in microseconds
    pub fn record_plan_time(&self, micros: u64) {
        self.total_plan_time_us.fetch_add(micros, Ordering::Relaxed);
    }

    /// Record execution time in microseconds
    pub fn record_exec_time(&self, micros: u64) {
        self.total_exec_time_us.fetch_add(micros, Ordering::Relaxed);
    }

    /// Record rows scanned
    pub fn record_rows_scanned(&self, count: u64) {
        self.rows_scanned.fetch_add(count, Ordering::Relaxed);
    }

    /// Record rows returned
    pub fn record_rows_returned(&self, count: u64) {
        self.rows_returned.fetch_add(count, Ordering::Relaxed);
    }

    /// Increment the query execution counter
    pub fn increment_queries(&self) {
        self.queries_executed.fetch_add(1, Ordering::Relaxed);
    }

    /// Get a snapshot of current metrics
    pub fn snapshot(&self) -> QueryMetricsSnapshot {
        QueryMetricsSnapshot {
            queries_executed: self.queries_executed.load(Ordering::Relaxed),
            total_parse_time_us: self.total_parse_time_us.load(Ordering::Relaxed),
            total_plan_time_us: self.total_plan_time_us.load(Ordering::Relaxed),
            total_exec_time_us: self.total_exec_time_us.load(Ordering::Relaxed),
            rows_scanned: self.rows_scanned.load(Ordering::Relaxed),
            rows_returned: self.rows_returned.load(Ordering::Relaxed),
        }
    }

    /// Reset all metrics to zero
    pub fn reset(&self) {
        self.queries_executed.store(0, Ordering::Relaxed);
        self.total_parse_time_us.store(0, Ordering::Relaxed);
        self.total_plan_time_us.store(0, Ordering::Relaxed);
        self.total_exec_time_us.store(0, Ordering::Relaxed);
        self.rows_scanned.store(0, Ordering::Relaxed);
        self.rows_returned.store(0, Ordering::Relaxed);
    }
}

impl QueryMetricsSnapshot {
    /// Get average parse time in microseconds
    pub fn avg_parse_time_us(&self) -> f64 {
        if self.queries_executed == 0 {
            0.0
        } else {
            self.total_parse_time_us as f64 / self.queries_executed as f64
        }
    }

    /// Get average planning time in microseconds
    pub fn avg_plan_time_us(&self) -> f64 {
        if self.queries_executed == 0 {
            0.0
        } else {
            self.total_plan_time_us as f64 / self.queries_executed as f64
        }
    }

    /// Get average execution time in microseconds
    pub fn avg_exec_time_us(&self) -> f64 {
        if self.queries_executed == 0 {
            0.0
        } else {
            self.total_exec_time_us as f64 / self.queries_executed as f64
        }
    }

    /// Get average total query time (parse + plan + exec) in microseconds
    pub fn avg_total_time_us(&self) -> f64 {
        if self.queries_executed == 0 {
            0.0
        } else {
            let total =
                self.total_parse_time_us + self.total_plan_time_us + self.total_exec_time_us;
            total as f64 / self.queries_executed as f64
        }
    }

    /// Get average rows scanned per query
    pub fn avg_rows_scanned(&self) -> f64 {
        if self.queries_executed == 0 {
            0.0
        } else {
            self.rows_scanned as f64 / self.queries_executed as f64
        }
    }

    /// Get average rows returned per query
    pub fn avg_rows_returned(&self) -> f64 {
        if self.queries_executed == 0 {
            0.0
        } else {
            self.rows_returned as f64 / self.queries_executed as f64
        }
    }

    /// Get selectivity ratio (rows returned / rows scanned)
    pub fn selectivity_ratio(&self) -> f64 {
        if self.rows_scanned == 0 {
            0.0
        } else {
            self.rows_returned as f64 / self.rows_scanned as f64
        }
    }

    /// Get total query time (parse + plan + exec) in microseconds
    pub fn total_query_time_us(&self) -> u64 {
        self.total_parse_time_us + self.total_plan_time_us + self.total_exec_time_us
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_metrics_basic() {
        let metrics = QueryMetrics::new();

        // Record some metrics
        metrics.increment_queries();
        metrics.record_parse_time(100);
        metrics.record_plan_time(200);
        metrics.record_exec_time(500);
        metrics.record_rows_scanned(1000);
        metrics.record_rows_returned(50);

        let snapshot = metrics.snapshot();
        assert_eq!(snapshot.queries_executed, 1);
        assert_eq!(snapshot.total_parse_time_us, 100);
        assert_eq!(snapshot.total_plan_time_us, 200);
        assert_eq!(snapshot.total_exec_time_us, 500);
        assert_eq!(snapshot.rows_scanned, 1000);
        assert_eq!(snapshot.rows_returned, 50);
    }

    #[test]
    fn test_metrics_accumulation() {
        let metrics = QueryMetrics::new();

        // Record two queries
        metrics.increment_queries();
        metrics.record_parse_time(100);
        metrics.record_plan_time(200);
        metrics.record_exec_time(500);
        metrics.record_rows_scanned(1000);
        metrics.record_rows_returned(50);

        metrics.increment_queries();
        metrics.record_parse_time(150);
        metrics.record_plan_time(250);
        metrics.record_exec_time(600);
        metrics.record_rows_scanned(2000);
        metrics.record_rows_returned(100);

        let snapshot = metrics.snapshot();
        assert_eq!(snapshot.queries_executed, 2);
        assert_eq!(snapshot.total_parse_time_us, 250);
        assert_eq!(snapshot.total_plan_time_us, 450);
        assert_eq!(snapshot.total_exec_time_us, 1100);
        assert_eq!(snapshot.rows_scanned, 3000);
        assert_eq!(snapshot.rows_returned, 150);
    }

    #[test]
    fn test_metrics_averages() {
        let metrics = QueryMetrics::new();

        // Record two queries
        metrics.increment_queries();
        metrics.record_parse_time(100);
        metrics.record_plan_time(200);
        metrics.record_exec_time(500);
        metrics.record_rows_scanned(1000);
        metrics.record_rows_returned(50);

        metrics.increment_queries();
        metrics.record_parse_time(200);
        metrics.record_plan_time(400);
        metrics.record_exec_time(700);
        metrics.record_rows_scanned(2000);
        metrics.record_rows_returned(150);

        let snapshot = metrics.snapshot();
        assert_eq!(snapshot.avg_parse_time_us(), 150.0);
        assert_eq!(snapshot.avg_plan_time_us(), 300.0);
        assert_eq!(snapshot.avg_exec_time_us(), 600.0);
        assert_eq!(snapshot.avg_total_time_us(), 1050.0);
        assert_eq!(snapshot.avg_rows_scanned(), 1500.0);
        assert_eq!(snapshot.avg_rows_returned(), 100.0);
    }

    #[test]
    fn test_selectivity_ratio() {
        let metrics = QueryMetrics::new();

        metrics.increment_queries();
        metrics.record_rows_scanned(1000);
        metrics.record_rows_returned(100);

        let snapshot = metrics.snapshot();
        assert_eq!(snapshot.selectivity_ratio(), 0.1);
    }

    #[test]
    fn test_metrics_reset() {
        let metrics = QueryMetrics::new();

        metrics.increment_queries();
        metrics.record_parse_time(100);
        metrics.record_plan_time(200);
        metrics.record_exec_time(500);
        metrics.record_rows_scanned(1000);
        metrics.record_rows_returned(50);

        let snapshot_before = metrics.snapshot();
        assert_eq!(snapshot_before.queries_executed, 1);

        metrics.reset();

        let snapshot_after = metrics.snapshot();
        assert_eq!(snapshot_after.queries_executed, 0);
        assert_eq!(snapshot_after.total_parse_time_us, 0);
        assert_eq!(snapshot_after.total_plan_time_us, 0);
        assert_eq!(snapshot_after.total_exec_time_us, 0);
        assert_eq!(snapshot_after.rows_scanned, 0);
        assert_eq!(snapshot_after.rows_returned, 0);
    }

    #[test]
    fn test_zero_queries_averages() {
        let metrics = QueryMetrics::new();
        let snapshot = metrics.snapshot();

        // All averages should be 0.0 when no queries executed
        assert_eq!(snapshot.avg_parse_time_us(), 0.0);
        assert_eq!(snapshot.avg_plan_time_us(), 0.0);
        assert_eq!(snapshot.avg_exec_time_us(), 0.0);
        assert_eq!(snapshot.avg_total_time_us(), 0.0);
        assert_eq!(snapshot.avg_rows_scanned(), 0.0);
        assert_eq!(snapshot.avg_rows_returned(), 0.0);
        assert_eq!(snapshot.selectivity_ratio(), 0.0);
    }

    #[test]
    fn test_total_query_time() {
        let metrics = QueryMetrics::new();

        metrics.increment_queries();
        metrics.record_parse_time(100);
        metrics.record_plan_time(200);
        metrics.record_exec_time(500);

        let snapshot = metrics.snapshot();
        assert_eq!(snapshot.total_query_time_us(), 800);
    }
}