Repository Public License
1<!--2ORIX Monitor3File: docs/metrics/network.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Network metrics910Sources: `Collectors/NetworkCollector.swift` (`NetworkCollector`, `NetworkMath`, `InterfaceKind`, `NetworkInterface`, `NetworkSample`, `DNSConfiguration`, `WiFiLink`, `LatencyResult`), `Metrics/Metric.swift`, `App/Sources/Features/SystemViews.swift` (`NetworkView`), `App/Sources/App/MonitorModel.swift` (path monitor).1112## Stored metrics1314Refresh: every tick of the fast tier — 2 s by default while a window is visible, 5 s with only the menu bar, doubled on battery when the battery saver is on (see [telemetry](../architecture/telemetry.md)).1516| Key (`MetricID`) | Name | Unit | Quality | Source API | Stored value |17|---|---|---|---|---|---|18| `network.down` (`netDown`) | Network download | bytes per second | derived | `sysctl` `NET_RT_IFLIST2` (`if_data64`) | `Σ Δ ifi_ibytes / Δ time` over hardware interfaces |19| `network.up` (`netUp`) | Network upload | bytes per second | derived | same | `Σ Δ ifi_obytes / Δ time` over hardware interfaces |2021"Hardware interfaces" are those whose `InterfaceKind.countsTowardTotal` is true: **Wi-Fi, Ethernet and cellular**. Tunnels, bridges, loopback and unclassified interfaces are excluded from the totals.2223Units: values are **bytes** per second (not bits), formatted with the system's file-size style. The menu bar uses a compact decimal form (`MenuBarText.shortRate`: "340K", "1.2M", "1.0G"). There is no percentage convention.2425## Why tunnels are not added2627A packet sent through a VPN leaves the Mac twice from the kernel's point of view: once on the tunnel interface (`utun3`) and once, encapsulated, on the hardware link (`en0`). Adding both would roughly double the traffic. ORIX Monitor therefore sums only the links that actually carry bytes off the machine, and lists tunnels in the interface table with their own rates. The page says so: "VPN tunnels are listed below but not added, since their traffic already crosses one of those links."2829The same reasoning excludes bridges and loopback (traffic that never leaves the Mac).3031## Reading counters3233`NetworkCollector.readInterfaces()`:34351. `sysctl` with MIB `{CTL_NET, PF_ROUTE, 0, 0, NET_RT_IFLIST2, 0}` — once to size the buffer, once to fill it.362. Walk the buffer message by message using `ifm_msglen`; for `RTM_IFINFO2` messages decode `if_msghdr2` followed by a `sockaddr_dl` (interface name).373. Take from `if_data64`: `ifi_ibytes`, `ifi_obytes`, `ifi_ipackets`, `ifi_opackets`, `ifi_ierrors`, `ifi_oerrors`, `ifi_mtu`, `ifi_baudrate`, `ifi_type`; and the flags from the header.3839`NET_RT_IFLIST2` is used because its counters are 64-bit. The older `getifaddrs` / `if_data` route exposes 32-bit byte counters that wrap after 4 GiB, which on a fast link happens within seconds to minutes.4041## Rate rules — `NetworkMath.rates`4243```44down = Δ bytesIn / elapsed45up = Δ bytesOut / elapsed46```4748- `elapsed` is monotonic time between two samples.49- `CounterMath.delta` with 64-bit counters: **any decrease is a reset**. When an interface is torn down and re-created (VPN reconnect, Wi-Fi re-association on some drivers) its counters restart from zero; the rate for that interval is `nil`, never a negative number and never a spike (`interfaceResetYieldsNoRateInsteadOfASpike`).50- The function also supports narrower counters (`bits: 32`) with single-wrap tolerance (`legacyThirtyTwoBitCountersWrap`); the collector itself always uses 64 bits.51- An interface that appears for the first time contributes no rate until its second sample.52- The totals are `nil` (nothing stored) until at least one counted interface has produced a rate — in particular on the first tick and on the first tick after sleep.5354## Interface classification — `NetworkMath.kind(name:ifType:hardwareType:)`5556Order of decisions:5758| Test | Result |59|---|---|60| `ifi_type == IFT_LOOP` | loopback |61| System Configuration hardware type `IEEE80211` | wifi |62| … `WWAN` | cellular |63| … `Bridge` | bridge |64| … `Ethernet` or `FireWire` | ethernet |65| … `PPP`, `IPSec`, `L2TP`, `VPN` | tunnel |66| Name prefix `utun`, `ipsec`, `ppp`, `tun`, `tap`, `gif`, `stf`, `wg` | tunnel |67| Name prefix `bridge` | bridge |68| Name prefix `pdp_ip` | cellular |69| Anything else | other |7071The hardware type and the display name ("Wi-Fi", "Thunderbolt Ethernet") come from `SCNetworkInterfaceCopyAll`, refreshed at most every 60 s. Interfaces that are not configured hardware ports and match no prefix — `awdl0`, `llw0`, `anpi0` and similar — are classified `other` and **not** counted, which keeps AirDrop/peer-to-peer and internal links out of the totals.7273## Displayed values7475Network page (`NetworkView`):7677| Card | Content | Source | Stored |78|---|---|---|---|79| Throughput | Download / upload readouts, two-series live chart | counters above | yes |80| Wi-Fi link | Signal (RSSI, dBm), noise (dBm), signal-to-noise (RSSI − noise, dB), link rate (Mbit/s), channel · band · PHY mode | CoreWLAN `CWWiFiClient.shared().interface()` | no |81| DNS and routing | Primary interface, router, DNS servers, search domains | `SCDynamicStoreCopyValue` on `State:/Network/Global/DNS` and `State:/Network/Global/IPv4` | no |82| Interfaces | Name and BSD name, kind, status (Active / Up, no address / Down), IPv4 addresses and the first IPv6 address, download, upload, received, sent, errors (in + out) | counters, `getifaddrs` | no |83| Latency test | Average, fastest, slowest, failed/attempts | on-demand TCP handshakes | no |84| Network changes | Up to eight recent Connected / Disconnected events with interface names and time | `NWPathMonitor` | yes, as events |85| Not available | Per-process network traffic | — | — |8687An interface is **active** when it is up, running and has at least one address (`NetworkInterface.isActive`). Inactive interfaces are hidden unless "Show inactive interfaces" is ticked.8889Wi-Fi and DNS data are refreshed by `MonitorModel` every fifth snapshot (about every 10 s at the default interval), not on every tick.9091Cumulative "Received" and "Sent" are the interface counters as they stand; they restart when the interface is re-created or the Mac restarts.9293### Wi-Fi network name9495`NetworkCollector.wifi()` deliberately does not read the SSID. On current macOS that requires Location Services authorization, and ORIX Monitor asks for no permission other than (optionally) notifications. The card says: "The network name is not shown: reading it requires Location Services, which ORIX Monitor never asks for."9697### Latency test9899`NetworkCollector.measureLatency(host:port:attempts:timeout:)`:100101- Five TCP handshakes (default) to port 443 of the host in the text field, 150 ms apart, each with a 3 s timeout.102- Each sample is the monotonic time from `NWConnection.start` to the `.ready` state, in milliseconds; the connection is cancelled immediately and **nothing is sent after the handshake**.103- `.failed`, `.waiting` or the timeout count as a failure.104- It runs **only when the button is pressed**. The default host is `1.1.1.1` (`AppSettings.latencyHost`); the user can type any host.105- This is connection-establishment time: it includes name resolution (for a host name), the SYN/SYN-ACK round trip and local stack time. It is not ICMP ping, and the card says so.106- Results are not stored and are lost when leaving the page.107108This is the only network traffic ORIX Monitor ever originates.109110### Network change events111112`MonitorModel.startPathMonitor()` runs an `NWPathMonitor`. When the path description changes (status, available interfaces, expensive or constrained flags), a `StoredEvent` of kind `network` with code `network.online` or `network.offline` and the interface list is recorded, and the slow-tier readings are invalidated. The first path observed after launch establishes the baseline and records nothing.113114## Privacy mask115116With the privacy mask on (Settings › Privacy, or `-ORIXPrivacy YES`), IP addresses, the router, DNS servers and search domains are replaced by "•••" in the interface. Interface names and byte counts stay visible. Reports contain interface names and totals but no addresses in any case.117118## Quality class119120`derived` for both stored metrics (rates from measured counters). Wi-Fi link values and DNS configuration are documented public-API readings and carry no badge.121122## Limitations123124- **Totals are per machine, not per app.** Nothing attributes traffic to a process.125- **Counters are at the interface layer**: they include link-layer overhead and all protocols.126- **Classification by name prefix is heuristic** for interfaces System Configuration does not describe. A VPN that creates an interface with an unlisted prefix would be classified `other`: still not counted in the totals (correct), but labelled "Other" instead of "VPN / tunnel".127- **Tethering through a bridge or an unlisted interface type** may not be counted if the uplink is not classified as Wi-Fi, Ethernet or cellular.128- **A reset drops one interval** for that interface, so the total for that tick omits it.129- **RSSI and noise are instantaneous driver values**, refreshed every few samples; no Wi-Fi history is stored.130- **`linkSpeed` (`ifi_baudrate`) is collected but not displayed**; the Wi-Fi card shows CoreWLAN's transmit rate instead.131- **Packet counts are collected but not displayed**; only error counts are.132133## Deliberately not shown134135| Item | Reason |136|---|---|137| Per-process network traffic | Needs a network extension or a private framework. "ORIX Monitor does not intercept traffic." |138| Wi-Fi network name (SSID / BSSID) | Requires Location Services, which is never requested. |139| Public IP address | Would require contacting an external service. |140| Connections, ports, remote hosts | Not collected; outside the app's scope and its privacy posture. |141| Continuous ping or automatic latency monitoring | The app generates no traffic on its own; the latency test is manual. |142| Bluetooth, AirDrop/AWDL and other peer-to-peer link traffic in the totals | Classified `other` and excluded so that totals mean "traffic over the Mac's network links". |143