SPB Git

Repository Public

METRICS-CATALOG.md 7.7 KB

# Metrics catalog

Source of truth: services/internal/protocol/metrics.go (protocol.Catalog). The same table seeds metric_catalog at ingest start-up and drives the agent collectors.

Rules:

  • A metric that cannot be measured produces no sample. It is declared in the report's availability map as unsupported (not measurable on this hardware/OS), permission_denied (measurable, but not with the agent's privileges) or unavailable (the collector failed this round). Never an estimate, never a zero.
  • counter_rate metrics are computed by the agent from a monotonic counter: the first round after start, and any round where the counter went backwards, produce no sample.
  • IDs are stable forever and never reused.
  • Cardinality per report: ≤ 8 interfaces, ≤ 12 volumes, ≤ 15 processes, ≤ 200 services, ≤ 400 samples, labels ≤ 64 bytes.

# Catalog

ID Name Unit Kind Interval Label Description Source Limitations
1 cpu.usage percent gauge 10 s — CPU busy share across all cores (0–100). macOS: host_processor_info ticks delta; Linux: /proc/stat delta —
2 cpu.user percent gauge 10 s — User-mode share. same as cpu.usage —
3 cpu.system percent gauge 10 s — Kernel-mode share. same as cpu.usage —
4 load.1 count gauge 10 s — 1-minute load average. getloadavg —
5 load.5 count gauge 10 s — 5-minute load average. getloadavg —
6 load.15 count gauge 10 s — 15-minute load average. getloadavg —
10 mem.used bytes gauge 10 s — Memory in use. macOS: host_statistics64 (active+wired+compressed pages); Linux: MemTotal-MemAvailable macOS has no single 'used' figure; this matches Activity Monitor's Memory Used closely, not exactly.
11 mem.total bytes gauge 60 s — Installed memory (unified memory on Apple Silicon). hw.memsize / MemTotal —
12 mem.wired bytes gauge 10 s — Wired memory. macOS: host_statistics64 macOS only.
13 mem.compressed bytes gauge 10 s — Memory held by the compressor. macOS: host_statistics64 macOS only.
14 mem.pressure.level level gauge 10 s — Kernel memory pressure: 1 normal, 2 warning, 4 critical. macOS: sysctl kern.memorystatus_vm_pressure_level macOS only; Linux reports unsupported.
15 mem.available.percent percent gauge 10 s — Share of memory the kernel considers available. macOS: sysctl kern.memorystatus_level; Linux: MemAvailable/MemTotal —
16 swap.used bytes gauge 10 s — Swap in use. macOS: sysctl vm.swapusage; Linux: /proc/meminfo —
17 swap.total bytes gauge 60 s — Swap currently allocated. same as swap.used macOS grows swap dynamically; total is the current allocation.
20 disk.used bytes gauge 60 s yes Used bytes per volume (label = mount point). statfs per mounted volume APFS volumes share a container: free space is shared between volumes.
21 disk.total bytes gauge 60 s yes Volume size (label = mount point). statfs —
22 disk.read bytes_per_s counter_rate 10 s — Read throughput, all physical disks. macOS: IOKit IOBlockStorageDriver statistics; Linux: /proc/diskstats —
23 disk.write bytes_per_s counter_rate 10 s — Write throughput, all physical disks. same as disk.read —
30 net.rx bytes_per_s counter_rate 10 s yes Receive throughput (label = interface). getifaddrs/if_data; Linux: /proc/net/dev Only physical and tunnel interfaces carrying an address; at most 8 per node.
31 net.tx bytes_per_s counter_rate 10 s yes Transmit throughput (label = interface). same as net.rx —
32 net.errors count counter_rate 10 s yes Interface errors per second, in+out (label = interface). same as net.rx —
33 net.latency ms gauge 30 s yes Round-trip time (label = gateway | ingest | hub). ICMP echo via /sbin/ping (3 packets) to the label target Unprivileged ping; a target that drops ICMP reports unavailable, not 0.
34 net.loss percent gauge 30 s yes Packet loss over the last probe (label = target). same as net.latency 3-packet probes: resolution is 33%.
40 gpu.usage percent gauge 10 s — GPU utilization. macOS: IORegistry IOAccelerator PerformanceStatistics 'Device Utilization %' Instantaneous driver figure, not an average over the interval. Linux: unsupported.
41 gpu.mem.used bytes gauge 10 s — Unified memory in use by the GPU. macOS: IOAccelerator 'In use system memory' macOS only.
50 thermal.pressure level gauge 30 s — Thermal pressure: 0 nominal, 1 moderate, 2 heavy, 3 trapping, 4 sleeping. macOS: notify state com.apple.system.thermalpressurelevel A coarse state, not a temperature.
51 thermal.temp celsius gauge 30 s — Temperature. none without root Not readable without root on Apple Silicon (powermetrics/SMC): reported as unsupported or permission_denied, never estimated.
52 power.draw watts gauge 30 s — Power draw. none without root Requires powermetrics (root): unsupported in the unprivileged agent.
53 battery.charge percent gauge 60 s — Battery charge. macOS: IOPowerSources Laptops only; desktops report unsupported.
60 uptime seconds gauge 60 s — Time since boot. kern.boottime / /proc/uptime —
61 procs.count count gauge 30 s — Number of processes. process table size —
70 agent.cpu percent gauge 30 s — CPU used by the agent itself (percent of one core). getrusage delta of the agent process —
71 agent.rss bytes gauge 30 s — Memory used by the agent itself. agent process resident size —

# Observed availability

Status of every metric as observed on real machines (queried from the database after the run, not assumed). measured (n) = n raw samples stored during the run.

Metric Mac17,6 (M5 Max), macOS 27.0
cpu.usage measured (38)
cpu.user measured (38)
cpu.system measured (38)
load.1 measured (40)
load.5 measured (40)
load.15 measured (40)
mem.used measured (40)
mem.total measured (8)
mem.wired measured (40)
mem.compressed measured (40)
mem.pressure.level measured (40)
mem.available.percent measured (40)
swap.used measured (40)
swap.total measured (8)
disk.used measured (24)
disk.total measured (24)
disk.read measured (38)
disk.write measured (38)
net.rx measured (76)
net.tx measured (76)
net.errors measured (76)
net.latency measured (28)
net.loss measured (28)
gpu.usage measured (40)
gpu.mem.used measured (40)
thermal.pressure measured (14)
thermal.temp unsupported
power.draw unsupported
battery.charge measured (8)
uptime measured (8)
procs.count measured (14)
agent.cpu measured (12)
agent.rss measured (14)

Runs:

  • Mac17,6 (M5 Max), macOS 27.0 — Mac17,6 Apple M5 Max, macOS 27.0 (26A5425a), agent 0.1.0-dev, 2026-11-18 (local pilot, 3 min mTLS + 3 min signed transport, database mcc_dev)

Linux has not been run yet: its column will appear after the first Linux pilot. Expected from the code: mem.wired, mem.compressed, mem.pressure.level, gpu.*, thermal.pressure → unsupported.

Files main
Menu

Theme