SPB Git

Repository Public License

network.md 9.9 KB

# Network metrics

Sources: 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).

# Stored metrics

Refresh: 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).

Key (MetricID) Name Unit Quality Source API Stored value
network.down (netDown) Network download bytes per second derived sysctl NET_RT_IFLIST2 (if_data64) Σ Δ ifi_ibytes / Δ time over hardware interfaces
network.up (netUp) Network upload bytes per second derived same Σ Δ ifi_obytes / Δ time over hardware interfaces

"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.

Units: 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.

# Why tunnels are not added

A 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."

The same reasoning excludes bridges and loopback (traffic that never leaves the Mac).

# Reading counters

NetworkCollector.readInterfaces():

  1. sysctl with MIB {CTL_NET, PF_ROUTE, 0, 0, NET_RT_IFLIST2, 0} — once to size the buffer, once to fill it.
  2. Walk the buffer message by message using ifm_msglen; for RTM_IFINFO2 messages decode if_msghdr2 followed by a sockaddr_dl (interface name).
  3. 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.

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.

# Rate rules — NetworkMath.rates

text
down = Δ bytesIn  / elapsed
up   = Δ bytesOut / elapsed
  • elapsed is monotonic time between two samples.
  • 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).
  • The function also supports narrower counters (bits: 32) with single-wrap tolerance (legacyThirtyTwoBitCountersWrap); the collector itself always uses 64 bits.
  • An interface that appears for the first time contributes no rate until its second sample.
  • 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.

# Interface classification — NetworkMath.kind(name:ifType:hardwareType:)

Order of decisions:

Test Result
ifi_type == IFT_LOOP loopback
System Configuration hardware type IEEE80211 wifi
… WWAN cellular
… Bridge bridge
… Ethernet or FireWire ethernet
… PPP, IPSec, L2TP, VPN tunnel
Name prefix utun, ipsec, ppp, tun, tap, gif, stf, wg tunnel
Name prefix bridge bridge
Name prefix pdp_ip cellular
Anything else other

The 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.

# Displayed values

Network page (NetworkView):

Card Content Source Stored
Throughput Download / upload readouts, two-series live chart counters above yes
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
DNS and routing Primary interface, router, DNS servers, search domains SCDynamicStoreCopyValue on State:/Network/Global/DNS and State:/Network/Global/IPv4 no
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
Latency test Average, fastest, slowest, failed/attempts on-demand TCP handshakes no
Network changes Up to eight recent Connected / Disconnected events with interface names and time NWPathMonitor yes, as events
Not available Per-process network traffic — —

An 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.

Wi-Fi and DNS data are refreshed by MonitorModel every fifth snapshot (about every 10 s at the default interval), not on every tick.

Cumulative "Received" and "Sent" are the interface counters as they stand; they restart when the interface is re-created or the Mac restarts.

# Wi-Fi network name

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."

# Latency test

NetworkCollector.measureLatency(host:port:attempts:timeout:):

  • Five TCP handshakes (default) to port 443 of the host in the text field, 150 ms apart, each with a 3 s timeout.
  • 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.
  • .failed, .waiting or the timeout count as a failure.
  • It runs only when the button is pressed. The default host is 1.1.1.1 (AppSettings.latencyHost); the user can type any host.
  • 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.
  • Results are not stored and are lost when leaving the page.

This is the only network traffic ORIX Monitor ever originates.

# Network change events

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.

# Privacy mask

With 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.

# Quality class

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.

# Limitations

  • Totals are per machine, not per app. Nothing attributes traffic to a process.
  • Counters are at the interface layer: they include link-layer overhead and all protocols.
  • 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".
  • 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.
  • A reset drops one interval for that interface, so the total for that tick omits it.
  • RSSI and noise are instantaneous driver values, refreshed every few samples; no Wi-Fi history is stored.
  • linkSpeed (ifi_baudrate) is collected but not displayed; the Wi-Fi card shows CoreWLAN's transmit rate instead.
  • Packet counts are collected but not displayed; only error counts are.

# Deliberately not shown

Item Reason
Per-process network traffic Needs a network extension or a private framework. "ORIX Monitor does not intercept traffic."
Wi-Fi network name (SSID / BSSID) Requires Location Services, which is never requested.
Public IP address Would require contacting an external service.
Connections, ports, remote hosts Not collected; outside the app's scope and its privacy posture.
Continuous ping or automatic latency monitoring The app generates no traffic on its own; the latency test is manual.
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".
Files main
Menu

Theme