mblt-tracker 0.0.1__tar.gz

mblt_tracker-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Mobilint, Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mblt_tracker-0.0.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: mblt-tracker
+Version: 0.0.1
+Summary: A Python library to track device usage, such as Mobilint NPU, NVIDIA GPU, Intel CPU, ...
+Author-email: "Mobilint Inc." <tech-support@mobilint.com>
+License: BSD-3-Clause
+Project-URL: Home, https://www.mobilint.com/
+Project-URL: Repository, https://github.com/mobilint/mblt-tracker
+Project-URL: Documentation, https://github.com/mobilint/mblt-tracker#readme
+Project-URL: Issues, https://github.com/mobilint/mblt-tracker/issues
+Keywords: python,energy,power,utilization,memory,energy-consumption,NPU,Mobilint,GPU,NVIDIA,CPU,Intel,monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: setuptools>=70.0.0
+Requires-Dist: nvidia-ml-py>=12.560.30
+Requires-Dist: apscheduler>=3.11.2
+Requires-Dist: pyRAPL>=0.2.3.1
+Requires-Dist: psutil>=7.0.0
+Dynamic: license-file
+
+# Mobilint Device Tracker
+
+<!-- markdownlint-disable MD033 -->
+<div align="center">
+<p>
+<a href="https://www.mobilint.com/" target="_blank">
+<img src="https://raw.githubusercontent.com/mobilint/mblt-tracker/master/assets/Mobilint_Logo_Primary.png" alt="Mobilint Logo" width="60%">
+</a>
+</p>
+<p>
+    <b>A lightweight Python library for tracking hardware metrics (Power, Utilization, Memory) across CPU, GPU, and NPU.</b>
+</p>
+</div>
+<!-- markdownlint-enable MD033 -->
+
+## Overview
+
+**mblt-tracker** is designed to help developers and researchers measure hardware performance with fair and consistent criteria. It provides a unified interface to poll metrics in the background while your code runs, producing both summarized statistics and detailed time-series traces.
+
+### ✨ Key Features
+
+- **Multi-Backend Support**: Unified interface for Intel CPU, NVIDIA GPU, and Mobilint NPU.
+- **Background Tracking**: Uses a background scheduler to poll metrics without blocking your main execution.
+- **Comprehensive Metrics**: Capture Power (Watts), Utilization (%), and Memory Usage (MB/%).
+- **Statistical Summaries**: Automatically calculates averages, peaks (max), and p99 values.
+- **Time-Series Traces**: Export raw data for custom plotting and analysis.
+- **Lightweight**: Minimal overhead, designed for production and research environments.
+
+---
+
+## 🚀 Installation
+
+[![PyPI - Version](https://img.shields.io/pypi/v/mblt-tracker?logo=pypi&logoColor=white)](https://pypi.org/project/mblt-tracker/)
+[![PyPI Downloads](https://static.pepy.tech/badge/mblt-tracker?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://clickpy.clickhouse.com/dashboard/mblt-tracker)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mblt-tracker?logo=python&logoColor=gold)](https://pypi.org/project/mblt-tracker/)
+
+```bash
+pip install mblt-tracker
+```
+
+For the latest features, install directly from source:
+
+```bash
+git clone https://github.com/mobilint/mblt-tracker.git
+cd mblt-tracker
+pip install -e .
+```
+
+---
+
+## 📖 Quick Start Guide
+
+The typical workflow involves initializing a tracker, starting it before your target workload, and stopping it after.
+
+```python
+from mblt_tracker import CPUDeviceTracker # or GPUDeviceTracker, NPUDeviceTracker
+
+# 1. Initialize with a polling interval (seconds)
+tracker = CPUDeviceTracker(interval=0.1)
+
+# 2. Start tracking (best to run after warm-up)
+tracker.start()
+
+# --- Your workload starts here ---
+# e.g., model.inference(data)
+# --- Your workload ends here ---
+
+# 3. Stop tracking
+tracker.stop()
+
+# 4. Access results
+metrics = tracker.get_metric()
+print(f"Average Power: {metrics['avg_power_w']:.2f} W")
+print(f"Max Utilization: {metrics['max_utilization_pct']:.2f} %")
+
+# 5. Export time-series trace (list of (timestamp, power_w))
+trace = tracker.get_trace()
+```
+
+---
+
+## 📊 Metrics Coverage
+
+| Metric | Intel CPU | NVIDIA GPU | Mobilint NPU |
+| :--- | :---: | :---: | :---: |
+| **Power (W)** | ✅ (RAPL) | ✅ (NVML) | ✅ (`mobilint-cli`) |
+| **Utilization (%)** | ✅ (`psutil`) | ✅ (NVML) | ✅ (`mobilint-cli`) |
+| **Memory (MB/%)** | ✅ (`psutil`) | ✅ (NVML) | ✅ (`mobilint-cli`) |
+| **Per-Device Stats** | ✅ (Sockets) | ✅ (GPU Indices) | ❌ (Global/Total) |
+
+---
+
+## 🛠️ Hardware Specifics
+
+### Intel CPU
+
+Uses **pyRAPL** for power measurements and **psutil** for utilization/memory.
+
+- **Permission**: Requires read access to Intel RAPL sysfs.
+
+  ```bash
+  sudo chmod -R a+r /sys/class/powercap/intel-rapl/
+  ```
+
+- **Docker**: Run containers with `--privileged` or mount the powercap directory.
+
+- **Features**: Tracks total system CPU usage or specific indices (e.g., `CPUDeviceTracker(cpu_id=[0, 1])`).
+
+### NVIDIA GPU
+
+Uses **NVML** (via `nvidia-ml-py`) for high-fidelity hardware monitoring.
+
+- **Features**: Tracks total system GPU usage or specific indices (e.g., `GPUDeviceTracker(gpu_id=[0, 1])`).
+- **Dependencies**: Requires NVIDIA Drivers and NVML library installed.
+
+### Mobilint NPU
+
+Polls the `mobilint-cli status` command.
+
+- **Platform**: Currently supports **Linux only**.
+- **Requirement**: Ensure [Mobilint Utility Tool](https://docs.mobilint.com/v1.0/en/installing_utility.html) is installed and `mobilint-cli` is in your PATH.
+- **NPU Power**: Distinguishes between NPU-specific power and total system power.
+
+---
+
+## 📝 Metric Output Format
+
+Calling `get_metric()` returns a dictionary with the following standard keys (where applicable):
+
+```json
+{
+  "avg_power_w": 25.4,          // Average total power in Watts
+  "max_power_w": 45.2,          // Peak power observed
+  "p99_power_w": 40.1,          // 99th percentile power
+  "avg_utilization_pct": 78.5,  // Average device utilization
+  "max_utilization_pct": 95.0,  // Peak device utilization
+  "avg_memory_used_mb": 2048.0, // Average memory usage
+  "total_memory_mb": 8192.0,    // Total available memory
+  "samples": 100                // Number of data points collected
+}
+```
+
+*Note: Some trackers provide additional keys like `cpu` or `gpu` for per-socket/per-device breakdown.*
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! To set up for development:
+
+1. Install dev dependencies: `pip install -e ".[dev]"`
+2. Run tests: `pytest tests/`
+
+## 📄 License
+
+This project is licensed under the **BSD-3-Clause License**. See the [LICENSE](https://github.com/mobilint/mblt-tracker/blob/master/LICENSE) file for details.
+
+---
+
+<!-- markdownlint-disable MD033 -->
+<div align="center">
+    <small>Developed with ❤️ by <a href="https://www.mobilint.com/">Mobilint Inc.</a></small>
+</div>
+<!-- markdownlint-enable MD033 -->

mblt_tracker-0.0.1/README.md

@@ -0,0 +1,164 @@
+# Mobilint Device Tracker
+
+<!-- markdownlint-disable MD033 -->
+<div align="center">
+<p>
+<a href="https://www.mobilint.com/" target="_blank">
+<img src="https://raw.githubusercontent.com/mobilint/mblt-tracker/master/assets/Mobilint_Logo_Primary.png" alt="Mobilint Logo" width="60%">
+</a>
+</p>
+<p>
+    <b>A lightweight Python library for tracking hardware metrics (Power, Utilization, Memory) across CPU, GPU, and NPU.</b>
+</p>
+</div>
+<!-- markdownlint-enable MD033 -->
+
+## Overview
+
+**mblt-tracker** is designed to help developers and researchers measure hardware performance with fair and consistent criteria. It provides a unified interface to poll metrics in the background while your code runs, producing both summarized statistics and detailed time-series traces.
+
+### ✨ Key Features
+
+- **Multi-Backend Support**: Unified interface for Intel CPU, NVIDIA GPU, and Mobilint NPU.
+- **Background Tracking**: Uses a background scheduler to poll metrics without blocking your main execution.
+- **Comprehensive Metrics**: Capture Power (Watts), Utilization (%), and Memory Usage (MB/%).
+- **Statistical Summaries**: Automatically calculates averages, peaks (max), and p99 values.
+- **Time-Series Traces**: Export raw data for custom plotting and analysis.
+- **Lightweight**: Minimal overhead, designed for production and research environments.
+
+---
+
+## 🚀 Installation
+
+[![PyPI - Version](https://img.shields.io/pypi/v/mblt-tracker?logo=pypi&logoColor=white)](https://pypi.org/project/mblt-tracker/)
+[![PyPI Downloads](https://static.pepy.tech/badge/mblt-tracker?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://clickpy.clickhouse.com/dashboard/mblt-tracker)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mblt-tracker?logo=python&logoColor=gold)](https://pypi.org/project/mblt-tracker/)
+
+```bash
+pip install mblt-tracker
+```
+
+For the latest features, install directly from source:
+
+```bash
+git clone https://github.com/mobilint/mblt-tracker.git
+cd mblt-tracker
+pip install -e .
+```
+
+---
+
+## 📖 Quick Start Guide
+
+The typical workflow involves initializing a tracker, starting it before your target workload, and stopping it after.
+
+```python
+from mblt_tracker import CPUDeviceTracker # or GPUDeviceTracker, NPUDeviceTracker
+
+# 1. Initialize with a polling interval (seconds)
+tracker = CPUDeviceTracker(interval=0.1)
+
+# 2. Start tracking (best to run after warm-up)
+tracker.start()
+
+# --- Your workload starts here ---
+# e.g., model.inference(data)
+# --- Your workload ends here ---
+
+# 3. Stop tracking
+tracker.stop()
+
+# 4. Access results
+metrics = tracker.get_metric()
+print(f"Average Power: {metrics['avg_power_w']:.2f} W")
+print(f"Max Utilization: {metrics['max_utilization_pct']:.2f} %")
+
+# 5. Export time-series trace (list of (timestamp, power_w))
+trace = tracker.get_trace()
+```
+
+---
+
+## 📊 Metrics Coverage
+
+| Metric | Intel CPU | NVIDIA GPU | Mobilint NPU |
+| :--- | :---: | :---: | :---: |
+| **Power (W)** | ✅ (RAPL) | ✅ (NVML) | ✅ (`mobilint-cli`) |
+| **Utilization (%)** | ✅ (`psutil`) | ✅ (NVML) | ✅ (`mobilint-cli`) |
+| **Memory (MB/%)** | ✅ (`psutil`) | ✅ (NVML) | ✅ (`mobilint-cli`) |
+| **Per-Device Stats** | ✅ (Sockets) | ✅ (GPU Indices) | ❌ (Global/Total) |
+
+---
+
+## 🛠️ Hardware Specifics
+
+### Intel CPU
+
+Uses **pyRAPL** for power measurements and **psutil** for utilization/memory.
+
+- **Permission**: Requires read access to Intel RAPL sysfs.
+
+  ```bash
+  sudo chmod -R a+r /sys/class/powercap/intel-rapl/
+  ```
+
+- **Docker**: Run containers with `--privileged` or mount the powercap directory.
+
+- **Features**: Tracks total system CPU usage or specific indices (e.g., `CPUDeviceTracker(cpu_id=[0, 1])`).
+
+### NVIDIA GPU
+
+Uses **NVML** (via `nvidia-ml-py`) for high-fidelity hardware monitoring.
+
+- **Features**: Tracks total system GPU usage or specific indices (e.g., `GPUDeviceTracker(gpu_id=[0, 1])`).
+- **Dependencies**: Requires NVIDIA Drivers and NVML library installed.
+
+### Mobilint NPU
+
+Polls the `mobilint-cli status` command.
+
+- **Platform**: Currently supports **Linux only**.
+- **Requirement**: Ensure [Mobilint Utility Tool](https://docs.mobilint.com/v1.0/en/installing_utility.html) is installed and `mobilint-cli` is in your PATH.
+- **NPU Power**: Distinguishes between NPU-specific power and total system power.
+
+---
+
+## 📝 Metric Output Format
+
+Calling `get_metric()` returns a dictionary with the following standard keys (where applicable):
+
+```json
+{
+  "avg_power_w": 25.4,          // Average total power in Watts
+  "max_power_w": 45.2,          // Peak power observed
+  "p99_power_w": 40.1,          // 99th percentile power
+  "avg_utilization_pct": 78.5,  // Average device utilization
+  "max_utilization_pct": 95.0,  // Peak device utilization
+  "avg_memory_used_mb": 2048.0, // Average memory usage
+  "total_memory_mb": 8192.0,    // Total available memory
+  "samples": 100                // Number of data points collected
+}
+```
+
+*Note: Some trackers provide additional keys like `cpu` or `gpu` for per-socket/per-device breakdown.*
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! To set up for development:
+
+1. Install dev dependencies: `pip install -e ".[dev]"`
+2. Run tests: `pytest tests/`
+
+## 📄 License
+
+This project is licensed under the **BSD-3-Clause License**. See the [LICENSE](https://github.com/mobilint/mblt-tracker/blob/master/LICENSE) file for details.
+
+---
+
+<!-- markdownlint-disable MD033 -->
+<div align="center">
+    <small>Developed with ❤️ by <a href="https://www.mobilint.com/">Mobilint Inc.</a></small>
+</div>
+<!-- markdownlint-enable MD033 -->

mblt_tracker-0.0.1/mblt_tracker/__init__.py

@@ -0,0 +1,17 @@
+"""Mobilint Device Tracker package for monitoring CPU, GPU, and NPU metrics.
+
+This package provides classes for tracking power usage, utilization, and memory
+consumption across different hardware backends.
+"""
+
+__version__ = "0.0.1"
+
+from .device_tracker_cpu import CPUDeviceTracker
+from .device_tracker_gpu import GPUDeviceTracker
+from .device_tracker_npu import NPUDeviceTracker
+
+__all__ = [
+    "CPUDeviceTracker",
+    "GPUDeviceTracker",
+    "NPUDeviceTracker",
+]

mblt_tracker-0.0.1/mblt_tracker/device_tracker.py

@@ -0,0 +1,84 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from apscheduler.schedulers.background import BackgroundScheduler
+from apscheduler.schedulers.base import STATE_RUNNING
+
+
+class BaseDeviceTracker(ABC):
+    """Abstract base class for device trackers."""
+
+    def __init__(self, interval: float, **kwargs):
+        """Initialize the device tracker.
+
+        Args:
+            interval (float): The interval in seconds at which the device should be polled.
+            **kwargs: Additional keyword arguments for parent classes.
+
+        Raises:
+            ValueError: If the interval is not positive.
+        """
+        super().__init__(**kwargs)
+        if interval <= 0:
+            raise ValueError("interval must be positive")
+        self._interval = interval
+        self._scheduler: Optional[BackgroundScheduler] = None
+        self._job_id: str = "device_track"
+
+    def start(self) -> None:
+        """Start tracking device metrics periodically."""
+        self.reset()
+        try:
+            self._func_for_sched()
+        except Exception:
+            pass
+        if self._scheduler is None or self._scheduler.state != STATE_RUNNING:
+            self._scheduler = BackgroundScheduler()
+            self._scheduler.start()
+
+        # Ensure _scheduler is not None for the linter
+        if self._scheduler is not None:
+            if self._scheduler.get_job(self._job_id) is not None:
+                self._scheduler.remove_job(self._job_id)
+            self._scheduler.add_job(
+                self._func_for_sched,
+                "interval",
+                seconds=self._interval,
+                id=self._job_id,
+            )
+
+    def stop(self) -> None:
+        """Stop tracking device metrics and shut down the scheduler."""
+        try:
+            self._func_for_sched()
+        except Exception:
+            pass
+        if self._scheduler is not None:
+            try:
+                self._scheduler.shutdown(wait=True)
+            finally:
+                self._scheduler = None
+
+    @abstractmethod
+    def _func_for_sched(self) -> None:
+        """Scheduled function to capture a single sample of metrics."""
+
+    @abstractmethod
+    def get_metric(self) -> dict:
+        """Return summarized device metrics since start or last reset.
+
+        Returns:
+            Dict: A dictionary containing averaged and peak metrics.
+        """
+
+    @abstractmethod
+    def get_trace(self) -> list[tuple[float, float]]:
+        """Return a time-series trace of power measurements.
+
+        Returns:
+            List[Tuple[float, float]]: A list of (timestamp, power_watt) pairs.
+        """
+
+    @abstractmethod
+    def reset(self) -> None:
+        """Clear all collected metrics and traces."""