symbiotic/

lib.rs

//! Performance profiling for Polars benchmarks
//!
//! This crate collects process-specific performance metrics:
//! - Process CPU time and usage
//! - Process memory (RSS, virtual, heap, stack)
//! - Page faults and allocator statistics
//! - Thread pool metrics
//! - Hardware performance counters (optional)

use tracing_subscriber::{layer::SubscriberExt, Registry};

pub mod layer;
pub mod collectors;
pub mod metrics;
pub mod display;
pub mod bench_integration;

// eBPF kernel-side intelligence (real implementation with aya)
pub mod ebpf;
pub mod pmu;
#[allow(unused)]
pub mod correlation;
pub mod analysis;
pub mod report;
#[cfg(feature = "tui")]
pub mod tui;

// Region profiling engine (per-function hardware counter attribution)
#[cfg(feature = "profiling")]
pub mod regions;

// Per-line hardware profiling (IP sampling → DWARF → .symbiot trace)
#[cfg(feature = "line-profiler")]
pub mod line_profiler;

// Source registry — compile-time function source capture for multi-level view
pub mod source_registry;

// Sensory system — complete /proc/self self-awareness
pub mod senses;

// Export formats (JSON, Chrome Trace, Flamegraph, HTML)
pub mod export;

// Unified timeline (merges BPF + region + PMU events)
#[cfg(feature = "profiling")]
pub mod timeline;

// Differential profiling (compare two runs)
pub mod diff;

// Query server (HTTP/JSON, gRPC, Unix socket)
#[cfg(feature = "server")]
pub mod server;

// VS Code-like profiling dashboard (offline HTML + live web UI)
#[cfg(feature = "dashboard")]
pub mod dashboard;

// Allocation tracking (can be used independently or with region profiling)
#[cfg(feature = "alloc-track")]
pub mod alloc_tracker;

// Re-export the procedural macros
pub use symbiotic_macros::profile_bench;
pub use symbiotic_macros::profile;

// Re-export key types
pub use layer::ProfilingLayer;
pub use metrics::{MetricsSnapshot, ProfileReport, CollectorData};
pub use bench_integration::BenchProfiler;

// Re-export region profiling types
#[cfg(feature = "profiling")]
pub use regions::{RegionGuard, RegionRegistry, RegionCounters, RegionNode};

/// Profile a named code block with hardware counters.
///
/// When the `profiling` feature is enabled, wraps the body in a `RegionGuard`
/// that measures cycles, instructions, cache misses, etc. When disabled,
/// compiles to a zero-cost pass-through.
///
/// # Example
///
/// ```rust,no_run
/// # use symbiotic::region;
/// fn process(data: &mut [f64]) -> f64 {
///     region!("sort", {
///         data.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
///     });
///     region!("sum", {
///         data.iter().sum()
///     })
/// }
/// ```
#[cfg(feature = "profiling")]
#[macro_export]
macro_rules! region {
    ($name:expr, $body:expr) => {{
        let _guard = $crate::RegionGuard::new($name);
        $body
    }};
}

/// No-op version when profiling is disabled.
#[cfg(not(feature = "profiling"))]
#[macro_export]
macro_rules! region {
    ($name:expr, $body:expr) => {
        $body
    };
}

/// Awaken the organism's nervous system.
///
/// Call this once at the start of `main()`. It:
/// 1. Loads the BPF sense_hub (59 tracepoints → 96 kernel counters)
/// 2. Enables sensory deltas in every `region!()` / `#[profile]` guard
///
/// After this call, every `RegionGuard` automatically captures kernel events
/// (page faults, context switches, I/O, lock contention) alongside PMU counters.
/// Cost: ~8 volatile loads per region entry+exit = ~10 cycles.
///
/// If BPF is unavailable (no `ebpf` feature, no permissions), this is a no-op.
/// Regions still capture PMU counters and wall time.
///
/// # Example
///
/// ```rust,ignore
/// fn main() {
///     symbiotic::init();  // ← one call, everything instrumented
///
///     region!("my_work", {
///         do_stuff();
///     });
///
///     // Report is shown automatically via BenchProfiler::report()
/// }
/// ```
pub fn init() {
    #[cfg(feature = "ebpf")]
    {
        senses::init_zero_copy();
    }
}

/// Initialize the profiling subscriber and return a handle to get the report
pub fn init_profiling() -> ProfilerHandle {
    let profiling_layer = ProfilingLayer::new();
    let handle = ProfilerHandle {
        layer: profiling_layer.clone(),
    };

    let subscriber = Registry::default()
        .with(profiling_layer);

    tracing::subscriber::set_global_default(subscriber)
        .expect("Failed to set global tracing subscriber");

    handle
}

