1.. SPDX-License-Identifier: GPL-2.0 2 3==================== 4Interface statistics 5==================== 6 7Overview 8======== 9 10This document is a guide to Linux network interface statistics. 11 12There are three main sources of interface statistics in Linux: 13 14 - standard interface statistics based on 15 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`; 16 - protocol-specific statistics; and 17 - driver-defined statistics available via ethtool. 18 19Standard interface statistics 20----------------------------- 21 22There are multiple interfaces to reach the standard statistics. 23Most commonly used is the `ip` command from `iproute2`:: 24 25 $ ip -s -s link show dev ens4u1u1 26 6: ens4u1u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000 27 link/ether 48:2a:e3:4c:b1:d1 brd ff:ff:ff:ff:ff:ff 28 RX: bytes packets errors dropped overrun mcast 29 74327665117 69016965 0 0 0 0 30 RX errors: length crc frame fifo missed 31 0 0 0 0 0 32 TX: bytes packets errors dropped carrier collsns 33 21405556176 44608960 0 0 0 0 34 TX errors: aborted fifo window heartbeat transns 35 0 0 0 0 128 36 altname enp58s0u1u1 37 38Note that `-s` has been specified twice to see all members of 39:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. 40If `-s` is specified once the detailed errors won't be shown. 41 42`ip` supports JSON formatting via the `-j` option. 43 44Protocol-specific statistics 45---------------------------- 46 47Protocol-specific statistics are exposed via relevant interfaces, 48the same interfaces as are used to configure them. 49 50ethtool 51~~~~~~~ 52 53Ethtool exposes common low-level statistics. 54All the standard statistics are expected to be maintained 55by the device, not the driver (as opposed to driver-defined stats 56described in the next section which mix software and hardware stats). 57For devices which contain unmanaged 58switches (e.g. legacy SR-IOV or multi-host NICs) the events counted 59may not pertain exclusively to the packets destined to 60the local host interface. In other words the events may 61be counted at the network port (MAC/PHY blocks) without separation 62for different host side (PCIe) devices. Such ambiguity must not 63be present when internal switch is managed by Linux (so called 64switchdev mode for NICs). 65 66Standard ethtool statistics can be accessed via the interfaces used 67for configuration. For example ethtool interface used 68to configure pause frames can report corresponding hardware counters:: 69 70 $ ethtool --include-statistics -a eth0 71 Pause parameters for eth0: 72 Autonegotiate: on 73 RX: on 74 TX: on 75 Statistics: 76 tx_pause_frames: 1 77 rx_pause_frames: 1 78 79General Ethernet statistics not associated with any particular 80functionality are exposed via ``ethtool -S $ifc`` by specifying 81the ``--groups`` parameter:: 82 83 $ ethtool -S eth0 --groups eth-phy eth-mac eth-ctrl rmon 84 Stats for eth0: 85 eth-phy-SymbolErrorDuringCarrier: 0 86 eth-mac-FramesTransmittedOK: 1 87 eth-mac-FrameTooLongErrors: 1 88 eth-ctrl-MACControlFramesTransmitted: 1 89 eth-ctrl-MACControlFramesReceived: 0 90 eth-ctrl-UnsupportedOpcodesReceived: 1 91 rmon-etherStatsUndersizePkts: 1 92 rmon-etherStatsJabbers: 0 93 rmon-rx-etherStatsPkts64Octets: 1 94 rmon-rx-etherStatsPkts65to127Octets: 0 95 rmon-rx-etherStatsPkts128to255Octets: 0 96 rmon-tx-etherStatsPkts64Octets: 2 97 rmon-tx-etherStatsPkts65to127Octets: 3 98 rmon-tx-etherStatsPkts128to255Octets: 0 99 100Driver-defined statistics 101------------------------- 102 103Driver-defined ethtool statistics can be dumped using `ethtool -S $ifc`, e.g.:: 104 105 $ ethtool -S ens4u1u1 106 NIC statistics: 107 tx_single_collisions: 0 108 tx_multi_collisions: 0 109 110uAPIs 111===== 112 113procfs 114------ 115 116The historical `/proc/net/dev` text interface gives access to the list 117of interfaces as well as their statistics. 118 119Note that even though this interface is using 120:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` 121internally it combines some of the fields. 122 123sysfs 124----- 125 126Each device directory in sysfs contains a `statistics` directory (e.g. 127`/sys/class/net/lo/statistics/`) with files corresponding to 128members of :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. 129 130This simple interface is convenient especially in constrained/embedded 131environments without access to tools. However, it's inefficient when 132reading multiple stats as it internally performs a full dump of 133:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` 134and reports only the stat corresponding to the accessed file. 135 136Sysfs files are documented in 137`Documentation/ABI/testing/sysfs-class-net-statistics`. 138 139 140netlink 141------- 142 143`rtnetlink` (`NETLINK_ROUTE`) is the preferred method of accessing 144:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` stats. 145 146Statistics are reported both in the responses to link information 147requests (`RTM_GETLINK`) and statistic requests (`RTM_GETSTATS`, 148when `IFLA_STATS_LINK_64` bit is set in the `.filter_mask` of the request). 149 150ethtool 151------- 152 153Ethtool IOCTL interface allows drivers to report implementation 154specific statistics. Historically it has also been used to report 155statistics for which other APIs did not exist, like per-device-queue 156statistics, or standard-based statistics (e.g. RFC 2863). 157 158Statistics and their string identifiers are retrieved separately. 159Identifiers via `ETHTOOL_GSTRINGS` with `string_set` set to `ETH_SS_STATS`, 160and values via `ETHTOOL_GSTATS`. User space should use `ETHTOOL_GDRVINFO` 161to retrieve the number of statistics (`.n_stats`). 162 163ethtool-netlink 164--------------- 165 166Ethtool netlink is a replacement for the older IOCTL interface. 167 168Protocol-related statistics can be requested in get commands by setting 169the `ETHTOOL_FLAG_STATS` flag in `ETHTOOL_A_HEADER_FLAGS`. Currently 170statistics are supported in the following commands: 171 172 - `ETHTOOL_MSG_PAUSE_GET` 173 - `ETHTOOL_MSG_FEC_GET` 174 - `ETHTOOL_MSG_MM_GET` 175 176debugfs 177------- 178 179Some drivers expose extra statistics via `debugfs`. 180 181struct rtnl_link_stats64 182======================== 183 184.. kernel-doc:: include/uapi/linux/if_link.h 185 :identifiers: rtnl_link_stats64 186 187Notes for driver authors 188======================== 189 190Drivers should report all statistics which have a matching member in 191:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` exclusively 192via `.ndo_get_stats64`. Reporting such standard stats via ethtool 193or debugfs will not be accepted. 194 195Drivers must ensure best possible compliance with 196:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. 197Please note for example that detailed error statistics must be 198added into the general `rx_error` / `tx_error` counters. 199 200The `.ndo_get_stats64` callback can not sleep because of accesses 201via `/proc/net/dev`. If driver may sleep when retrieving the statistics 202from the device it should do so periodically asynchronously and only return 203a recent copy from `.ndo_get_stats64`. Ethtool interrupt coalescing interface 204allows setting the frequency of refreshing statistics, if needed. 205 206Retrieving ethtool statistics is a multi-syscall process, drivers are advised 207to keep the number of statistics constant to avoid race conditions with 208user space trying to read them. 209 210Statistics must persist across routine operations like bringing the interface 211down and up. 212 213Kernel-internal data structures 214------------------------------- 215 216The following structures are internal to the kernel, their members are 217translated to netlink attributes when dumped. Drivers must not overwrite 218the statistics they don't report with 0. 219 220- ethtool_pause_stats() 221- ethtool_fec_stats() 222