Wheelhouse docs

Diagnostics — health#

The Health tab answers one question: is the router's connection-tracking table coping? It is the first tab because a full or thrashing conntrack table produces symptoms — new connections failing while existing ones work, intermittent timeouts on a busy network — that look like almost anything else.

Two reads, both every 5 seconds: GET /api/conntrack/stats, which is show conntrack statistics parsed into one row per CPU, and GET /api/sessions for the live flow count.

The four tiles#

TileValueTone
Tracked flowsRows in the conntrack table right now, with a live dot that goes dark if the last answer is over 12 s old
Insert failuresSum of Insert fail across every CPUred when non-zero
DropsSum of Dropamber when non-zero
Early dropsSum of Early dropamber when non-zero

Under the tiles is a verdict, computed from those three sums:

Healthy. Connection tracking is healthy: nothing dropped, nothing failed to insert.

Not healthy. Connection tracking is dropping entries. That usually means nf_conntrack_max is too small for the load, or something is opening far more flows than expected — check Sessions for a host with an unusual flow count.

That second sentence is the actual diagnostic path, and it is worth following in that order: check whether the table is too small for this network, then check whether one host is responsible.

The per-CPU table#

Connection tracking keeps per-CPU counters, and the table shows them un-summed, sortable by any column. On a multi-queue NIC a single hot CPU is a real signal — it usually means receive-side scaling is not distributing the way you assumed.

ColumnWhat it counts
CPUThe core this row belongs to.
FoundLookups that matched an existing entry.
InvalidPackets that could not be associated with a valid connection.
InsertNew entries added to the table.
Insert failNew entries that could not be added. Shown in red when non-zero.
DropPackets dropped because tracking failed. Shown in amber when non-zero.
Early dropEntries evicted before they expired, to make room.
ErrorsErrors reported by the tracking subsystem.

Reading the three that matter:

  • Insert fail means a new connection could not be tracked. Either the table is full, or two CPUs raced to insert the same entry. Sustained non-zero values mean the table is too small.
  • Early drop means the table is under pressure: the kernel is evicting entries that had not expired in order to make room for new ones. This is the earliest of the three warnings, and the one worth alerting on.
  • Drop means packets were dropped as a consequence.

The panel meta reads the number of cores reported. When the table is empty the empty state names the command to run by hand: show conntrack statistics.

Byte accounting#

At the foot of the tab:

Per-flow byte accounting requires nf_conntrack_acct: set system sysctl parameter net.netfilter.nf_conntrack_acct value 1.

Without that sysctl the kernel counts flows but not bytes, so the Sessions page and the Dashboard's top talkers show flow counts with no byte totals behind them. It is a configuration change like any other: stage it on the System settings tab under kernel tunables, or from the CLI, and commit it.

Raising the table size#

The page names nf_conntrack_max and does not offer a control for it, because the right value depends on the router's memory. It is a kernel tunable like any other:

set system sysctl parameter net.netfilter.nf_conntrack_max value 262144

Stage it, read the diff, commit it. The current value is not shown by this page; read it from the console with sysctl net.netfilter.nf_conntrack_max.

What this tab will not do#

  • It does not show the table. The individual flows are on the Sessions page; this tab is the health of the mechanism, not its contents.
  • It does not keep history. These are the current counters. Nothing here is retained; the equivalent long-term view is a scrape of /metrics plus your own store.
  • It does not read nf_conntrack_max. It names the symptom and the likely cause; it does not report the limit or how close you are to it.

See also#


Checked against ui/src/pages/Diagnostics.tsx, agent/opmode.go, agent/main.go, ui/src/lib/format.ts.

Updated 2026-09-02 manual diagnostics conntrack health