Add metrics monitoring functionality with callback support

DefinetlyNotAI · DefinetlyNotAI · commit 1d1ec99d5cf7 · 2025-08-17T01:50:04.000+03:00
Now there is an easy way to natively get stable stream of data X interval for Y amount of time, or until you explicitly stop!
Updated the C code, the Python Lib Wrapper, and the example script
Updated SECURITY.md as well
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,9 +1,14 @@
 ## Supported Versions
 
-| Version | Supported | Release Date |
-|---------|-----------|--------------|
-| 0.2.x   | ✅         | 7th Aug 2025 |
-| 0.1.x   | ❌         | 7th Aug 2025 |
+| Version | Supported | Release Date  |
+|---------|-----------|---------------|
+| 0.3.x   | ✅         | 17th Aug 2025 |
+| 0.2.x   | ✅         | 13th Aug 2025 |
+| 0.1.x   | ❌         | 7th Aug 2025  |
+
+> v0.1.0 cannot be found in the release section, it was a dev version that was never released to the public.
+> 
+> v0.2.0-beta is the first public release, and it is a beta version. It also supports `pip`
 
 ## Reporting a Vulnerability
 
diff --git a/TODO.md b/TODO.md
@@ -1,9 +1,3 @@
-| Item           | Description                                                                                                                                                                                 | Priority | Version to Expect |
-|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-------------------|
-| processInspect | Add an ondemand feature to process inspect: monitor an app and send data at intervals to the caller (possibly async), with .end to stop, and support for flags. Useful for sysadmin panels. | High     | 0.3.0-beta        |
-
-
-Docs to update:
-- hRNG Python
-- hRNG C
-- Helper tools: Compiling (minor changes)
+| Item    | Description | Priority | Version to Expect |
+|---------|-------------|----------|-------------------|
+| Nothing | ???         | ???      | ???               |
diff --git a/example/processInspect.py b/example/processInspect.py
@@ -5,8 +5,9 @@
 1. Setting up the ProcessMetrics module
 2. Using both session-based and snapshot monitoring approaches
 3. Working with all available metric types
-4. Interpreting and displaying the collected metrics
+4. Interpreting and displaying the metrics
 5. Proper error handling and best practices
+6. Continuous monitoring with callbacks
 """
 import json
 import os
@@ -316,7 +317,7 @@ def demo_other_process_monitoring() -> None:
             print(f"  PID {proc.info['pid']}: {proc.info['name']}")
 
         # Try to monitor a system process like explorer.exe on Windows
-        target_name = "explorer.exe" if os.name == "nt" else "sshd"
+        target_name = "explorer.exe"
         target_pid = None
 
         for proc in psutil.process_iter(['pid', 'name']):
@@ -340,6 +341,119 @@ def demo_other_process_monitoring() -> None:
             print(f"\nCould not find {target_name} process")
 
 
+def demo_continuous_monitoring() -> None:
+    """
+    Demonstrates how to use continuous monitoring with callbacks.
+
+    This approach is ideal for:
+    - Real-time monitoring dashboards
+    - System administration panels
+    - Long-term resource tracking
+    - Detecting resource spikes or anomalies
+    """
+    print("\n\n" + "=" * 80)
+    print("DEMONSTRATION: CONTINUOUS MONITORING WITH CALLBACKS")
+    print("=" * 80)
+
+    metrics = ProcessMetrics()
+    pid = os.getpid()  # Monitor the current Python process
+
+    # Define the metrics we want to collect
+    flags = (
+        ProcessMetrics.METRIC_WORKING_SET |
+        ProcessMetrics.METRIC_PRIVATE_BYTES |
+        ProcessMetrics.METRIC_CPU_USAGE |
+        ProcessMetrics.METRIC_HANDLES |
+        ProcessMetrics.METRIC_THREADS
+    )
+
+    # Counter for received updates
+    updates_received = 0
+
+    # Callback function that will be called for each metrics update
+    def metrics_callback(data):
+        nonlocal updates_received
+        updates_received += 1
+        print(f"\nUpdate #{updates_received} received:")
+        print(f"  PID: {data['pid']}")
+
+        if 'working_set_kb' in data:
+            print(f"  Working Set: {data['working_set_kb']} KB")
+        if 'private_kb' in data:
+            print(f"  Private Memory: {data['private_kb']} KB")
+        if 'cpu' in data:
+            print(f"  CPU Usage: {data['cpu']}%")
+        if 'handles' in data:
+            print(f"  Handles: {data['handles']}")
+        if 'threads' in data:
+            print(f"  Threads: {data['threads']}")
+
+        # If we receive 5 updates, simulate some workload
+        if updates_received == 5:
+            print("\n  [Simulating intensive workload during monitoring...]")
+            simulate_workload(intensity=3)
+
+    # Start monitoring with a 1-second interval, run for 10 seconds
+    interval_ms = 1000  # 1 second between updates
+    duration_ms = 10000  # Run for 10 seconds total
+
+    print(f"Starting continuous monitoring for PID {pid}")
+    print(f"Interval: {interval_ms}ms, Duration: {duration_ms}ms")
+    print("Updates will be printed as they are received...")
+
+    # Start the monitoring
+    success = metrics.start_monitoring(
+        pid=pid,
+        metrics=flags,
+        interval_ms=interval_ms,
+        duration_ms=duration_ms,
+        callback=metrics_callback
+    )
+
+    if not success:
+        print("ERROR: Failed to start continuous monitoring!")
+        return
+
+    # Wait until monitoring is complete
+    print("Monitoring active. Waiting for completion...")
+
+    # Keep checking if monitoring is still active
+    while metrics.is_monitoring_active():
+        time.sleep(0.5)
+
+    print("\nMonitoring completed automatically after duration expired.")
+    print(f"Received {updates_received} updates in total.")
+
+    # Demonstrate manual stopping
+    print("\nNow demonstrating indefinite monitoring with manual stop...")
+    updates_received = 0
+
+    # Start indefinite monitoring (duration = -1)
+    success = metrics.start_monitoring(
+        pid=pid,
+        metrics=flags,
+        interval_ms=interval_ms,
+        duration_ms=-1,  # Run indefinitely
+        callback=metrics_callback
+    )
+
+    if not success:
+        print("ERROR: Failed to start indefinite monitoring!")
+        return
+
+    print("Indefinite monitoring started. Will stop after 5 seconds...")
+
+    # Let it run for 5 seconds then stop manually
+    time.sleep(5)
+
+    # Stop monitoring
+    if metrics.stop_monitoring():
+        print("\nMonitoring stopped manually.")
+        print(f"Received {updates_received} updates before stopping.")
+    else:
+        print("\nFailed to stop monitoring or monitoring was already stopped.")
+
+
 def main():
     """Main function to demonstrate all ProcessMetrics capabilities."""
     print("=" * 80)
@@ -353,6 +467,7 @@ def main():
     demo_snapshot_monitoring()
     demo_selective_metrics()
     demo_other_process_monitoring()
+    demo_continuous_monitoring()  # Added the new continuous monitoring demo
 
     print("\n" + "=" * 80)
     print("DEMONSTRATION COMPLETE")
diff --git a/pyCTools/processInspect.py b/pyCTools/processInspect.py
@@ -1,6 +1,6 @@
 import ctypes
 import json
-from ctypes import c_char_p, c_size_t, c_ulong, create_string_buffer
+from ctypes import c_char_p, c_size_t, c_ulong, create_string_buffer, CFUNCTYPE, c_void_p, c_int
 
 from pyCTools._loadDLL import load_dll
 
@@ -59,6 +59,24 @@ def __init__(self):
         self._dll.get_metrics_json.argtypes = [c_ulong, c_ulong, c_char_p, c_size_t]
         self._dll.get_metrics_json.restype = ctypes.c_int
 
+        # Define C function type for the monitoring callback
+        self._CALLBACK_TYPE = CFUNCTYPE(None, c_char_p, c_void_p)
+
+        # Set types for monitoring functions
+        self._dll.start_metrics_monitoring.argtypes = [c_ulong, c_ulong, c_ulong, c_int,
+                                                       self._CALLBACK_TYPE, c_void_p]
+        self._dll.start_metrics_monitoring.restype = ctypes.c_int
+
+        self._dll.stop_metrics_monitoring.argtypes = []
+        self._dll.stop_metrics_monitoring.restype = ctypes.c_int
+
+        self._dll.is_metrics_monitoring_active.argtypes = []
+        self._dll.is_metrics_monitoring_active.restype = ctypes.c_int
+
+        # Store callback reference to prevent garbage collection
+        self._callback_ref = None
+        self._user_callback = None
+
     @staticmethod
     def _json_call(func, pid: int, metrics: int, _buffer_size: int = 4096) -> dict:
         """
