Temperature context

What it is

Temperature context adds a view of the machine's thermal state alongside energy and runtime. Linux commonly exposes thermal zones at /sys/class/thermal/thermal_zone*/; each zone has a type and a temperature in millidegrees Celsius.

DoL8 currently reads sensor data through psutil, prefers known CPU sensor families such as coretemp and k10temp, and stores valid samples during a run. It reports baseline, peak, average, ending temperature, and rise when readings are available.

Why it matters

Two runs at different temperatures may not be comparable. A hot processor can lower its frequency to manage heat; that changes how long instructions take and how much energy a workload uses. Thermal readings help explain an outlier rather than letting it look like a code change.

Temperature by itself does not prove throttling. Frequency information may be absent or inaccessible, so a reliable measurement tool must say unknown instead of guessing.

How it works

The kernel thermal interface stores millidegrees Celsius, so a direct sysfs reader converts temp / 1000 to Celsius and uses the zone's type to identify CPU sensors. The current DoL8 path queries psutil.sensors_temperatures() and picks a preferred CPU-like sensor when one exists.

The poller samples about every 100 ms. DoL8 also asks psutil.cpu_freq() for current frequency in MHz. It records a throttle event when a sample drops below 80% of the previous frequency while temperature is at least 85 C. If frequency data is not available at the start, the final throttling field is unknown (no frequency sensor).

temperature_c = zone_temp_millidegrees / 1000
frequency_mhz = psutil.cpu_freq().current

if frequency_mhz < previous_frequency_mhz * 0.8 and temperature_c >= 85:
    record_throttle_event()

This is a heuristic using sampled values, not a hardware throttle counter. It can miss short events between samples, and frequency changes can have causes other than heat.

What to build

1. Read optional sensors. In dol8/thermal.py, preserve unavailable sensors as None; do not turn a missing or invalid reading into zero degrees.
2. Identify the CPU zone. Prefer known CPU sensor types. If reading sysfs directly, inspect each thermal zone's type before using its temp.
3. Normalize units. Convert kernel millidegrees to Celsius once and keep report field names and units explicit.
4. Correlate cautiously. In dol8/poller.py, record temperature and frequency at the same sample time. Keep the threshold and sampling cadence documented.
5. Test absence and variation. Fake psutil in tests/test_thermal.py for empty sensors, invalid values, missing frequency, warm-up, and a hot frequency drop.

How to use it

Run the normal profiling command. Thermal fields are optional and depend on the sensors exposed by this Linux machine. Output values below are illustrative.

python -m dol8.cli run workload.py --runs 5

THERMAL: baseline 62.0 C, peak 78.5 C, avg 73.1 C, end 76.0 C, rise 16.5 C
THROTTLING: unknown (no frequency sensor)

Edge cases & gotchas

• Thermal zones may describe the chassis, ACPI, or another device rather than the CPU. Filter by zone type or known sensor family.
• Temperature APIs can be missing, permission-restricted, or return empty lists. Report unavailable values without failing an otherwise valid RAPL run.
• A sensor reading of zero or a non-numeric value is not a useful temperature sample; do not include it in peak or average statistics.
• CPU frequency may vary because of power policy, idle states, or workload phase. A sampled frequency drop plus high temperature is evidence for a warning, not proof of thermal throttling.
• The current 100 ms polling cadence can miss very brief thermal or frequency events.

Related