Feature Request: Extend pmUnits to support electrical and thermal dimensions

[tallpsmith]

Feature Request: Extend pmUnits to support electrical and thermal dimensions

Background

PCP's pmUnits structure currently supports three dimensions: Space (bytes), Time (seconds), and Count (dimensionless). While this covers many use cases, it forces PMDAs that collect electrical and thermal metrics to define them as dimensionless, losing semantic meaning and preventing proper unit conversion.

Current workaround: All PMDAs with power/thermal metrics use PMDA_PMUNITS(0,0,0,0,0,0) (dimensionless) and rely on metric names or pmrep labels to convey units to users.

Problem

Multiple PMDAs collect metrics that would benefit from proper unit definitions:

PMDA	Current Dimensionless Metrics	Example
nvidia	temperature, fanspeed, power, energy	nvidia.temperature (°C), nvidia.power (mW)
darwin	thermal.cpu.die, power.battery.voltage, power.battery.amperage, power.battery.capacity, thermal.fan.speed	All defined as dimensionless
amdgpu	GPU temperature, power consumption	Hardware monitoring
smart	disk temperature sensors	smart.temperature_celsius
lmsensors	Linux hwmon sensors (temp, voltage, current, fans)	System health monitoring
roomtemp	Environmental temperature monitoring	Datacenter monitoring

Impact:

• pmrep/pmchart cannot perform unit conversions (e.g., °C ↔ °F, mW → W)
• Unit metadata lost at the PMDA level
• Tools display raw numbers without semantic context
• Inconsistent user experience compared to well-defined metrics (bytes, seconds)

Proposed Solution

Extend pmUnits to support additional physical dimensions commonly encountered in system monitoring:

Proposed New Dimensions

Dimension	Base Unit	Scale Examples	Use Cases
Temperature	Celsius (°C)	Celsius, Fahrenheit, Kelvin	CPU/GPU/disk temps, thermal sensors
Voltage	Volt (V)	V, mV, μV	Power supply, battery voltage, sensor rails
Current	Ampere (A)	A, mA, μA	Power draw, battery current
Power	Watt (W)	W, mW, μW, kW	Power consumption, TDP monitoring
Energy	Joule (J)	J, Wh, kWh	Energy counters, battery capacity
Frequency	Hertz (Hz)	Hz, kHz, MHz, GHz	CPU/GPU clocks, timers
Angular Velocity	RPM	RPM	Fan speeds

Implementation Sketch

Extend the pmUnits bitfield structure (in pmapi.h) to add new dimension fields, similar to how dimSpace, dimTime, and dimCount work today:

// New dimension constants (example)
#define PM_TEMP_CELSIUS   0  /* degrees Celsius */
#define PM_TEMP_FAHRENHEIT 1 /* degrees Fahrenheit */
#define PM_TEMP_KELVIN     2 /* Kelvin */

#define PM_VOLTAGE_VOLT    0  /* volts */
#define PM_VOLTAGE_MVOLT   1  /* millivolts */
// ... etc

PMDAs could then define metrics properly:

// Before (dimensionless)
PMDA_PMUNITS(0, 0, 0, 0, 0, 0)

// After (semantic temperature)
PMDA_PMUNITS(0, 0, 0, 0, 0, 0, 1, PM_TEMP_CELSIUS)

Discussion Points

1. Scope: Which dimensions are most valuable? Should we start with a subset (e.g., temperature + power) or implement comprehensively?

2. Backward compatibility: How to handle existing dimensionless metrics? Deprecation path? Automatic migration?

3. Conversion logic: Should libpcp gain conversion functions (e.g., pmConvertTemp(), pmConvertPower())? Or leave to client tools?

4. Standard adoption: Should PCP align with SI units, IEC standards, or support multiple unit systems?

5. Effort vs. benefit: Is the improved semantic correctness and UX worth the engineering effort to extend the core unit system?

Benefits

• Semantic correctness: Metrics carry proper unit metadata
• Better UX: Tools can display appropriate units and perform conversions
• Developer experience: PMDA authors can define metrics naturally
• Future-proofing: New hardware monitoring PMDAs get proper unit support from day one

Questions for Maintainers

• Does this align with PCP's design philosophy?
• Are there architectural concerns with extending pmUnits?
• Would this be accepted if implemented with tests and documentation?
• Any alternative approaches we should consider instead?

---

Context: This came up while developing pmrep views for the darwin PMDA's thermal/power metrics, where specifying units like dC or mAh caused PM_ERR_CONV errors. Investigation revealed this is a systemic limitation affecting multiple PMDAs.

