Inspect Interface and Hardware Counters with ip stats

Reach for ip stats when a plain ip -s link show is not enough and you need offload, bridge or address-family counters as well. You can inspect all of it, narrow it to one device or group, and check whether L3 hardware statistics are actually being collected. The examples describe iproute2 6.1.0, installed here as Ubuntu package version 6.1.0-1ubuntu6.4.

Allow about ten minutes for read-only checks. Enabling a hardware statistics suite takes longer to assess, because the result depends on the driver and device. This guide assumes ip is installed and that you know the interface you want to inspect: replace INTERFACE_NAME below with a real name such as enp0s31f6.

• Inspection needs no special privilege. The read commands normally run fine as your own account.
• The setting command is different. It changes device statistics collection, so treat it as an administrator action and check its effect afterwards.

1. Check the installed command

Confirm the binary and version before you trust its output in a script:

$ command -v ip
/usr/sbin/ip
$ ip -Version
ip utility, iproute2-6.1.0, libbpf 1.3.0

stats is a subcommand of the larger ip utility. Ask it for the grammar whenever you need to check a spelling or a supported subgroup:

$ ip stats help
Usage: ip stats help
       ip stats show [ dev DEV ] [ group GROUP [ subgroup SUBGROUP [ suite SUITE ] ... ] ... ] ...
       ip stats set dev DEV l3_stats { on | off }
GROUP := { link | xstats | xstats_slave | offload | afstats }

2. Read the complete statistics dump

With no device or group filter, ip stats show asks for every available statistic on every network device:

$ ip stats show
1: lo: group offload subgroup hw_stats_info
    l3_stats off used off
1: lo: group afstats subgroup mpls
1: lo: group offload subgroup l3_stats off used off
1: lo: group link
    RX: bytes packets errors dropped missed mcast
    ...

Real output is host-specific and can run long. A device driver can expose empty groups, counters under different headings, or no entry at all for a given statistic. The fields under group link are the same link statistics ip -s link show already gives you, useful for ordinary RX and TX checks, while the other groups expose more specialised data.

Do not treat a zero counter as proof that a feature is broken. It can just as easily mean no matching traffic has occurred yet, the device does not implement that suite, or the relevant collection is disabled.

3. Limit the result to one interface

Use dev when you are investigating one interface. It cuts the noise and makes repeated checks easier to compare:

$ ip stats show dev INTERFACE_NAME

For a compact check of the normal link counters, add group link:

$ ip stats show dev INTERFACE_NAME group link
2: INTERFACE_NAME: group link
    RX: bytes packets errors dropped missed mcast
    ...
    TX: bytes packets errors dropped carrier collsns
    ...

Use the interface name exactly as ip link show prints it. A renamed device, a network namespace, or a short-lived virtual interface can turn a previously valid name into a dead end. Check the available names without changing anything:

$ ip -o link show

4. Inspect specialised groups

The useful filters in the installed manual are:

• group offload. Hardware-oriented suites, including cpu_hit, hw_stats_info and l3_stats.
• group xstats. Extended bridge or bond statistics on the device.
• group xstats_slave. Extended statistics for a bridge or bond slave.
• group afstats. Address-family-specific statistics, including MPLS.

For example, check the state and counters of the offload suites on one device:

$ ip stats show dev INTERFACE_NAME group offload
2: INTERFACE_NAME: group offload subgroup hw_stats_info
    l3_stats off used off
2: INTERFACE_NAME: group offload subgroup l3_stats off used off

When a group accepts subgroups, adding one narrows it further. This asks only for the state information:

$ ip stats show dev INTERFACE_NAME group offload subgroup hw_stats_info

l3_stats and used answer different questions. l3_stats on means collection has been enabled for the interface. used on means a device driver has actually installed the collection. An enabled suite can still report used off.

5. Enable L3 hardware statistics only when required

L3 statistics describe traffic handled in hardware for an object matching the software interface. The suite is disabled by default. Enabling it is a state change that may add device work, so do it only when the hardware and driver support the measurement you actually need:

$ sudo ip stats set dev INTERFACE_NAME l3_stats on

This does not add an address, create an interface, or configure a route. It only toggles collection for the named device, and it does not guarantee the driver can install the counters. Verify both state fields immediately:

$ ip stats show dev INTERFACE_NAME group offload subgroup hw_stats_info
2: INTERFACE_NAME: group offload subgroup hw_stats_info
    l3_stats on used on

Your output may say used off. That means the request was enabled but the driver did not install the suite. Investigate the device and driver before you interpret any L3 counters, and do not repeatedly toggle the setting as a substitute for checking support.

To undo this specific change, disable the suite on the same interface:

$ sudo ip stats set dev INTERFACE_NAME l3_stats off
$ ip stats show dev INTERFACE_NAME group offload subgroup hw_stats_info

That does not restore any counters already observed; it just stops the requested collection. If a monitoring service depends on those counters, coordinate the change before applying it.

6. Read L3 counters after verification

Once the state check reports the collection you expect, request the L3 suite itself:

$ ip stats show dev INTERFACE_NAME group offload subgroup l3_stats
2: INTERFACE_NAME: group offload subgroup l3_stats on used on
    RX: bytes packets errors dropped mcast
    ...
    TX: bytes packets errors dropped
    ...

The command also reports information about the selected suite. Counters are device-specific and can sit at zero until matching traffic passes through the hardware object, so compare two samples rather than reading one absolute value as a throughput measurement.

Common errors

Cannot find device usually means the interface name is wrong or belongs to another network namespace: run ip -o link show in the namespace where the device actually exists. An unknown group or subgroup means the installed iproute2 build does not accept that spelling, so check ip stats help and its matching manual. Empty specialised output is not automatically an error either; support varies by device type and driver.