> For clean Markdown content of this page, append .md to this URL.

# aitune.utils.monitoring.setup_hardware_metrics

Hardware metrics collector.

## Module Contents

### Classes

| Name                                                                                               | Description                                           |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`HardwareMetricsSession`](#aitune-utils-monitoring-setup_hardware_metrics-HardwareMetricsSession) | Manages the lifecycle of hardware metrics collection. |

### Functions

| Name                                                                                                   | Description                                                      |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| [`_split_for_logging`](#aitune-utils-monitoring-setup_hardware_metrics-_split_for_logging)             | Split a wide metrics table into narrower sub-tables for logging. |
| [`disable_hardware_metrics`](#aitune-utils-monitoring-setup_hardware_metrics-disable_hardware_metrics) | Disable hardware metrics collection at runtime.                  |
| [`dump_metrics`](#aitune-utils-monitoring-setup_hardware_metrics-dump_metrics)                         | Logs metrics summary and dumps the metrics to a CSV file.        |
| [`enable_hardware_metrics`](#aitune-utils-monitoring-setup_hardware_metrics-enable_hardware_metrics)   | Enable hardware metrics collection at runtime.                   |
| [`get_default_collector`](#aitune-utils-monitoring-setup_hardware_metrics-get_default_collector)       | Get the default hardware metrics collector.                      |
| [`get_hardware_metrics`](#aitune-utils-monitoring-setup_hardware_metrics-get_hardware_metrics)         | Get metrics from the receiver.                                   |
| [`snapshot`](#aitune-utils-monitoring-setup_hardware_metrics-snapshot)                                 | Dump currently collected hardware metrics to a CSV file.         |

### Data

[`_DEFAULT_SESSION`](#aitune-utils-monitoring-setup_hardware_metrics-_DEFAULT_SESSION)

### API

```python
class aitune.utils.monitoring.setup_hardware_metrics.HardwareMetricsSession()
```

Manages the lifecycle of hardware metrics collection.

Encapsulates the collector, receiver subprocess, runtime enable/disable state,
and atexit registration.

**`_collector`** `HardwareMetricsCollector | None = None`

---

**`_noop_collector`** `= NoOpHardwareMetricsCollector()`

---

**`_receiver`** `ParentReceiver | None = None`

---

**`_runtime_enabled`** `bool | None = None`

---

```python
aitune.utils.monitoring.setup_hardware_metrics.HardwareMetricsSession._ensure_initialized() -> None
```

```python
aitune.utils.monitoring.setup_hardware_metrics.HardwareMetricsSession._should_collect() -> bool
```

```python
aitune.utils.monitoring.setup_hardware_metrics.HardwareMetricsSession.disable() -> None
```

Disable collection at runtime, gracefully stopping any active session.

```python
aitune.utils.monitoring.setup_hardware_metrics.HardwareMetricsSession.enable() -> None
```

Enable collection at runtime, overriding the env var.

```python
aitune.utils.monitoring.setup_hardware_metrics.HardwareMetricsSession.get_collector() -> aitune.utils.monitoring.hardware_metrics.collector.NoOpHardwareMetricsCollector
```

Return the active collector, or a no-op when collection is disabled.

```python
aitune.utils.monitoring.setup_hardware_metrics.HardwareMetricsSession.get_metrics() -> pandas.DataFrame | None
```

Return accumulated metrics, or None if collection was never started.

```python
aitune.utils.monitoring.setup_hardware_metrics.HardwareMetricsSession.snapshot(
    path: pathlib.Path,
    reset_metrics: bool = True
) -> None
```

Dump currently collected metrics to a CSV file.

**Parameters:**

**`path`** `Path`

Path to write the CSV file.

---

**`reset_metrics`** `bool` — default: True

If True, clears the accumulated metrics after writing.

---

```python
aitune.utils.monitoring.setup_hardware_metrics._split_for_logging(
    flat: pandas.DataFrame,
    n_index_cols: int
) -> list[pandas.DataFrame]
```

Split a wide metrics table into narrower sub-tables for logging.

Each split contains the index columns (Module, Backend) plus up to 6
metric columns. Returns the original frame unchanged when there are at
most 6 metric columns.

```python
aitune.utils.monitoring.setup_hardware_metrics.disable_hardware_metrics() -> None
```

Disable hardware metrics collection at runtime.

Overrides the AITUNE\_HARDWARE\_METRICS environment variable.
If collection was active, gracefully stops the receiver (dumping any
accumulated metrics) and resets state so that a future enable\_hardware\_metrics()
call starts a fresh collection session.

```python
aitune.utils.monitoring.setup_hardware_metrics.dump_metrics(
    metrics: pandas.DataFrame
)
```

Logs metrics summary and dumps the metrics to a CSV file.

**Parameters:**

**`metrics`** `pd.DataFrame`

The metrics to dump.

---

```python
aitune.utils.monitoring.setup_hardware_metrics.enable_hardware_metrics() -> None
```

Enable hardware metrics collection at runtime.

Overrides the AITUNE\_HARDWARE\_METRICS environment variable.
The collector and receiver subprocess are started lazily on the first use.

```python
aitune.utils.monitoring.setup_hardware_metrics.get_default_collector() -> aitune.utils.monitoring.hardware_metrics.collector.NoOpHardwareMetricsCollector
```

Get the default hardware metrics collector.

```python
aitune.utils.monitoring.setup_hardware_metrics.get_hardware_metrics() -> pandas.DataFrame | None
```

Get metrics from the receiver.

```python
aitune.utils.monitoring.setup_hardware_metrics.snapshot(
    path: pathlib.Path,
    reset_metrics: bool = True
) -> None
```

Dump currently collected hardware metrics to a CSV file.

**Parameters:**

**`path`** `Path`

Path to write the CSV file.

---

**`reset_metrics`** `bool` — default: True

If True, clears the accumulated metrics after writing.

---

```python
aitune.utils.monitoring.setup_hardware_metrics._DEFAULT_SESSION: HardwareMetricsSession = HardwareMetricsSession()
```