[kmcdonell]

OK, @tallpsmith let me start with an initial reaction you'll recall I've used in other contexts, "Which part of the concept ``no'' are you having difficulty understanding?"

But let me assume a more reasonable posture. It is thoughts like this that have driven PCP evolution over 30+ years, so let me ponder this a bit ...

The immediate hurdles I see are:

1. pmUnits is embedded in the archives, the PMAPI and the over the wire PDUs ... changing this involves revving libpcp, the distributed protocols and archive formats and building all of the cross-rev compatibility support ... this is a lot of work
2. units conversion is an O(N*N) chunk of code, but it happens in lots of places (libpcp, pmie, derived metrics, pmrep); I'd like to keep N as small as possible, and this proposal seems to have the potential to increase N substantially
3. everytime a new dimension is proposed we have to do 1. and 2. all over again, so this basic infrastructure is not easily extensible (more on that below)
4. units are implicated in every PMAPI client that does rate conversion of counters

Now, without any real thought as to implementation, I could imagine a new feature that allowed additional attribute metadata (think non-data fork in a filesystem, or key=value style) to be supported for a given PMID. If this was JSON or some similar generic format, then this would be extensible. And indeed would have been a better basis for other quasi-metadata, like, er, help text!

This would be adding to the PMAPI, the pmcd-pmda interface (libpcp_pmda), the over-the wire protocols (all involve revving the version, but adding is much simpler than changing). But even this raises questions about archive format ... we'd need a metadata record for attributes (which means a new archive version so down-rev libpcp's would not choke on new archives), a tool to "down-rev" a new archive (so down-rev libpcp's could read all of the non-attribute information) and are the attributes time-invariant (I'd expect "yes" is the only sane answer here).

[natoscott]

| [...] imagine a new feature that allowed additional attribute metadata (think non-data fork in a filesystem, or key=value style) to be supported for a given PMID.

We already have this feature - see pmLookupLabels(1). Some agents are even using it for a similar purpose to that sought here...

src/pmdas$ grep -r watt *
denki/denki.c:					pmdaAddLabels(lpp, "{\"units\":\"watt hours\"}");
denki/denki.c:					pmdaAddLabels(lpp, "{\"units\":\"watt\"}");
nvidia/nvidia.c:	pmdaAddLabels(lp, "{\"units\":\"milliwatts\"}");

[kmcdonell]

@natoscott Fortunately I'll be dead soon, so no more embarrassing public disclosures of my neanderthal ignorance.

[christianhorn]

I have been wrapping my head around the request as well, trying to understand the request.

I think this would place energy rather as additional dimension to everything, instead of how I was so far looking at it: as just a further metric which one would be interested in (so register/record it), or rather not.

Maybe coming from the other side, on illustrating how this approach here could be better, could have helped.

[tallpsmith]

This all stemmed from me, adding some GPU power and fan speed metrics for macOS. When I attempted to add some pmrep views I initially placed some unit information in the configs and it didn't like it because RPM and Watts were not recognized as units it could do conversions on.

[tallpsmith]

Here's exhibit A: 4049861

[tallpsmith]

Exhibit B: 266fec3

[natoscott]

Setting aside the labels approach for now (which is not a panacea because it isn't really "standardised" and always available like the other units), one thing I do want to mention is that there is a little wriggle room here and that a middle ground may be possible.

pmUnits is embedded in the archives, the PMAPI and the over the wire PDUs ... changing this involves revving libpcp, the distributed protocols and archive formats and building all of the cross-rev compatibility support ... this is a lot of work

The proposed table of additions is large - too large IMO (very much agreeing with @kmcdonell on that) - but based on the areas we've typically been asked for improved units support over the years, it could be whittled down. If it can be reduced (I suggest power and temperature as the most common requests we've seen), there are 8 bits of padding in the pmUnits field of pmDesc where we could add some support allowing these to become first-class citizens and with no change to on-disk or over-the-wire formats (all existing tools just ignore these, and they are currently zero on-disk).

@tallpsmith btw, hertz is mentioned as a category in the table - this can be represented, check kernel.all.hz in the Linux kernel PMDA - so IMO that row in the table can be discarded already.

[natoscott]

BTW, this ...

// Before (dimensionless)
PMDA_PMUNITS(0, 0, 0, 0, 0, 0)

// After (semantic temperature)
PMDA_PMUNITS(0, 0, 0, 0, 0, 0, 1, PM_TEMP_CELSIUS)

Is not a viable approach due to backward-compatibility requirements, however a new macro (with a different name) can be added to allow any new fields to be initialized.