SPB Git

Repository Public

METRICS-CATALOG.md 7.7 KB 103 lines markdown

1# Metrics catalog23<!-- GENERATED by `go run ./cmd/mcc-agent catalog --markdown --observed ../docs/metrics-observed.json`. Do not edit by hand. -->45Source of truth: `services/internal/protocol/metrics.go` (`protocol.Catalog`). The same table seeds6`metric_catalog` at ingest start-up and drives the agent collectors.78Rules:910- A metric that cannot be measured produces **no sample**. It is declared in the report's `availability` map as11  `unsupported` (not measurable on this hardware/OS), `permission_denied` (measurable, but not with the agent's12  privileges) or `unavailable` (the collector failed this round). Never an estimate, never a zero.13- `counter_rate` metrics are computed by the agent from a monotonic counter: the first round after start, and any14  round where the counter went backwards, produce no sample.15- IDs are stable forever and never reused.16- Cardinality per report: ≤ 8 interfaces, ≤ 12 volumes, ≤ 15 processes, ≤ 200 services, ≤ 400 samples, labels ≤ 64 bytes.1718## Catalog1920| ID | Name | Unit | Kind | Interval | Label | Description | Source | Limitations |21|---:|---|---|---|---:|---|---|---|---|22| 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 | — |23| 2 | `cpu.user` | percent | gauge | 10 s | — | User-mode share. | same as cpu.usage | — |24| 3 | `cpu.system` | percent | gauge | 10 s | — | Kernel-mode share. | same as cpu.usage | — |25| 4 | `load.1` | count | gauge | 10 s | — | 1-minute load average. | getloadavg | — |26| 5 | `load.5` | count | gauge | 10 s | — | 5-minute load average. | getloadavg | — |27| 6 | `load.15` | count | gauge | 10 s | — | 15-minute load average. | getloadavg | — |28| 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. |29| 11 | `mem.total` | bytes | gauge | 60 s | — | Installed memory (unified memory on Apple Silicon). | hw.memsize / MemTotal | — |30| 12 | `mem.wired` | bytes | gauge | 10 s | — | Wired memory. | macOS: host_statistics64 | macOS only. |31| 13 | `mem.compressed` | bytes | gauge | 10 s | — | Memory held by the compressor. | macOS: host_statistics64 | macOS only. |32| 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. |33| 15 | `mem.available.percent` | percent | gauge | 10 s | — | Share of memory the kernel considers available. | macOS: sysctl kern.memorystatus_level; Linux: MemAvailable/MemTotal | — |34| 16 | `swap.used` | bytes | gauge | 10 s | — | Swap in use. | macOS: sysctl vm.swapusage; Linux: /proc/meminfo | — |35| 17 | `swap.total` | bytes | gauge | 60 s | — | Swap currently allocated. | same as swap.used | macOS grows swap dynamically; total is the current allocation. |36| 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. |37| 21 | `disk.total` | bytes | gauge | 60 s | yes | Volume size (label = mount point). | statfs | — |38| 22 | `disk.read` | bytes_per_s | counter_rate | 10 s | — | Read throughput, all physical disks. | macOS: IOKit IOBlockStorageDriver statistics; Linux: /proc/diskstats | — |39| 23 | `disk.write` | bytes_per_s | counter_rate | 10 s | — | Write throughput, all physical disks. | same as disk.read | — |40| 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. |41| 31 | `net.tx` | bytes_per_s | counter_rate | 10 s | yes | Transmit throughput (label = interface). | same as net.rx | — |42| 32 | `net.errors` | count | counter_rate | 10 s | yes | Interface errors per second, in+out (label = interface). | same as net.rx | — |43| 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. |44| 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%. |45| 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. |46| 41 | `gpu.mem.used` | bytes | gauge | 10 s | — | Unified memory in use by the GPU. | macOS: IOAccelerator 'In use system memory' | macOS only. |47| 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. |48| 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. |49| 52 | `power.draw` | watts | gauge | 30 s | — | Power draw. | none without root | Requires powermetrics (root): unsupported in the unprivileged agent. |50| 53 | `battery.charge` | percent | gauge | 60 s | — | Battery charge. | macOS: IOPowerSources | Laptops only; desktops report unsupported. |51| 60 | `uptime` | seconds | gauge | 60 s | — | Time since boot. | kern.boottime / /proc/uptime | — |52| 61 | `procs.count` | count | gauge | 30 s | — | Number of processes. | process table size | — |53| 70 | `agent.cpu` | percent | gauge | 30 s | — | CPU used by the agent itself (percent of one core). | getrusage delta of the agent process | — |54| 71 | `agent.rss` | bytes | gauge | 30 s | — | Memory used by the agent itself. | agent process resident size | — |5556## Observed availability5758Status of every metric as observed on real machines (queried from the database after the run, not assumed).59`measured (n)` = n raw samples stored during the run.6061| Metric | Mac17,6 (M5 Max), macOS 27.0 |62|---|---|63| `cpu.usage` | measured (38) |64| `cpu.user` | measured (38) |65| `cpu.system` | measured (38) |66| `load.1` | measured (40) |67| `load.5` | measured (40) |68| `load.15` | measured (40) |69| `mem.used` | measured (40) |70| `mem.total` | measured (8) |71| `mem.wired` | measured (40) |72| `mem.compressed` | measured (40) |73| `mem.pressure.level` | measured (40) |74| `mem.available.percent` | measured (40) |75| `swap.used` | measured (40) |76| `swap.total` | measured (8) |77| `disk.used` | measured (24) |78| `disk.total` | measured (24) |79| `disk.read` | measured (38) |80| `disk.write` | measured (38) |81| `net.rx` | measured (76) |82| `net.tx` | measured (76) |83| `net.errors` | measured (76) |84| `net.latency` | measured (28) |85| `net.loss` | measured (28) |86| `gpu.usage` | measured (40) |87| `gpu.mem.used` | measured (40) |88| `thermal.pressure` | measured (14) |89| `thermal.temp` | unsupported |90| `power.draw` | unsupported |91| `battery.charge` | measured (8) |92| `uptime` | measured (8) |93| `procs.count` | measured (14) |94| `agent.cpu` | measured (12) |95| `agent.rss` | measured (14) |9697Runs:9899- **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)100101Linux has not been run yet: its column will appear after the first Linux pilot. Expected from the code:102`mem.wired`, `mem.compressed`, `mem.pressure.level`, `gpu.*`, `thermal.pressure` → `unsupported`.103
Files main
Menu

Theme