SPB Git

Repository Public License

collectors.md 11.5 KB

# 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:

  1. 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.
  2. Monotonic time. Elapsed time comes from MonotonicClock.now() (CLOCK_MONOTONIC_RAW), never from the wall clock, so clock changes cannot corrupt a rate.
  3. 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.
  4. 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.
  5. Unknown is nil, not zero. Optional fields stay nil when the system does not provide them.
  6. 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 with vm_deallocate. getloadavg for load averages.
  • Raw data: CPUTicks per logical core — user, system, idle, nice as 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() returns nil when there is no baseline or the core count changed.
  • 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.

# 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, through CounterMath.
  • 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: 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.
  • Addresses: getifaddrs + getnameinfo(NI_NUMERICHOST); the %scope suffix 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 from IFT_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 with NWConnection, guarded by ResumeOnce so a continuation is resumed exactly once).

# ProcessCollector

For each PID from proc_listallpids:

  1. 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).
  2. 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.
  3. 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.
  4. 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, 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.
  • 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.

# 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 by MonitorModel.
  • 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.

# 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 TelemetryEngine actor.
  • 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.
  • 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.
Files main
Menu

Theme