Collectors
Source: Packages/ORIXMonitorCore/Sources/ORIXMonitorCore/Collectors/.
A 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.
Common design
flowchart TD
R["Read cumulative counters"] --> B{"Baseline exists?"}
B -- "no" --> S["Store baseline, return no rate"]
B -- "yes" --> D["CounterMath.delta"]
D --> W{"Went backwards?"}
W -- "reset" --> N["Rate is nil for this interval"]
W -- "ok or one wrap" --> T["CounterMath.rate = delta / elapsed"]
T --> O["Typed sample"]
N --> O
S --> O
Rules every collector follows:
- 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. - Monotonic time. Elapsed time comes from
MonotonicClock.now()(CLOCK_MONOTONIC_RAW), never from the wall clock, so clock changes cannot corrupt a rate. - No baseline, no value. The first reading after creation or
reset()yieldsnilrates (or anilsample for CPU). Nothing is ever back-filled. - Counter resets are not spikes.
CounterMath.delta(previous:current:bits:)returnsnilwhen 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. - Unknown is
nil, not zero. Optional fields staynilwhen the system does not provide them. reset()drops the baseline;TelemetryEngine.resetBaselines()calls it on every stateful collector after sleep, wake, a detected gap or a pause.
| Collector | Type | State | Tier |
|---|---|---|---|
CPUCollector |
final class |
previous per-core ticks, time | fast |
MemoryCollector |
final class |
previous VMCounters, time |
fast |
DiskCollector |
final class |
previous DiskCounters per BSD name, time, DiskArbitration session |
fast (activity), slow (volumes) |
NetworkCollector |
final class |
previous InterfaceCounters per interface, time, hardware-port map (refreshed every 60 s) |
fast |
ProcessCollector |
final class |
per-PID baseline (CPU nanoseconds, energy, start time), path cache, user-name cache | process |
PowerCollector |
caseless enum |
none | slow |
ThermalLevel |
enum |
none | fast |
GPUCollector |
caseless enum |
none | fast (statistics), once (devices) |
CPUCollector
- Interface:
host_processor_info(host, PROCESSOR_CPU_LOAD_INFO, …); the returned array is released withvm_deallocate.getloadavgfor load averages. - Raw data:
CPUTicksper logical core —user,system,idle,niceas 32-bit wrapping counters. - 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. - 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. - Sample:
CPUSample { total, cores, loadAverage[3], interval }.sample()returnsnilwhen there is no baseline or the core count changed. - Topology:
CPUTopology.current()readsmachdep.cpu.brand_string,hw.physicalcpu,hw.logicalcpu,hw.nperflevelsandhw.perflevelN.{name,physicalcpu,logicalcpu}. Groups are listed in the kernel's own order with the kernel's own names.
MemoryCollector
- Interfaces:
host_statistics64(HOST_VM_INFO64)→vm_statistics64;hw.memsize;host_page_size;sysctl vm.swapusage→xsw_usage;sysctl kern.memorystatus_vm_pressure_level. - Accounting:
MemoryMath.account(_:pageSize:physical:)— see memory metrics. It uses saturating arithmetic because the kernel counters are not read atomically. - Rates: page-ins, page-outs, swap-ins and swap-outs as
Δ counter / Δ time, throughCounterMath. - Pressure:
MemoryPressureLevel(kernelValue:)maps 1 → normal, 2 → warning, 4 → critical; anything else → normal. If the sysctl cannot be read the collector assumes 1 (normal).
DiskCollector
Two independent halves.
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.
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.
NetworkCollector
- Counters:
sysctlwith MIB{CTL_NET, PF_ROUTE, 0, 0, NET_RT_IFLIST2, 0}; the buffer is walked message by message andRTM_IFINFO2records are decoded asif_msghdr2+sockaddr_dlwith unaligned loads.if_data64provides 64-bit byte, packet and error counters, MTU, type and baud rate. - Addresses:
getifaddrs+getnameinfo(NI_NUMERICHOST); the%scopesuffix of link-local IPv6 addresses is removed. - 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 fromIFT_LOOP. - Totals: only kinds with
countsTowardTotal(Wi-Fi, Ethernet, cellular) are summed. - Static helpers:
dns()(System Configuration dynamic store),wifi()(CoreWLAN; no SSID),measureLatency(host:port:attempts:timeout:)(on-demand TCP handshakes withNWConnection, guarded byResumeOnceso a continuation is resumed exactly once).
ProcessCollector
For each PID from proc_listallpids:
- 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 toPROC_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 fromproc_pidpathand is cached per (PID, start time). - Name.
pbi_name, elsepbi_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. - Statistics.
proc_pid_rusage(RUSAGE_INFO_V4). On success: CPU time (ri_user_time + ri_system_time, converted from Mach units byProcessMath.nanos),ri_phys_footprint,ri_diskio_bytesread,ri_diskio_byteswritten,ri_billed_energy; thread count fromproc_pidinfo(PROC_PIDTASKINFO). On failure:hasStatisticsstaysfalseandrestrictedis incremented. - 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.
ProcessCollector.selfUsage() is the cheap, single-process variant used every tick for ORIX Monitor's own footprint.
Caches: user names by UID (getpwuid), paths by PID. The path cache is pruned when it holds more than twice the number of live PIDs.
PowerCollector
- Documented part:
IOPSCopyPowerSourcesInfo,IOPSGetProvidingPowerSourceType,IOPSCopyPowerSourcesList,IOPSGetPowerSourceDescriptionfor the internal battery (current and maximum capacity → charge percent, charging, charged, time to empty, time to full, health string),IOPSCopyExternalPowerAdapterDetailsfor adapter wattage and name,ProcessInfo.isLowPowerModeEnabled. - Best-effort part (only if
includeBestEffortand a battery exists): all properties of theAppleSmartBatteryservice, parsed byPowerMath.batteryFields(registry:)into cycle count, design capacity, full-charge capacity, voltage, amperage, temperature and system load. See power metrics.
ThermalLevel
ThermalLevel.current() wraps ProcessInfo.processInfo.thermalState into a Comparable enum with raw values 0…3. Unknown future cases map to nominal.
GPUCollector
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 byMonitorModel.statistics(): iteratesIOAcceleratorservices and passes each property dictionary toparse(registry:), which requires aPerformanceStatisticsdictionary and readsDevice Utilization %,Renderer Utilization %,Tiler Utilization %(each clamped to 0…100),In use system memory,Alloc system memory, plusmodelandgpu-core-count. Returns an empty array when the properties are absent.
SensorCapabilityResolver and SystemInfo
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.
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.
orix-probe
Sources/orix-probe/main.swift is a command-line front end to the same collectors:
| Invocation | Output |
|---|---|
orix-probe [seconds] |
One real reading of every collector after the given interval (default 1 s) |
orix-probe --capabilities |
Adds the capability rows |
orix-probe --latency |
Adds a latency test to 1.1.1.1 |
orix-probe --strings |
JSON list of English strings the core produces at run time (used by Scripts/localize.py) |
orix-probe --bench |
JSON micro-benchmarks of collectors and store |
Limitations
- Collectors are not thread-safe by themselves; they rely on being owned by the
TelemetryEngineactor. DiskCollector.readDisks()andGPUCollector.statistics()depend on IORegistry layouts. A missing key drops the device or the figure; it does not raise an error the user sees.- 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). - No collector reads the SMC, private frameworks, or spawns a subprocess.