From 93540856626c6a5d38706e8a75de27148a37cc69 Mon Sep 17 00:00:00 2001
From: prplV <maseeeeeeeed@gmail.com>
Date: Fri, 7 Mar 2025 10:21:04 +0300
Subject: [PATCH] monitoring final doc comments

---
 crates/api-grub/src/monitoring.rs | 53 +++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/crates/api-grub/src/monitoring.rs b/crates/api-grub/src/monitoring.rs
index aeacf2d..8203c4c 100644
--- a/crates/api-grub/src/monitoring.rs
+++ b/crates/api-grub/src/monitoring.rs
@@ -151,6 +151,12 @@ impl MonitoringImporter {
         Ok(())
     }
 
+    /// A function for pulling measures list
+    /// 
+    /// Used with actual credentials for current CM session
+    /// and returning measures in format of `Ok(Vec<(String, String)>)`
+    /// , where `(String, String)` is a tuple of measure `id` and `description` 
+    /// (`name`) 
     pub async fn get_metrics_list(&self) -> anyhow::Result<Vec<(String, String)>> {
         let client = Client::new();
         let mut vec: Vec<(String, String)> = Vec::new();
@@ -183,6 +189,22 @@ impl MonitoringImporter {
         info!("List of measures was pulled, total - {}", &vec.len());
         Ok(vec)
     }
+
+    /// A function to get realtime data
+    /// 
+    /// It pulles info about 1 measure or a slice of measures and 
+    /// exports all data to Prometehus exporter 
+    /// 
+    /// # How it works 
+    /// 1) creates a restriction for max count of async 
+    /// tasks (`tokio::sync::Semaphore`)
+    /// 
+    /// 2) divides vec of measures in case of creating chunks with
+    /// the most optimal sizes to optimize self and server load
+    /// 
+    /// 3) spawns async tasks-grabbers to get measures info which 
+    /// exprots all data by itselfs
+    /// 
     pub async fn get_measure_info(&self, measures: Arc<Vec<(String, String)>>) -> anyhow::Result<()> {
         let mut sys = sysinfo::System::new();
         sys.refresh_cpu_all();
@@ -225,6 +247,17 @@ impl MonitoringImporter {
         }
         Ok(())
     }
+
+    /// An async task-grabber 
+    /// 
+    /// Used to create request to the CM server and 
+    /// get all measure(s) data 
+    /// 
+    /// # Also 
+    /// An argument `measure: Arc<String>` can be a single measure like `measure$1` or
+    /// a slice of measures in special format `%5B%22measure$1%22,%20%22measure$2%22%5D`.
+    /// This is a neccesary measure to handle two types of requests and URL restrictions
+    /// 
     async fn process_endpoint(measure: Arc<String>, client: Arc<Client>, arc: Arc<Self>, hm: &HashMap<String, String>) -> anyhow::Result<PrometheusMetricsExtended> {        
         let resp = client
             .get(format!("http://{}/e-nms/mirror/measure/{}", arc.ip, &measure))
@@ -239,6 +272,21 @@ impl MonitoringImporter {
                 PrometheusMetricsExtended::new_zvks(Self::extract_metric_data(resp, hm).await?).await
             )
     }
+
+    /// An recursive extractor of data 
+    /// 
+    /// Uses target-json CM-Server response as `Value` and HashMap of 
+    /// measures' `id`s and their appropriate `description`s 
+    /// 
+    /// # How it works
+    /// 1) if `Value` is an `Object` -> executes `Self::process_value` on it and 
+    /// returns result of the function as `Vec`
+    /// 
+    /// 2) if `Value` is an `Array` -> self-executes for each pat of the array 
+    /// and aggregates all data in the `Vec` by using `.append(&mut Vec<...>)`
+    /// 
+    /// 3) if `Value` is `_` -> returns error **Invalid JSON format**
+    /// 
     fn extract_metric_data(json: Value, hm: &HashMap<String, String>) -> Pin<Box<dyn Future<Output = anyhow::Result<Vec<MetricOutputExtended>>> + Send + '_>> {
         Box::pin(async move {
             return match json {
@@ -259,6 +307,11 @@ impl MonitoringImporter {
             }
         })
     } 
+
+    /// A function-extractor for single measure object
+    /// 
+    /// Searches for certain fields and aggregates it in the `MetricOutputExtended`
+    /// object
     async fn process_value(obj : &Map<String, Value>, hm: &HashMap<String, String>) -> anyhow::Result<MetricOutputExtended> {
         let id = obj.get("$id");
         let val = obj.get("value");