/// Initialize profiling with custom configuration
pub fn init_with_config(config: ProfilerConfig) -> ProfilerHandle {
    let profiling_layer = ProfilingLayer::with_config(config);
    let handle = ProfilerHandle {
        layer: profiling_layer.clone(),
    };

    let subscriber = Registry::default()
        .with(profiling_layer);

    tracing::subscriber::set_global_default(subscriber)
        .expect("Failed to set global tracing subscriber");

    handle
}

/// Configuration for the profiler
#[derive(Clone, Debug)]
pub struct ProfilerConfig {
    /// Sampling interval in milliseconds
    pub sample_interval_ms: u64,
    /// Enable hardware performance counters
    pub enable_perf: bool,
    /// Enable jemalloc statistics
    pub enable_jemalloc: bool,
    /// Enable thread pool monitoring
    pub enable_threads: bool,
    /// Maximum number of samples to keep in memory
    pub max_samples: usize,
    /// Benchmark name
    pub benchmark_name: String,
    /// Query server TCP port (None = disabled). Requires `server` feature.
    /// Also reads SYMBIOT_PORT env var at startup.
    pub server_port: Option<u16>,
    /// Unix domain socket path (None = disabled). Requires `server-uds` feature.
    /// Also reads SYMBIOT_SOCK env var at startup.
    pub server_socket: Option<std::path::PathBuf>,
    /// gRPC server port (None = disabled). Requires `server-grpc` feature.
    /// Also reads SYMBIOT_GRPC_PORT env var at startup.
    pub server_grpc_port: Option<u16>,
}

impl Default for ProfilerConfig {
    fn default() -> Self {
        // Check env vars for server config.
        // When `dashboard` feature is enabled, default to port 9882 so the
        // web UI is available without requiring SYMBIOT_PORT to be set.
        let server_port = std::env::var("SYMBIOT_PORT").ok()
            .and_then(|s| s.parse::<u16>().ok())
            .or({
                #[cfg(feature = "dashboard")]
                { Some(9882) }
                #[cfg(not(feature = "dashboard"))]
                { None }
            });
        let server_socket = std::env::var("SYMBIOT_SOCK").ok()
            .map(std::path::PathBuf::from);
        let server_grpc_port = std::env::var("SYMBIOT_GRPC_PORT").ok()
            .and_then(|s| s.parse::<u16>().ok());

        Self {
            sample_interval_ms: 1,    // 1ms = 1000Hz sampling
            enable_perf: true,         // Enable all hardware counters
            enable_jemalloc: true,     // Track allocations via jemalloc-ctl
            enable_threads: true,      // Monitor all threads
            max_samples: 1000000,      // Maximum samples for high frequency
            benchmark_name: "benchmark".to_string(),
            server_port,
            server_socket,
            server_grpc_port,
        }
    }
}

// No alternative configurations - always use the default aggressive settings

/// Handle to the profiler for getting reports
pub struct ProfilerHandle {
    layer: ProfilingLayer,
}

impl ProfilerHandle {
    /// Get the final profiling report
    pub fn report(&self) -> ProfileReport {
        self.layer.get_report()
    }

    /// Stop profiling and get the final report
    pub fn finish(self) -> ProfileReport {
        self.layer.stop();
        self.layer.get_report()
    }

    /// Report bytes processed by the benchmark
    pub fn report_bytes(&self, bytes: u64) {
        self.layer.report_bytes(bytes);
    }

    /// Report rows processed by the benchmark
    pub fn report_rows(&self, rows: u64) {
        self.layer.report_rows(rows);
    }

    /// Report both bytes and rows processed
    pub fn report_throughput(&self, bytes: u64, rows: u64) {
        self.layer.report_bytes(bytes);
        self.layer.report_rows(rows);
    }

    /// Dump a heap profile in pprof format (requires jemalloc feature)
    ///
    /// Returns gzipped protobuf data that can be analyzed with pprof:
    /// ```ignore
    /// let pprof_data = profiler.dump_heap_profile().await?;
    /// std::fs::write("heap.pb.gz", pprof_data)?;
    /// // Then analyze with: pprof -http=:8080 heap.pb.gz
    /// ```
    #[cfg(feature = "jemalloc")]
    pub async fn dump_heap_profile(&self) -> Result<Vec<u8>, String> {
        self.layer.dump_heap_profile().await
    }

    /// Dump a heap flamegraph in SVG format (requires jemalloc feature)
    ///
    /// Returns an interactive SVG that can be viewed in a browser:
    /// ```ignore
    /// let svg = profiler.dump_heap_flamegraph().await?;
    /// std::fs::write("heap_flamegraph.svg", svg)?;
    /// ```
    #[cfg(feature = "jemalloc")]
    pub async fn dump_heap_flamegraph(&self) -> Result<Vec<u8>, String> {
        self.layer.dump_heap_flamegraph().await
    }
}