SPB Git

Repository Public License

collectors.md 11.5 KB 132 lines markdown

1<!--2ORIX Monitor3File: docs/architecture/collectors.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Collectors910Source: `Packages/ORIXMonitorCore/Sources/ORIXMonitorCore/Collectors/`.1112A collector reads one family of system interfaces and returns a typed, `Sendable` sample. Collectors hold only what they need to compute a delta: the previous counters and the monotonic time they were read at.1314## Common design1516```mermaid17flowchart TD18    R["Read cumulative counters"] --> B{"Baseline exists?"}19    B -- "no" --> S["Store baseline, return no rate"]20    B -- "yes" --> D["CounterMath.delta"]21    D --> W{"Went backwards?"}22    W -- "reset" --> N["Rate is nil for this interval"]23    W -- "ok or one wrap" --> T["CounterMath.rate = delta / elapsed"]24    T --> O["Typed sample"]25    N --> O26    S --> O27```2829Rules every collector follows:30311. **Arithmetic is separated from I/O.** Each family has a pure `enum` (`CPUMath`, `MemoryMath`, `CounterMath`, `NetworkMath`, `DiskMath`, `ProcessMath`, `PowerMath`) that unit tests exercise without touching the system.322. **Monotonic time.** Elapsed time comes from `MonotonicClock.now()` (`CLOCK_MONOTONIC_RAW`), never from the wall clock, so clock changes cannot corrupt a rate.333. **No baseline, no value.** The first reading after creation or `reset()` yields `nil` rates (or a `nil` sample for CPU). Nothing is ever back-filled.344. **Counter resets are not spikes.** `CounterMath.delta(previous:current:bits:)` returns `nil` when a counter went backwards by more than one wraparound can explain. For 64-bit counters any decrease is a reset. For narrower counters a wrap is accepted only if the previous reading was in the top half of the range.355. **Unknown is `nil`, not zero.** Optional fields stay `nil` when the system does not provide them.366. **`reset()`** drops the baseline; `TelemetryEngine.resetBaselines()` calls it on every stateful collector after sleep, wake, a detected gap or a pause.3738| Collector | Type | State | Tier |39|---|---|---|---|40| `CPUCollector` | `final class` | previous per-core ticks, time | fast |41| `MemoryCollector` | `final class` | previous `VMCounters`, time | fast |42| `DiskCollector` | `final class` | previous `DiskCounters` per BSD name, time, DiskArbitration session | fast (activity), slow (volumes) |43| `NetworkCollector` | `final class` | previous `InterfaceCounters` per interface, time, hardware-port map (refreshed every 60 s) | fast |44| `ProcessCollector` | `final class` | per-PID baseline (CPU nanoseconds, energy, start time), path cache, user-name cache | process |45| `PowerCollector` | caseless `enum` | none | slow |46| `ThermalLevel` | `enum` | none | fast |47| `GPUCollector` | caseless `enum` | none | fast (statistics), once (devices) |4849## CPUCollector5051- **Interface:** `host_processor_info(host, PROCESSOR_CPU_LOAD_INFO, …)`; the returned array is released with `vm_deallocate`. `getloadavg` for load averages.52- **Raw data:** `CPUTicks` per logical core — `user`, `system`, `idle`, `nice` as 32-bit wrapping counters.53- **Per-core load:** `CPUMath.load(previous:current:)` uses wrapping subtraction (`&-`), folds nice time into user, and divides each state by the total. No elapsed ticks → `CPULoad.zero`, never NaN.54- **Total:** `CPUMath.aggregate(previous:current:)` sums ticks over all cores first, then divides. Each core is weighted by the time it actually ran; it is not an average of per-core percentages. A change in core count between two readings yields `.zero`.55- **Sample:** `CPUSample { total, cores, loadAverage[3], interval }`. `sample()` returns `nil` when there is no baseline or the core count changed.56- **Topology:** `CPUTopology.current()` reads `machdep.cpu.brand_string`, `hw.physicalcpu`, `hw.logicalcpu`, `hw.nperflevels` and `hw.perflevelN.{name,physicalcpu,logicalcpu}`. Groups are listed in the kernel's own order with the kernel's own names.5758## MemoryCollector5960- **Interfaces:** `host_statistics64(HOST_VM_INFO64)` → `vm_statistics64`; `hw.memsize`; `host_page_size`; `sysctl vm.swapusage` → `xsw_usage`; `sysctl kern.memorystatus_vm_pressure_level`.61- **Accounting:** `MemoryMath.account(_:pageSize:physical:)` — see [memory metrics](../metrics/memory.md). It uses saturating arithmetic because the kernel counters are not read atomically.62- **Rates:** page-ins, page-outs, swap-ins and swap-outs as `Δ counter / Δ time`, through `CounterMath`.63- **Pressure:** `MemoryPressureLevel(kernelValue:)` maps 1 → normal, 2 → warning, 4 → critical; anything else → normal. If the sysctl cannot be read the collector assumes 1 (normal).6465## DiskCollector6667Two independent halves.6869**Volumes** (`volumes()`): `FileManager.mountedVolumeURLs(includingResourceValuesForKeys:options: [.skipHiddenVolumes])`, then per volume `URLResourceValues` (name, total, available, available for important usage, internal, removable, read-only, local, root, format description). Volumes with zero total capacity are skipped. DiskArbitration (`DADiskCreateFromVolumePath`, `DADiskCopyWholeDisk`, `DADiskCopyDescription`) adds the BSD name, the whole-disk/container BSD name, the device model and the connection protocol.7071**Physical activity** (`activity(now:)`): iterates IOKit services matching `IOBlockStorageDriver`, reads the `Statistics` dictionary (`Bytes (Read)`, `Bytes (Write)`, `Operations (Read)`, `Operations (Write)`), takes the child media entry for `BSD Name` and `Size`, and the parent device for `Device Characteristics` (`Product Name`, `Medium Type`) and `Protocol Characteristics` (`Physical Interconnect`, `Physical Interconnect Location`). A device whose interconnect is `Virtual Interface` is a disk image: it is listed but excluded from the machine totals because its I/O is already counted on the backing device.7273## NetworkCollector7475- **Counters:** `sysctl` with MIB `{CTL_NET, PF_ROUTE, 0, 0, NET_RT_IFLIST2, 0}`; the buffer is walked message by message and `RTM_IFINFO2` records are decoded as `if_msghdr2` + `sockaddr_dl` with unaligned loads. `if_data64` provides 64-bit byte, packet and error counters, MTU, type and baud rate.76- **Addresses:** `getifaddrs` + `getnameinfo(NI_NUMERICHOST)`; the `%scope` suffix of link-local IPv6 addresses is removed.77- **Classification:** `NetworkMath.kind(name:ifType:hardwareType:)` uses the System Configuration hardware type when the interface is a configured port (`SCNetworkInterfaceCopyAll`), then falls back to the BSD name prefix (`utun`, `ipsec`, `ppp`, `tun`, `tap`, `gif`, `stf`, `wg` → tunnel; `bridge` → bridge; `pdp_ip` → cellular). Loopback is detected from `IFT_LOOP`.78- **Totals:** only kinds with `countsTowardTotal` (Wi-Fi, Ethernet, cellular) are summed.79- **Static helpers:** `dns()` (System Configuration dynamic store), `wifi()` (CoreWLAN; no SSID), `measureLatency(host:port:attempts:timeout:)` (on-demand TCP handshakes with `NWConnection`, guarded by `ResumeOnce` so a continuation is resumed exactly once).8081## ProcessCollector8283For each PID from `proc_listallpids`:84851. **Identity.** Try `proc_pidinfo(PROC_PIDTBSDINFO)` for the full record (name, parent, UID, start time). If the kernel refuses — which it does for processes of other users on the audited system — fall back to `PROC_PIDT_SHORTBSDINFO`, which gives PID, parent, UID and short command name but no start time. If both fail, the process is skipped. The executable path comes from `proc_pidpath` and is cached per (PID, start time).862. **Name.** `pbi_name`, else `pbi_comm`; if the name is empty or was truncated at the kernel's length limit, the last component of the executable path is used instead.873. **Statistics.** `proc_pid_rusage(RUSAGE_INFO_V4)`. On success: CPU time (`ri_user_time + ri_system_time`, converted from Mach units by `ProcessMath.nanos`), `ri_phys_footprint`, `ri_diskio_bytesread`, `ri_diskio_byteswritten`, `ri_billed_energy`; thread count from `proc_pidinfo(PROC_PIDTASKINFO)`. On failure: `hasStatistics` stays `false` and `restricted` is incremented.884. **Deltas.** CPU percent and power are computed only if a baseline exists for this PID **and its start time matches**, which prevents a recycled PID from inheriting another process's counters.8990`ProcessCollector.selfUsage()` is the cheap, single-process variant used every tick for ORIX Monitor's own footprint.9192Caches: user names by UID (`getpwuid`), paths by PID. The path cache is pruned when it holds more than twice the number of live PIDs.9394## PowerCollector9596- **Documented part:** `IOPSCopyPowerSourcesInfo`, `IOPSGetProvidingPowerSourceType`, `IOPSCopyPowerSourcesList`, `IOPSGetPowerSourceDescription` for the internal battery (current and maximum capacity → charge percent, charging, charged, time to empty, time to full, health string), `IOPSCopyExternalPowerAdapterDetails` for adapter wattage and name, `ProcessInfo.isLowPowerModeEnabled`.97- **Best-effort part** (only if `includeBestEffort` and a battery exists): all properties of the `AppleSmartBattery` service, parsed by `PowerMath.batteryFields(registry:)` into cycle count, design capacity, full-charge capacity, voltage, amperage, temperature and system load. See [power metrics](../metrics/power.md).9899## ThermalLevel100101`ThermalLevel.current()` wraps `ProcessInfo.processInfo.thermalState` into a `Comparable` enum with raw values 0…3. Unknown future cases map to `nominal`.102103## GPUCollector104105- **`devices()`:** `MTLCopyAllDevices()` → `GPUDevice` (registry ID, name, low-power / removable / headless flags, unified memory, recommended working-set size, maximum buffer length, ray-tracing and 32-bit MSAA support, threads per threadgroup). Read once by `MonitorModel`.106- **`statistics()`:** iterates `IOAccelerator` services and passes each property dictionary to `parse(registry:)`, which requires a `PerformanceStatistics` dictionary and reads `Device Utilization %`, `Renderer Utilization %`, `Tiler Utilization %` (each clamped to 0…100), `In use system memory`, `Alloc system memory`, plus `model` and `gpu-core-count`. Returns an empty array when the properties are absent.107108## SensorCapabilityResolver and SystemInfo109110`SensorCapabilityResolver.resolve()` runs the stateless collectors once and returns thirty `SensorCapability` rows (id, name, category, classification, `present`, source, note). `MonitorModel` evaluates it once at launch. The classification of each row is documented in the [capability matrix](../research/macos-capability-matrix.md).111112`SystemInfo.current()` gathers `hw.model`, the chip brand, the OS version and build (`kern.osversion`), physical memory, topology, boot time (`kern.boottime`) and host name.113114## orix-probe115116`Sources/orix-probe/main.swift` is a command-line front end to the same collectors:117118| Invocation | Output |119|---|---|120| `orix-probe [seconds]` | One real reading of every collector after the given interval (default 1 s) |121| `orix-probe --capabilities` | Adds the capability rows |122| `orix-probe --latency` | Adds a latency test to `1.1.1.1` |123| `orix-probe --strings` | JSON list of English strings the core produces at run time (used by `Scripts/localize.py`) |124| `orix-probe --bench` | JSON micro-benchmarks of collectors and store |125126## Limitations127128- Collectors are not thread-safe by themselves; they rely on being owned by the `TelemetryEngine` actor.129- `DiskCollector.readDisks()` and `GPUCollector.statistics()` depend on IORegistry layouts. A missing key drops the device or the figure; it does not raise an error the user sees.130- The process collector issues several system calls per process on each process tick; its cost grows with the number of processes. The measured cost is reported by `orix-probe --bench` (see [performance](../development/performance.md)).131- No collector reads the SMC, private frameworks, or spawns a subprocess.132
Files main
Menu

Theme