donpat1to/watcheragent
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

added commentation

Browse Source
This commit is contained in:
Patrick Mahnke-Hartmann
2025-10-01 12:07:53 +02:00
parent d994be757e
commit 8c49a63a50
13 changed files with 570 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
WatcherAgent/src/hardware/cpu.rs
View File

@@ -2,6 +2,29 @@ use anyhow::Result;
use std::error::Error;
use sysinfo::System;
//! # CPU Hardware Module
//!
//! This module provides CPU information collection for WatcherAgent, including load, temperature, and system uptime.
//!
//! ## Responsibilities
//! - **CPU Detection:** Identifies CPU model and core count.
//! - **Metric Collection:** Queries CPU load, temperature, and uptime.
//! - **Error Handling:** Graceful fallback if metrics are unavailable.
//!
//! ## Units
//! - `current_load`: CPU usage as a percentage (**0.0–100.0**)
//! - `current_temp`: CPU temperature in **degrees Celsius (°C)**
//! - `uptime`: System uptime in **seconds (s)**
//!
/// CPU statistics for the host system.
///
/// # Fields
/// - `name`: CPU model name (string)
/// - `cores`: Number of physical CPU cores (integer)
/// - `current_load`: CPU usage as a percentage (**0.0–100.0**)
/// - `current_temp`: CPU temperature in **degrees Celsius (°C)**
/// - `uptime`: System uptime in **seconds (s)**
/// - `host_name`: Hostname of the system (string)
#[derive(Debug)]
pub struct CpuInfo {
pub name: Option<String>,
@@ -12,6 +35,10 @@ pub struct CpuInfo {
pub host_name: Option<String>,
}
/// Collects CPU information (model, cores, load, temperature, uptime).
///
/// # Returns
/// * `Result<CpuInfo, Box<dyn Error + Send + Sync>>` - CPU statistics or error if unavailable.
pub async fn get_cpu_info() -> Result<CpuInfo, Box<dyn Error + Send + Sync>> {
let mut sys = System::new_all();
@@ -33,12 +60,23 @@ pub async fn get_cpu_info() -> Result<CpuInfo, Box<dyn Error + Send + Sync>> {
})
}
/// Queries system for current CPU load (percentage).
///
/// # Arguments
/// * `sys` - Mutable reference to sysinfo::System
///
/// # Returns
/// * `Result<f64, Box<dyn Error + Send + Sync>>` - CPU load as percentage.
pub async fn get_cpu_load(sys: &mut System) -> Result<f64, Box<dyn Error + Send + Sync>> {
sys.refresh_cpu_all();
tokio::task::yield_now().await; // Allow other tasks to run
Ok(sys.global_cpu_usage() as f64)
}
/// Attempts to read CPU temperature from system sensors (Linux only).
///
/// # Returns
/// * `Result<f64, Box<dyn Error + Send + Sync>>` - CPU temperature in degrees Celsius (°C).
pub async fn get_cpu_temp() -> Result<f64, Box<dyn Error + Send + Sync>> {
println!("Attempting to get CPU temperature...");

27
WatcherAgent/src/hardware/disk.rs
View File

@@ -7,6 +7,27 @@ use sysinfo::{Component, Components, Disk, Disks};
use serde::Serialize;
//! # Disk Hardware Module
//!
//! This module provides disk information collection for WatcherAgent, including total and per-disk statistics and temperature data.
//!
//! ## Responsibilities
//! - **Disk Enumeration:** Lists all physical disks and their properties.
//! - **Usage Calculation:** Computes total and per-disk usage, available space, and usage percentage.
//! - **Temperature Monitoring:** Associates disk components with temperature sensors if available.
//!
//! ## Units
//! - All sizes are in **bytes** unless otherwise noted.
//! - Temperatures are in **degrees Celsius (°C)**.
//!
/// Summary of disk statistics for the system.
///
/// # Fields
/// - `total_size`: Total disk size in bytes (all disks > 100MB)
/// - `total_used`: Total used disk space in bytes
/// - `total_available`: Total available disk space in bytes
/// - `total_usage`: Usage percentage (0.0–100.0)
/// - `detailed_info`: Vector of [`DiskInfoDetailed`] for each disk
#[derive(Serialize, Debug)]
pub struct DiskInfo {
pub total_size: Option<f64>,
@@ -16,6 +37,12 @@ pub struct DiskInfo {
pub detailed_info: Vec<DiskInfoDetailed>,
}
/// Collects disk information for all detected disks, including usage and temperature.
///
/// This function enumerates all disks, calculates usage statistics, and attempts to associate temperature sensors with disk components.
///
/// # Returns
/// * `Result<DiskInfo, Box<dyn std::error::Error + Send + Sync>>` - Disk statistics and details, or error if collection fails.
pub async fn get_disk_info() -> Result<DiskInfo, Box<dyn std::error::Error + Send + Sync>> {
let disks = Disks::new_with_refreshed_list();
let mut detailed_info = Vec::new();

33
WatcherAgent/src/hardware/gpu.rs
View File

@@ -2,6 +2,29 @@ use anyhow::Result;
use nvml_wrapper::Nvml;
use std::error::Error;
//! # GPU Hardware Module
//!
//! This module provides GPU information collection for WatcherAgent, including load, temperature, and VRAM statistics.
//!
//! ## Responsibilities
//! - **GPU Detection:** Identifies GPU model and capabilities.
//! - **Metric Collection:** Queries GPU load, temperature, and VRAM usage using NVML (NVIDIA only).
//! - **Error Handling:** Graceful fallback if GPU or NVML is unavailable.
//!
//! ## Units
//! - `current_load`: GPU usage as a percentage (**0.0–100.0**)
//! - `current_temp`: GPU temperature in **degrees Celsius (°C)**
//! - `vram_total`: Total VRAM in **megabytes (MB)**
//! - `vram_used`: Used VRAM in **megabytes (MB)**
//!
/// GPU statistics for the host system.
///
/// # Fields
/// - `name`: GPU model name (string)
/// - `current_load`: GPU usage as a percentage (**0.0–100.0**)
/// - `current_temp`: GPU temperature in **degrees Celsius (°C)**
/// - `vram_total`: Total VRAM in **megabytes (MB)**
/// - `vram_used`: Used VRAM in **megabytes (MB)**
#[derive(Debug)]
pub struct GpuInfo {
pub name: Option<String>,
@@ -11,6 +34,12 @@ pub struct GpuInfo {
pub vram_used: Option<f64>,
}
/// Collects GPU information (load, temperature, VRAM) using NVML.
///
/// This function attempts to query the first NVIDIA GPU using NVML. If unavailable, it returns a fallback with only the detected GPU name.
///
/// # Returns
/// * `Result<GpuInfo, Box<dyn Error + Send + Sync>>` - GPU statistics or fallback if unavailable.
pub async fn get_gpu_info() -> Result<GpuInfo, Box<dyn Error + Send + Sync>> {
match get_gpu_metrics() {
Ok((gpu_temp, gpu_load, vram_used, vram_total)) => {
@@ -37,6 +66,10 @@ pub async fn get_gpu_info() -> Result<GpuInfo, Box<dyn Error + Send + Sync>> {
}
}
/// Queries NVML for GPU metrics: temperature, load, VRAM used/total.
///
/// # Returns
/// * `Result<(f64, f64, f64, f64), Box<dyn Error + Send + Sync>>` - Tuple of (temperature °C, load %, VRAM used MB, VRAM total MB).
pub fn get_gpu_metrics() -> Result<(f64, f64, f64, f64), Box<dyn Error + Send + Sync>> {
let nvml = Nvml::init();
if let Ok(nvml) = nvml {

29
WatcherAgent/src/hardware/memory.rs
View File

@@ -3,6 +3,24 @@ use std::error::Error;
use anyhow::Result;
use sysinfo::System;
//! # Memory Hardware Module
//!
//! This module provides memory information collection for WatcherAgent, including total, used, and free RAM.
//!
//! ## Responsibilities
//! - **Memory Detection:** Queries system for total, used, and free RAM.
//! - **Usage Calculation:** Computes memory usage percentage.
//! - **Error Handling:** Graceful fallback if metrics are unavailable.
//!
//! ## Units
//! - `total`, `used`, `free`: RAM in **megabytes (MB)**
//!
/// Memory statistics for the host system.
///
/// # Fields
/// - `total`: Total RAM in **megabytes (MB)**
/// - `used`: Used RAM in **megabytes (MB)**
/// - `free`: Free RAM in **megabytes (MB)**
#[derive(Debug)]
pub struct MemoryInfo {
pub total: Option<f64>,
@@ -10,6 +28,10 @@ pub struct MemoryInfo {
pub free: Option<f64>,
}
/// Collects memory information (total, used, free RAM).
///
/// # Returns
/// * `Result<MemoryInfo>` - Memory statistics or error if unavailable.
pub async fn get_memory_info() -> Result<MemoryInfo> {
let mut sys = System::new();
sys.refresh_memory();
@@ -21,6 +43,13 @@ pub async fn get_memory_info() -> Result<MemoryInfo> {
})
}
/// Computes memory usage percentage from sysinfo::System.
///
/// # Arguments
/// * `sys` - Mutable reference to sysinfo::System
///
/// # Returns
/// * `Result<f64, Box<dyn Error + Send + Sync>>` - Memory usage as percentage.
pub fn _get_memory_usage(sys: &mut System) -> Result<f64, Box<dyn Error + Send + Sync>> {
sys.refresh_memory();
Ok((sys.used_memory() as f64 / sys.total_memory() as f64) * 100.0)

21
WatcherAgent/src/hardware/mod.rs
View File

@@ -14,6 +14,23 @@ pub use memory::get_memory_info;
pub use network::get_network_info;
pub use network::NetworkMonitor;
//! # Hardware Module
//!
//! This module aggregates all hardware subsystems for WatcherAgent, providing unified collection and access to CPU, GPU, memory, disk, and network statistics.
//!
//! ## Responsibilities
//! - **Subsystem Aggregation:** Combines all hardware modules into a single struct for easy access.
//! - **Unified Collection:** Provides a single async method to collect all hardware metrics at once.
//!
/// Aggregated hardware statistics for the host system.
///
/// # Fields
/// - `cpu`: CPU statistics (see [`CpuInfo`])
/// - `gpu`: GPU statistics (see [`GpuInfo`])
/// - `memory`: Memory statistics (see [`MemoryInfo`])
/// - `disk`: Disk statistics (see [`DiskInfo`])
/// - `network`: Network statistics (see [`NetworkInfo`])
/// - `network_monitor`: Rolling monitor for network bandwidth
#[derive(Debug)]
pub struct HardwareInfo {
pub cpu: cpu::CpuInfo,
@@ -25,6 +42,10 @@ pub struct HardwareInfo {
}
impl HardwareInfo {
/// Collects all hardware statistics asynchronously.
///
/// # Returns
/// * `Result<HardwareInfo, Box<dyn Error + Send + Sync>>` - Aggregated hardware statistics or error if any subsystem fails.
pub async fn collect() -> Result<Self, Box<dyn Error + Send + Sync>> {
let mut network_monitor = network::NetworkMonitor::new();
Ok(Self {

37
WatcherAgent/src/hardware/network.rs
View File

@@ -2,6 +2,24 @@ use std::error::Error;
use std::result::Result;
use std::time::Instant;
//! # Network Hardware Module
//!
//! This module provides network information collection for WatcherAgent, including interface enumeration and bandwidth statistics.
//!
//! ## Responsibilities
//! - **Interface Detection:** Lists all network interfaces.
//! - **Bandwidth Monitoring:** Tracks receive/transmit rates using a rolling monitor.
//! - **Error Handling:** Graceful fallback if metrics are unavailable.
//!
//! ## Units
//! - `rx_rate`, `tx_rate`: Network bandwidth in **bytes per second (B/s)**
//!
/// Network statistics for the host system.
///
/// # Fields
/// - `interfaces`: List of network interface names (strings)
/// - `rx_rate`: Receive bandwidth in **bytes per second (B/s)**
/// - `tx_rate`: Transmit bandwidth in **bytes per second (B/s)**
#[derive(Debug)]
pub struct NetworkInfo {
pub interfaces: Option<Vec<String>>,
@@ -9,6 +27,13 @@ pub struct NetworkInfo {
pub tx_rate: Option<f64>,
}
/// Rolling monitor for network bandwidth statistics.
///
/// # Fields
/// - `prev_rx`: Previous received bytes
/// - `prev_tx`: Previous transmitted bytes
/// - `last_update`: Timestamp of last update
#[derive(Debug)]
pub struct NetworkMonitor {
prev_rx: u64,
@@ -23,6 +48,7 @@ impl Default for NetworkMonitor {
}
impl NetworkMonitor {
/// Creates a new `NetworkMonitor` for bandwidth tracking.
pub fn new() -> Self {
Self {
prev_rx: 0,
@@ -31,6 +57,10 @@ impl NetworkMonitor {
}
}
/// Updates the network usage statistics and returns current rx/tx rates.
///
/// # Returns
/// * `Result<(f64, f64), Box<dyn Error>>` - Tuple of (rx_rate, tx_rate) in bytes per second.
pub fn update_usage(&mut self) -> Result<(f64, f64), Box<dyn Error>> {
let (current_rx, current_tx) = get_network_bytes()?;
let elapsed = self.last_update.elapsed().as_secs_f64();
@@ -55,6 +85,13 @@ impl NetworkMonitor {
}
}
/// Collects network information (interfaces, rx/tx rates) using a monitor.
///
/// # Arguments
/// * `monitor` - Mutable reference to a `NetworkMonitor`
///
/// # Returns
/// * `Result<NetworkInfo, Box<dyn Error>>` - Network statistics or error if unavailable.
pub async fn get_network_info(monitor: &mut NetworkMonitor) -> Result<NetworkInfo, Box<dyn Error>> {
let (rx_rate, tx_rate) = monitor.update_usage()?;
Ok(NetworkInfo {