Repository Public
1package protocol23// Metric describes one catalogued time series. The catalog is the single4// source for the metric_catalog table, the agent collectors and5// docs/METRICS-CATALOG.md. IDs are stable forever; never reuse one.6type Metric struct {7 ID int168 Name string9 Unit string // percent | bytes | bytes_per_s | count | ms | ratio | seconds | level | celsius | watts10 Kind string // gauge | counter_rate (rate computed by the agent from a monotonic counter)11 IntervalS int12 Labeled bool // label = interface name, mount point or probe target13 Source string // how it is measured (per OS)14 Description string15 Limits string // known limitations, stated to the user16}1718var Catalog = []Metric{19 {1, "cpu.usage", "percent", "gauge", 10, false, "macOS: host_processor_info ticks delta; Linux: /proc/stat delta", "CPU busy share across all cores (0–100).", ""},20 {2, "cpu.user", "percent", "gauge", 10, false, "same as cpu.usage", "User-mode share.", ""},21 {3, "cpu.system", "percent", "gauge", 10, false, "same as cpu.usage", "Kernel-mode share.", ""},22 {4, "load.1", "count", "gauge", 10, false, "getloadavg", "1-minute load average.", ""},23 {5, "load.5", "count", "gauge", 10, false, "getloadavg", "5-minute load average.", ""},24 {6, "load.15", "count", "gauge", 10, false, "getloadavg", "15-minute load average.", ""},25 {10, "mem.used", "bytes", "gauge", 10, false, "macOS: host_statistics64 (active+wired+compressed pages); Linux: MemTotal-MemAvailable", "Memory in use.", "macOS has no single 'used' figure; this matches Activity Monitor's Memory Used closely, not exactly."},26 {11, "mem.total", "bytes", "gauge", 60, false, "hw.memsize / MemTotal", "Installed memory (unified memory on Apple Silicon).", ""},27 {12, "mem.wired", "bytes", "gauge", 10, false, "macOS: host_statistics64", "Wired memory.", "macOS only."},28 {13, "mem.compressed", "bytes", "gauge", 10, false, "macOS: host_statistics64", "Memory held by the compressor.", "macOS only."},29 {14, "mem.pressure.level", "level", "gauge", 10, false, "macOS: sysctl kern.memorystatus_vm_pressure_level", "Kernel memory pressure: 1 normal, 2 warning, 4 critical.", "macOS only; Linux reports unsupported."},30 {15, "mem.available.percent", "percent", "gauge", 10, false, "macOS: sysctl kern.memorystatus_level; Linux: MemAvailable/MemTotal", "Share of memory the kernel considers available.", ""},31 {16, "swap.used", "bytes", "gauge", 10, false, "macOS: sysctl vm.swapusage; Linux: /proc/meminfo", "Swap in use.", ""},32 {17, "swap.total", "bytes", "gauge", 60, false, "same as swap.used", "Swap currently allocated.", "macOS grows swap dynamically; total is the current allocation."},33 {20, "disk.used", "bytes", "gauge", 60, true, "statfs per mounted volume", "Used bytes per volume (label = mount point).", "APFS volumes share a container: free space is shared between volumes."},34 {21, "disk.total", "bytes", "gauge", 60, true, "statfs", "Volume size (label = mount point).", ""},35 {22, "disk.read", "bytes_per_s", "counter_rate", 10, false, "macOS: IOKit IOBlockStorageDriver statistics; Linux: /proc/diskstats", "Read throughput, all physical disks.", ""},36 {23, "disk.write", "bytes_per_s", "counter_rate", 10, false, "same as disk.read", "Write throughput, all physical disks.", ""},37 {30, "net.rx", "bytes_per_s", "counter_rate", 10, true, "getifaddrs/if_data; Linux: /proc/net/dev", "Receive throughput (label = interface).", "Only physical and tunnel interfaces carrying an address; at most 8 per node."},38 {31, "net.tx", "bytes_per_s", "counter_rate", 10, true, "same as net.rx", "Transmit throughput (label = interface).", ""},39 {32, "net.errors", "count", "counter_rate", 10, true, "same as net.rx", "Interface errors per second, in+out (label = interface).", ""},40 {33, "net.latency", "ms", "gauge", 30, true, "ICMP echo via /sbin/ping (3 packets) to the label target", "Round-trip time (label = gateway | ingest | hub).", "Unprivileged ping; a target that drops ICMP reports unavailable, not 0."},41 {34, "net.loss", "percent", "gauge", 30, true, "same as net.latency", "Packet loss over the last probe (label = target).", "3-packet probes: resolution is 33%."},42 {40, "gpu.usage", "percent", "gauge", 10, false, "macOS: IORegistry IOAccelerator PerformanceStatistics 'Device Utilization %'", "GPU utilization.", "Instantaneous driver figure, not an average over the interval. Linux: unsupported."},43 {41, "gpu.mem.used", "bytes", "gauge", 10, false, "macOS: IOAccelerator 'In use system memory'", "Unified memory in use by the GPU.", "macOS only."},44 {50, "thermal.pressure", "level", "gauge", 30, false, "macOS: notify state com.apple.system.thermalpressurelevel", "Thermal pressure: 0 nominal, 1 moderate, 2 heavy, 3 trapping, 4 sleeping.", "A coarse state, not a temperature."},45 {51, "thermal.temp", "celsius", "gauge", 30, false, "none without root", "Temperature.", "Not readable without root on Apple Silicon (powermetrics/SMC): reported as unsupported or permission_denied, never estimated."},46 {52, "power.draw", "watts", "gauge", 30, false, "none without root", "Power draw.", "Requires powermetrics (root): unsupported in the unprivileged agent."},47 {53, "battery.charge", "percent", "gauge", 60, false, "macOS: IOPowerSources", "Battery charge.", "Laptops only; desktops report unsupported."},48 {60, "uptime", "seconds", "gauge", 60, false, "kern.boottime / /proc/uptime", "Time since boot.", ""},49 {61, "procs.count", "count", "gauge", 30, false, "process table size", "Number of processes.", ""},50 {70, "agent.cpu", "percent", "gauge", 30, false, "getrusage delta of the agent process", "CPU used by the agent itself (percent of one core).", ""},51 {71, "agent.rss", "bytes", "gauge", 30, false, "agent process resident size", "Memory used by the agent itself.", ""},52}5354var byName = func() map[string]Metric {55 m := make(map[string]Metric, len(Catalog))56 for _, c := range Catalog {57 m[c.Name] = c58 }59 return m60}()6162func MetricByName(name string) (Metric, bool) { m, ok := byName[name]; return m, ok }6364// Availability states for a metric that produced no sample.65const (66 AvailUnsupported = "unsupported" // cannot be measured on this hardware/OS67 AvailPermissionDenied = "permission_denied" // measurable, but not with the agent's privileges68 AvailUnavailable = "unavailable" // should be measurable; the collector failed this round69)7071// Cardinality limits enforced by both agent and ingest.72const (73 MaxInterfaces = 874 MaxVolumes = 1275 MaxProcesses = 1576 MaxServices = 20077 MaxSamples = 40078 MaxLabelLen = 6479)80