# Native Metric Migration for 2026.3.0 The unreleased 2026.3.0 native collectors use bytes, bytes/second, Hz, W, and degrees Celsius with explicit unit-bearing field names. This is a **breaking, one-time contract migration** for the native Docker image and Debian package. Old names are not emitted as aliases. Upgrade collectors and dashboards together. Standard Telegraf inputs (including powerstat, Turbostat, CPU, memory, network, and disk) are unchanged. So are the qmassa JSON input schema, engine/CPU utilization percentages, counts, state/throttle flags, process resident set size (RSS) bytes, and `rapl_power_power_w`. Percentages remain 0–100 (or the existing multi-core/ multi-engine semantics), not newly introduced 0–1 ratios. ## Prometheus Names and Conversions Multiply the previous value by the factor below to obtain the new value. For GPU memory, `{...}` denotes the existing memory field names; all fields from qmassa's device/client memory maps receive the `_bytes` suffix. Tags, device/tile identities, and collector selection behavior are preserved. | Previous name | New name | Factor | | -------------------------------------------------------- | ------------------------------------------------------ | --------- | | `cpu_frequency_avg_frequency` | `cpu_frequency_avg_frequency_hz` | 1,000 | | `cpu_core_class_frequency_avg` | `cpu_core_class_frequency_avg_hz` | 1,000 | | `gpu_frequency` (legacy `value` alias) | `gpu_frequency_cur_freq_hz` | 1,000,000 | | `gpu_frequency_{act,cur,min,max}_freq` | `gpu_frequency_{act,cur,min,max}_freq_hz` | 1,000,000 | | `gpu_power` | `gpu_power_power_w` | 1 | | `gpu_temperature` | `gpu_temperature_temperature_c` | 1 | | `gpu_fan` (RPM) | `gpu_fan_speed_hz` (rotations/second) | 1/60 | | `gpu_memory_{smem_total,smem_used,vram_total,vram_used}` | Same names with `_bytes` appended | 1 | | `gpu_client_{smem_used,smem_rss,vram_used,vram_rss}` | Same names with `_bytes` appended | 1 | | `npu_power` | `npu_power_w` | 1 | | `npu_frequency` (already corrected Hz) | `npu_frequency_hz` | 1 | | `npu_temperature` | `npu_temperature_c` | 1 | | `npu_bandwidth` (decimal MB/s) | `npu_bandwidth_bytes_per_second` | 1,000,000 | | `npu_memory_mb` (actually MiB) | `npu_memory_bytes` | 1,048,576 | | `npu_frequency_max_mhz` | `npu_frequency_max_hz` | 1,000,000 | | `memory_bandwidth_{read,write,total}_mibps` | `memory_bandwidth_{read,write,total}_bytes_per_second` | 1,048,576 | Line-protocol measurement names stay unchanged; their fields are renamed accordingly. For example, `npu` now has `frequency_hz` and `memory_bytes`; `gpu_power` has `power_w` instead of `value`. There is no second GPU `value` field repeating requested frequency. The NPU frequency factor assumes the already-corrected native Hz calculation. Earlier uncorrected builds reported values 1e6 too small and also used the wrong Intel® Core™ Ultra Series 2 phase-locked loop (PLL) formula; their historical data needs separate correction, not just a rename. The current formulas remain MTL/ARL `ratio * 50e6 * 2/3` and LNL/PTL `ratio * 50e6 / 2`. ## Display and Query Units Convert raw metrics at the display or query boundary: - Clocks: divide Hz by `1e6` for MHz or `1e9` for GHz. - Memory sizes: divide bytes by `1048576` for MiB or `1073741824` for GiB. - Whole-system DRAM throughput: divide bytes/s by `1e9` for decimal GB/s. - NPU throughput: divide bytes/s by `1e6` for decimal MB/s. Examples for external dashboards: ```promql gpu_frequency_act_freq_hz / 1e6 npu_memory_bytes / 1048576 memory_bandwidth_total_bytes_per_second / 1e9 gpu_fan_speed_hz * 60 ``` Do **not** apply `rate()` again to bandwidth metrics: they are already rates. The memory-controller collector converts the sysfs MiB-per-event scale to bytes before dividing by elapsed time. NPU bandwidth preserves actual sampling interval and single 32-bit counter-wrap handling. Missing optional NPU data stays absent; measured zeros stay zero. Memory is no longer rounded to two decimal places of MiB before export. ## Upgrade Checklist 1. Upgrade the native plugins for every producer read by your dashboards. Restart/recreate the selected services so old collector processes stop. 2. Replace old names in PromQL, recording/alert rules, and custom ingestion clients. Rescale numeric thresholds using the table; do not splice old and new raw values into one history without conversion. 3. Merge new examples into locally retained configuration files. Mounted configurations are not automatically overwritten. 4. Verify the new metric families at `/metrics`, check device/tile labels and missing-data behavior, and compare dashboard values after display conversion. ## TUI Configuration Migration Upgrade `mm-tui` with the native collectors. The [terminal dashboard](./terminal-dashboard.md) performs display conversions; do not pre-convert the Prometheus endpoint or it will scale the values twice. For retained custom chart configuration, replace the old DRAM chart IDs `memory.bandwidthMiBps`, `memory.readMiBps`, and `memory.writeMiBps` with `memory.bandwidthGBps`, `memory.readGBps`, and `memory.writeGBps`. Use `GB/s` as the display unit and convert any fixed MiB/s bounds by multiplying by `1048576 / 1e9`. Merge the current examples rather than discarding local settings. ## Debian Package Upgrades Install the new package with `apt` so plugins and the dashboard are upgraded together. Locally modified configuration is preserved: compare any `.dpkg-dist` files with the active configuration, merge the needed changes, and restart `mm-tui`. In particular, retained chart files may still use the old DRAM IDs. Do not replace local settings wholesale or run old and new metric contracts through the same unconverted history.