Skip to content

cpu: Add NUMA node mapping metric - #3785

Open
baozhuoran wants to merge 2 commits into
prometheus:masterfrom
baozhuoran:numatopology-collector
Open

baozhuoran wants to merge 2 commits into
prometheus:masterfrom
baozhuoran:numatopology-collector

Conversation

@baozhuoran

@baozhuoran baozhuoran commented Aug 7, 2026 •

Copy link
Copy Markdown

Summary

Add node_cpu_numa_info{cpu,node} to the cpu collector. It exposes the NUMA node of each online CPU, read from /sys/devices/system/node/node*/cpulist through procfs. It depends on prometheus/procfs#892; see Dependency below.

# HELP node_cpu_numa_info NUMA node of each online CPU, information from /sys/devices/system/node/node*/cpulist.
# TYPE node_cpu_numa_info gauge
node_cpu_numa_info{cpu="0",node="0"} 1
node_cpu_numa_info{cpu="1",node="0"} 1
node_cpu_numa_info{cpu="2",node="1"} 1
node_cpu_numa_info{cpu="3",node="1"} 1

This PR was reworked. The first version added a standalone numatopology collector that also parsed libvirt domain XML. That part is dropped: it was service data read from outside /proc and /sys, and its per-node memory metric duplicated node_memory_numa_MemTotal.

Motivation

node_exporter exposes per-NUMA-node memory (meminfo_numa), but nothing says which CPUs belong to which NUMA node. With this mapping:

  • CPUs per NUMA node: count by (instance, node) (node_cpu_numa_info)
  • CPU time by NUMA node: sum by (instance, node, mode) (rate(node_cpu_seconds_total[5m]) * on (instance, cpu) group_left(node) node_cpu_numa_info)

Notes

  • The NUMA node is a label, as in node_memory_numa_*, rather than the sample value, as in node_pcidevice_numa_node. A label can be joined onto per-CPU series.
  • One series per online CPU, the same cardinality as node_cpu_online, so there is no new flag.
  • Offline CPUs are not listed by the kernel in cpulist, and memory-only nodes have no CPUs, so neither produces a series.
  • Systems without NUMA nodes expose no series and the collector does not fail.

Dependency

This needs sysfs.FS.NUMANodeCPUList from prometheus/procfs#892, which is not merged yet, so this PR can't be merged as it is. The first commit is a temporary replace directive pointing at that branch so that CI can run. Once a procfs release contains the helper, I'll drop that commit and bump procfs instead. The collector change itself is ready for review.

Testing

  • Added TestCPUNUMAInfo, which uses the existing fixtures/sys NUMA nodes (node0 0-1, node1 2-3, node2 memory-only).
  • Regenerated e2e-output.txt and e2e-64k-page-output.txt with ./end-to-end-test.sh -u.
  • The unit tests (with -race), golangci-lint and make checkmetrics pass locally on Linux. ./end-to-end-test.sh passes on x86_64 and arm64.
  • Checked against a live kernel: the series match nodeN/cpulist and cover the same CPUs as node_cpu_seconds_total. A sysfs tree without devices/system/node gives no series and no collector error.

Zhuoran-Bao added 2 commits November 10, 2026 15:03
Temporary replace directive pointing at prometheus/procfs#892. Drop this
commit and bump github.com/prometheus/procfs once a release contains
sysfs.FS.NUMANodeCPUList.

Signed-off-by: Zhuoran-Bao <zhuoran.bao@ibm.com>
Add node_cpu_numa_info{cpu,node}, which exposes the NUMA node of each
online CPU as read from /sys/devices/system/node/node*/cpulist via
procfs. It allows counting CPUs per NUMA node and aggregating per-CPU
metrics such as node_cpu_seconds_total by NUMA node. Systems without
NUMA nodes and memory-only nodes expose no series.

Signed-off-by: Zhuoran-Bao <zhuoran.bao@ibm.com>
@baozhuoran
baozhuoran force-pushed the numatopology-collector branch from 906c8a7 to 2081194 Compare November 10, 2026 20:05
@baozhuoran baozhuoran changed the title feat(collector): add NUMA topology collector cpu: Add NUMA node mapping metric Nov 10, 2026
@baozhuoran
baozhuoran marked this pull request as ready for review November 10, 2026 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant