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
availabilitymap asunsupported(not measurable on this hardware/OS),permission_denied(measurable, but not with the agent's privileges) orunavailable(the collector failed this round). Never an estimate, never a zero. counter_ratemetrics 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.