Resource Monitor

Background 10 Hz resource sampling for CPU, memory, and GPU utilization during benchmarks.

See Also

• Benchmarking Overview - All benchmarking tools
• Profiler - GPU memory profiling
• Monitor - Real-time monitoring
• Benchmarking Guide

---

calibrax.profiling.resources

Background resource monitoring with 10Hz sampling.

Provides ResourceMonitor context manager for tracking CPU, memory, and optional GPU utilization during benchmark execution.

GPUProfilerProtocol

Bases: Protocol

Protocol for GPU profilers providing utilization and memory data.

get_utilization

get_utilization() -> float

Get current GPU utilization percentage.

Returns:

Type	Description
float	GPU utilization as a percentage (0-100).

get_memory_usage

get_memory_usage() -> dict[str, float]

Get current GPU memory usage statistics.

Returns:

Type	Description
dict[str, float]	Dictionary with at least 'gpu_memory_used_mb' key.

get_clock_info

get_clock_info() -> dict[str, float]

Get current GPU clock frequencies.

Returns:

Type	Description
dict[str, float]	Dictionary with 'gpu_clock_mhz' and 'mem_clock_mhz' keys.

get_power_info

get_power_info() -> dict[str, float]

Get current GPU power draw and limits.

Returns:

Type	Description
dict[str, float]	Dictionary with 'power_draw_w' and 'power_limit_w' keys.

ResourceSample dataclass

ResourceSample(*, timestamp: float, cpu_percent: float, rss_mb: float, gpu_util: float | None, gpu_mem_mb: float | None, gpu_clock_mhz: float | None = None, gpu_power_w: float | None = None)

Single resource measurement at a point in time.

Attributes:

Name	Type	Description
timestamp	float	Time of measurement (perf_counter).
cpu_percent	float	CPU utilization percentage.
rss_mb	float	Resident set size in MB.
gpu_util	float | None	GPU utilization percentage (None if no GPU).
gpu_mem_mb	float | None	GPU memory used in MB (None if no GPU).

timestamp instance-attribute

timestamp: float

cpu_percent instance-attribute

cpu_percent: float

rss_mb instance-attribute

rss_mb: float

gpu_util instance-attribute

gpu_util: float | None

gpu_mem_mb instance-attribute

gpu_mem_mb: float | None

gpu_clock_mhz class-attribute instance-attribute

gpu_clock_mhz: float | None = None

gpu_power_w class-attribute instance-attribute

gpu_power_w: float | None = None

ResourceSummary dataclass

ResourceSummary(*, peak_rss_mb: float, mean_rss_mb: float, peak_gpu_mem_mb: float | None, mean_gpu_util: float | None, memory_growth_mb: float, num_samples: int, duration_sec: float, mean_gpu_clock_mhz: float | None = None, mean_gpu_power_w: float | None = None)

Aggregated resource usage over a monitoring period.

Attributes:

Name	Type	Description
peak_rss_mb	float	Maximum RSS observed.
mean_rss_mb	float	Average RSS across all samples.
peak_gpu_mem_mb	float | None	Maximum GPU memory (None if no GPU).
mean_gpu_util	float | None	Average GPU utilization (None if no GPU).
memory_growth_mb	float	Last RSS minus first RSS (positive = growth).
num_samples	int	Total samples collected.
duration_sec	float	Time span of monitoring.

peak_rss_mb instance-attribute

peak_rss_mb: float

mean_rss_mb instance-attribute

mean_rss_mb: float

peak_gpu_mem_mb instance-attribute

peak_gpu_mem_mb: float | None

mean_gpu_util instance-attribute

mean_gpu_util: float | None

memory_growth_mb instance-attribute

memory_growth_mb: float

num_samples instance-attribute

num_samples: int

duration_sec instance-attribute

duration_sec: float

mean_gpu_clock_mhz class-attribute instance-attribute

mean_gpu_clock_mhz: float | None = None

mean_gpu_power_w class-attribute instance-attribute

mean_gpu_power_w: float | None = None

to_dict

to_dict() -> dict[str, Any]

Serialize to a JSON-compatible dictionary.

Optional GPU fields are included only when not None. Numeric values are converted to Python primitives for JAX scalar safety.

Returns:

Type	Description
dict[str, Any]	Dictionary representation with all resource summary fields.

from_dict classmethod

from_dict(data: dict[str, Any]) -> ResourceSummary

Deserialize from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dictionary with resource summary fields.	required

Returns:

Type	Description
ResourceSummary	Reconstructed ResourceSummary instance.

ResourceMonitor

ResourceMonitor(sample_interval_sec: float = 0.1, gpu_profiler: GPUProfilerProtocol | None = None)

Background 10Hz resource sampling via context manager.

Usage:

with ResourceMonitor() as mon:
    # ... run benchmark ...
summary = mon.summary

Parameters:

Name	Type	Description	Default
sample_interval_sec	float	Seconds between samples (default 0.1 = 10Hz).	0.1
gpu_profiler	GPUProfilerProtocol | None	Optional profiler satisfying GPUProfilerProtocol.	None

Parameters:

Name	Type	Description	Default
sample_interval_sec	float	Seconds between resource samples.	0.1
gpu_profiler	GPUProfilerProtocol | None	Optional GPU profiler for GPU metrics.	None

samples property

samples: list[ResourceSample]

Return a copy of all collected samples.

summary property

summary: ResourceSummary

Compute aggregated summary from collected samples.

Returns:

Type	Description
ResourceSummary	ResourceSummary with aggregated metrics, or zeroed summary
ResourceSummary	if no samples were collected.