@@ -121,3 +139,70 @@ def get_snapshot(self, pid: int, metrics: int) -> dict:
             dict: Current metrics snapshot.
         """
         return self._json_call(self._dll.get_metrics_json, pid, metrics)
+
+    # noinspection PyUnusedLocal
+    def _callback_wrapper(self, json_str, user_data):
+        """
+        Internal callback wrapper that converts C JSON string to Python dict
+        and calls the user's callback function.
+
+        Args:
+            json_str (c_char_p): JSON metrics data from C.
+            user_data (c_void_p): User data pointer (unused in this implementation).
+        """
+        if self._user_callback:
+            metrics_dict = json.loads(ctypes.string_at(json_str).decode('utf-8'))
+            self._user_callback(metrics_dict)
+
+    def start_monitoring(self, pid: int, metrics: int, interval_ms: int,
+                         duration_ms: int = -1, callback=None) -> bool:
+        """
+        Start continuous monitoring of a process at specified intervals.
+
+        Args:
+            pid (int): Process ID to monitor.
+            metrics (int): Bitmask of metrics to collect (use class flags).
+            interval_ms (int): Interval between metric collections in milliseconds.
+            duration_ms (int): Total duration to monitor in milliseconds. Use -1 for
+                               indefinite monitoring until explicitly stopped.
+            callback (callable): Function to call with each metrics update.
+                                The callback receives a dict of the parsed metrics.
+
+        Returns:
+            bool: True if monitoring started successfully, False otherwise.
+        """
+        if self.is_monitoring_active():
+            return False
+
+        self._user_callback = callback
+
+        # Create C-compatible callback function
+        if callback:
+            self._callback_ref = self._CALLBACK_TYPE(self._callback_wrapper)
+        else:
+            self._callback_ref = None
+
+        return bool(self._dll.start_metrics_monitoring(
+            pid, metrics, interval_ms, duration_ms, self._callback_ref, None))
+
+    def stop_monitoring(self) -> bool:
+        """
+        Stop an active monitoring session.
+
+        Returns:
+            bool: True if monitoring was successfully stopped, False if no monitoring was active.
+        """
+        result = bool(self._dll.stop_metrics_monitoring())
+        if result:
+            self._user_callback = None
+            self._callback_ref = None
+        return result
+
+    def is_monitoring_active(self) -> bool:
+        """
+        Check if a monitoring session is currently active.
+
+        Returns:
+            bool: True if monitoring is active, False otherwise.
+        """
+        return bool(self._dll.is_metrics_monitoring_active())
diff --git a/src/processInspect.c b/src/processInspect.c
