Measure Kernel Network Counters with lnstat

By the end of this guide you will be able to discover the network statistics your kernel exports, select a small set of counters, take a bounded sample, and hand the result to a script as JSON. The commands are read-only and normally need no elevated privileges. Allow about 10 minutes, including time to generate a little traffic if a counter is quiet.

What lnstat reads

lnstat scans files under /proc/net/stat/. Each file has a header naming its columns and then one row per CPU. The program adds the per-CPU values before displaying them. For a repeated sample, it reports the difference from the previous value, so the output is useful for watching activity rather than only reading a lifetime total.

The installed package is iproute2 6.1.0-1ubuntu6.4, and the installed program reports version 6.1.0. ctstat and rtstat are available aliases for the same program and report the same version here. Use lnstat in new notes and scripts so the command name describes what it now covers.

command -v lnstat
lnstat --version
dpkg-query -W iproute2

Expected output includes /usr/bin/lnstat, lnstat Version 6.1.0, and the installed package version. A different iproute2 release can expose different files or keys, so treat your own discovery output as authoritative.

1. Discover available files and keys

Start with the dump mode. It lists each statistics file and numbers the keys found in that file. This avoids guessing whether a counter is called lookups, searched, or something else.

lnstat --dump

On this machine the list includes arp_cache and ndisc_cache for neighbour statistics, and rt_cache for routing-related counters. The installed manual also describes ip_conntrack and nf_conntrack, but a file only appears when the running kernel exports it.

Do not treat a key as globally unique. For example, entries occurs in more than one file. The unqualified form searches for the first matching file, while file:key pins the selection to a named file.

2. Take a small, readable sample

Use -f to limit the input file, -k to choose columns, -i for the interval in seconds, -c for the number of intervals, and -s 1 for a header once at startup. This example watches the current IPv4 neighbour-table size and lookup count for one interval.

lnstat -f arp_cache -k entries,lookups -i 1 -c 1 -s 1

Typical output is a compact table like this, although the numbers change with system activity:

arp_cach|arp_cach|
 entries| lookups|
     117| 1103563|

The shortened file label and narrow columns are normal. The values are kernel counters summed across CPUs. A one-interval command is a useful smoke test; it does not tell you whether a counter is increasing over time.

3. Pin duplicate key names

When a key appears in several files, qualify it. This command selects the neighbour count from arp_cache and the slow-path routing count from rt_cache:

lnstat -k arp_cache:entries,rt_cache:in_slow_tot -i 1 -c 1 -s 1

Qualification matters in automation. Without it, a bare key can resolve to the first file containing that name, and a package or kernel change can alter which file is encountered first. Keep -f and qualified keys together when the source file is part of the meaning of your measurement.

4. Watch changes instead of totals

For a short human-readable watch, request several intervals. The first reading establishes the baseline; later readings show changes since the preceding interval. Use a positive count when testing so the command has a definite end.

lnstat -f arp_cache -k lookups,hits,res_failed -i 2 -c 5 -s 1

This takes five readings two seconds apart. lookups counts neighbour lookups, hits counts successful lookups, and res_failed counts failed lookups. The counters are observations, not diagnoses: a rise in failures tells you to investigate the surrounding network and kernel state, not that one particular cause has been proved.

The manual documents -c -1 for an ongoing one-second sample. Treat that form as a long-running process: stop it with Ctrl-C, and do not put it in a service or cron job without an explicit lifetime and log policy.

5. Export one bounded result as JSON

Use JSON when another program will consume the output. Keep the sample bounded and select one file so the shape is predictable for your own parser.

lnstat --json -f arp_cache -k entries,lookups -i 1 -c 1 -s 0

The result is a JSON object with keys such as entries, allocs, lookups, and hits, depending on what you selected. For example:

{"entries":117,"lookups":1103563}

Do not parse the aligned table output by splitting on whitespace when JSON is available. Also do not assume every key exists on every host: first validate the requested file and key with lnstat --dump, then handle a missing file or key as an operational error.

Common traps

• Using a made-up key: a typo such as searches fails with an unknown-field error. Copy the exact spelling from --dump or the relevant /proc/net/stat/ header.
• Expecting a rate: lnstat prints counter differences between intervals, not a unit-labelled per-second rate. If you need a rate, divide the difference by the actual interval in your own code.
• Assuming old files exist: ip_conntrack is documented as a backwards-compatible name for nf_conntrack, but the running system may expose neither. Discovery wins.
• Watching a quiet counter: a repeated zero can be a correct result. Generate only safe, expected traffic for a test; do not flood a production interface just to make a number move.
• Adding sudo automatically: these reads are normally available to an ordinary user. If access is restricted by local policy, diagnose that policy rather than making a monitoring script permanently privileged.

Done means

• You confirmed the installed iproute2 and lnstat versions.
• You used lnstat --dump instead of guessing file or key names.
• You selected duplicate names with file:key where the source mattered.
• You tested a bounded interval and understood that repeated readings are counter differences.
• You used --json for machine consumption and handled missing keys as a real error.