Inspect Interface and Hardware Counters with ip stats

You will use ip stats to inspect interface counters, narrow the output to one device or statistics 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 the ip command is installed and that you know the interface you want to inspect. Replace INTERFACE_NAME with a real name such as enp0s31f6. The inspection commands normally need no elevated privileges. The setting command 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 relying on output in a script:

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

The subcommand is part of the larger ip utility. Ask it for the grammar when you need to check a spelling or 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 requests all available statistics for all network devices:

$ 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 may be very long. Device drivers can expose empty groups, counters with different headings, or no entry for a statistic at all. The fields under group link are the same link statistics shown by ip -s link show. They are useful for ordinary RX and TX traffic checks, while the other groups expose more specialised data.

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

3. Limit the result to one interface

Use dev when you are investigating one interface. This reduces distraction 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 printed by ip link show. A renamed device, a network namespace, or a short-lived virtual interface can make a previously valid name fail. 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 for hardware-oriented suites, including cpu_hit, hw_stats_info and l3_stats.
• group xstats for extended bridge or bond statistics on the device.
• group xstats_slave for extended statistics relating to a bridge or bond slave.
• group afstats for address-family-specific statistics, including MPLS.

For example, inspect 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 command asks only for the state information:

$ ip stats show dev INTERFACE_NAME group offload subgroup hw_stats_info

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

5. Enable L3 hardware statistics only when required

L3 statistics describe traffic handled in hardware for an object corresponding to the software interface. The suite is disabled by default. Enabling it is a state change and may add device work, so do it only when the hardware and driver support the measurement you 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 toggles collection for the named device. It also does not guarantee that 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 interpreting L3 counters. Do not repeatedly toggle the setting as a substitute for checking support.

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

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

That command does not restore any counters already observed; it 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 includes information about the selected suite. Counters are device-specific and can remain at zero until matching traffic passes through the hardware object. Compare two samples rather than reading a single 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 exists. An unknown group or subgroup means the installed iproute2 build does not accept that spelling; use ip stats help and its matching manual. Empty specialised output is not automatically an error: support varies by device type and driver.