> For the complete documentation index, see [llms.txt](https://docs.layeronecloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.layeronecloud.com/network-monitor/architecture/measurement-model.md). # Measurement model Interface RX/TX counters are authoritative for total utilization. Interface RX/TX counters are authoritative for total utilization. Packet observations are attributed to `(site, logical segment, MAC)` and grouped into bounded, destination-aware application facts. A rollup carries both total and attributed bytes, libpcap drop counters, and coverage markers. Missing observations are never scaled to look complete. Which side of a flow is "ours" decides whether it is Internet traffic and which device it belongs to. Address rules cover private ranges, the capture's connected prefixes, the site's configured application networks and addresses learnt from ARP. An uplink capture adds two rules that need no configuration and work for guests with public addresses: the router's MAC, read from the host's default route and neighbour table, marks the Internet side of every frame it sends or receives, and the capture's DDoS-protected prefixes are local. Traffic the sensor still cannot place is counted only as unscoped coverage, and the Applications card says so instead of waiting. The server judges each application fact on its own. A malformed row is skipped and every other row is stored; coverage summaries that disagree with the rows are recorded on an `application_usage_discrepancy` event, never used to discard the rows. Only a counter past the database bound skips a whole minute's facts. A capture domain is one non-overlapping bridge or interface plus its generated traffic role. `monitoring.wan` is the sole WAN resolver. It consumes versioned inventory with assigned IPs, verified physical-device kinds, bridge masters, and lower-device links, plus the interfaces the host's routing tables name as carrying a default route. Public unicast IP owners identify WAN networks, and so does a default-route owner: a node behind a NAT gateway has no public address anywhere, yet its uplink bridge is unmistakably the WAN. Either owner resolves downward to physical, bond, or VLAN capture points, so `vmbr0` is captured on `nic2`; the port's counters include forwarded guest traffic, which the bridge device's own counters do not. The binding records the evidence (`public_address`, `default_route`), the address owners, and whether the probe source is public. A private probe source measures reachability through the gateway but is never a protected DDoS target, and its provider is reported as "Behind NAT gateway" rather than looked up. A bond is captured once, excluding its slaves. VLAN address ownership remains isolated from sibling VLANs and unrelated lower-device addresses. Unresolved or overlapping public interfaces produce a visible partial-resolution warning. Private, CGNAT, loopback, link-local, documentation, reserved, multicast, and unspecified addresses do not establish WAN membership. Virtual-only SDNs and per-VM firewall/tap plumbing do not qualify. The persisted binding records the capture device, public addresses, each IP's owner, and a stable public IPv4 probe source. WAN status, DDoS, overview/live traffic, probes, monthly usage, and application capture authority consume this same result; saved roles, legacy uplink flags, and protected CIDRs cannot create a WAN. The agent validates the selected source on its recorded owner, without independently discovering a fallback. IPv6-only WANs retain traffic and DDoS monitoring but explicitly have no IPv4 reachability measurements. Non-overlapping infrastructure bridges are added as LAN. Interface names supply internal segment keys, VLAN tags are detected directly from frames, and MAC identities are learned passively. Complete inventories reconcile atomically with settings changes; identical resolutions do not churn configuration or membership epochs. Incomplete or older inventories retain the last confirmed mapping. Link-down alone does not remove a WAN. Membership epochs preserve old bindings for delayed measurements, and retired capture identities are not reused for a different interface or traffic role. DDoS destination ownership is separate from device discovery. For a WAN capture, the control plane derives exact `/32` and `/128` protected hosts from the shared WAN binding's public addresses. Operators add manual CIDRs for public ranges routed through the host but not assigned to one of those interfaces. Automatic and manual values are merged into the effective protected set sent to the sensor. Newly discovered LAN captures keep DDoS detection disabled, and an enabled WAN with no effective target reports `no_targets` instead of pretending to monitor traffic. Application boundary overrides are also separate from DDoS protected targets. Private, ULA, link-local, directly connected, and passively owned addresses form the automatic local boundary. A site may additionally define up to 128 public CIDRs it owns or routes; these application CIDRs affect Internet-versus- internal direction only and never add a DDoS protection target. Per-VM plumbing is ignored for capture but is still named on the network view. Proxmox derives `tapi`, `vethi`, `fwbri`, `fwlni`, and `fwprp` from the guest that owns the NIC, and the host side of each pair carries a MAC generated at boot rather than the guest's configured one, so the interface name is the only tie back to billing. The VMID and NIC index are read from the name and matched against the Pulsar Operations VM inventory for the site; a VMID shared by two mapped clusters is resolved by the reporting node and otherwise reported as ambiguous rather than guessed. When inventory is missing or stale the VMID is still shown, so an interface is never left unattributed just because billing is unavailable. Each one is also labelled by its place in the guest's path: the VM-side tap, the firewall bridge in front of it, the firewall-side link, and the port on the main bridge. Because Proxmox inserts a firewall bridge only when the firewall is enabled for a NIC, the path is read from the reported master and the neighbours actually observed on that node rather than from names that ought to exist. The web service calculates WAN uptime from the existing probe measurements; the node does not calculate or send uptime counters. Legacy WAN history is measured over elapsed minutes, not reported ones. A minute the sensor never reported is a minute nobody could confirm the WAN was up, so it counts against uptime; averaging only the minutes that arrived is what would let a stopped sensor read as perfect. Measurement starts when the WAN was designated, so a link added an hour ago is not judged on the day before it existed, and it stops 90–150 seconds short of now so ordinary upload lag is not mistaken for an outage. Because a single missing minute is 0.07 percent of a day, the console leads with live state rather than the rolling average: a WAN that is down now reads "Down", with the average kept alongside as history. Every received probe round now also retains its timestamp and WAN state in `WanAvailabilityMinute`, packed into one row per WAN/minute for 30 days. Failed probes followed by recovery in the same minute remain visible with second-level durations. Late delivery is ordered by observation time and duplicate timestamps retain their first value. The API streams these rows into continuous intervals, retaining only state changes in memory. Brief interruptions subtract their duration from minutes previously counted wholly up; overlapping probe failures and contact gaps are counted only once. Continuous uptime is the same measurement read as a run rather than an average: the console counts forward from the last unavailable minute or precise interruption, so a short observed failure also resets the continuous run. The server sends the instant the run started and the page ticks from it, which keeps the counter honest across a slow poll. Probe minutes are pruned at thirty days, so a run reaching that edge is reported as at least that long rather than exactly that long. The strip under the utilization chart is the same measurement read as a timeline. It covers exactly the span the chart is drawing and marks the minutes the WAN was not confirmed up where they fell, so an outage lines up with the dip in traffic above it instead of being averaged into a shorter bar. A minute the sensor reported with no target answering is drawn as an observed failure; a minute nobody reported is drawn as a gap, because it counts against uptime without being evidence of one. Minutes before the WAN was designated remain blank. Inside the reporting grace, a separate recent span uses probe minutes already received and the newest individual probe result, so a fresh healthy WAN stays green through Now. A failed latest round turns that span red even if an earlier probe in its minute succeeded. Missing contact is logged separately from paging: active captures use `max(6, 3 × live_interval_seconds)` seconds (six seconds by default); nodes without configured captures use 30 seconds to allow their slower diagnostic reports. These spans say "Node reporting gap", because silence does not establish a physical WAN failure. The server records them both during dispatcher ticks and on the next accepted request, preserving gaps that recover between ticks. Gap events remain for 90 days. Offline paging still waits for the configured silence threshold, 60 seconds by default. Continued contact cannot keep expired WAN probes green. Recent intervals never extend beyond server time, and only enter settled uptime totals after the reporting grace. Responses cap displayed precise intervals at the latest 2,000 and disclose that limit; totals include all retained interruptions. WAN interface counters provide the site Internet total. On LAN captures on the routing host, device-to-gateway frames are classified as WAN-bound device traffic and are excluded from the internal LAN total; device-to-device and local broadcast or multicast frames contribute to LAN once per observed frame. This keeps the LAN and WAN totals mutually exclusive without requiring customer-managed subnets. The same classification is recorded a second time against the observed address, so a top-talker ranking is per address rather than per machine: a device holding several addresses appears once per address, named after whichever device most recently claimed that address. Application and port detail stays on the per-MAC device scope, so the address scope costs one key per address and traffic class instead of a second full dimension set. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.layeronecloud.com/network-monitor/architecture/measurement-model.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.