geopm_heatmap_agent(1) – render a component-saturation heatmap from GEOPM telemetry

Synopsis

python3 -m geopmdpy.heatmap_agent [-t TIME] [-p PERIOD] [-o TRACE_OUT]
                                  [-i CONFIG_PATH] [--heatmap-out PATH]
                                  [--fom FOM_CSV] [--no-plot]
                                  [--replot-csv TRACE_CSV]

Sample and render (default)

python3 -m geopmdpy.heatmap_agent -t 30 --heatmap-out heatmap.png

Correlate against a figure of merit

python3 -m geopmdpy.heatmap_agent -t 60 --heatmap-out hm.png --fom fom.csv

Re-render a saved trace without sampling

python3 -m geopmdpy.heatmap_agent -t 60 -o trace.csv --no-plot
python3 -m geopmdpy.heatmap_agent --replot-csv trace.csv --heatmap-out hm.png

Description

The heatmap_agent is a pure-Python implementation of the geopm::Agent(3) interface for the GEOPM Python session (see geopmsession(1)). It samples a set of per-component signals in-process through the geopmdpy.pio interface and, when the session ends, renders a normalized component-saturation heatmap with one row per component and time along the horizontal axis. Each row is scaled to its own dynamic range, so a component pinned near its own maximum while the others sit idle reads out as the bottleneck for that phase of the run.

The agent samples the following signals when they are granted on the platform; any that are unavailable are silently dropped:

CPU_POWER (CPU package power)
MSR::CPU_SCALABILITY_RATIO (stalled-vs-retiring proxy)
CPU_FREQUENCY_STATUS (core frequency)
CPU_UNCORE_FREQUENCY_STATUS (uncore frequency)
DRAM_POWER (memory power)
GPU_POWER, GPU_CORE_ACTIVITY, GPU_UNCORE_ACTIVITY, GPU_UTILIZATION (GPU power and activity, when a GPU IOGroup is present)

When both CPU_INSTRUCTIONS_RETIRED and CPU_CYCLES_THREAD are available, the agent derives a per-sample IPC row from the deltas of the two cumulative counters and also emits it as an IPC column in the trace. High IPC alongside modest DRAM and uncore activity indicates a compute-bound region; low IPC with saturated DRAM power or uncore frequency indicates a memory-bound region.

Because this agent extends the session interface, it accepts all of the standard geopmsession(1) options (for example -t/--time, -p/--period, -o/--trace-out, and -i/--signal-config) in addition to the options listed below. The agent supplies its own default signal request set, so no request list needs to be piped in; provide -i CONFIG_PATH to trace a custom set of requests instead. The default sampling period is lowered to 0.05 second; an explicit -p/--period still takes precedence. This is a read-only monitoring agent and writes no controls.

Options

--heatmap-out PATH: Output PNG path for the rendered heatmap. Default: component_heatmap.png.
--fom FOM_CSV: Overlay an external figure-of-merit time series beneath the heatmap. The CSV must have two columns, time_seconds and value. The FOM axis shares the heatmap’s time axis to aid correlation of the metric against the telemetry.
--no-plot: Collect the trace but skip rendering the heatmap. Useful for long or high-rate captures; render the resulting trace later with --replot-csv.
--replot-csv TRACE_CSV: Render a heatmap from an existing geopmsession trace CSV and exit without opening a session. No PlatformIO access is required. The PNG is written to --heatmap-out and --fom may be combined with it. When the trace contains the CPU_INSTRUCTIONS_RETIRED and CPU_CYCLES_THREAD counters the IPC row is derived from them; otherwise an existing IPC column is used if present. This option is distinct from -f/--report-format, which selects the report output format.

Requirements

Rendering requires matplotlib (and pandas for the --fom overlay and --replot-csv modes). These are optional dependencies of geopmdpy and can be installed with:

pip install geopmdpy[heatmap]

Importing the module and running a --no-plot capture do not require these packages.

Limitations

GEOPM exposes no NIC telemetry and has no notion of data flowing between components, so this tool visualizes per-component saturation over time rather than a data-flow diagram between the CPU, GPU, and other devices. When rendering at the end of a run (the default), samples are accumulated in memory for the duration of the session; for very long or high-rate captures prefer --no-plot and re-render the saved trace with --replot-csv.