1.. SPDX-License-Identifier: GPL-2.0 2 3==================== 4Interface statistics 5==================== 6 7This document is a guide to Linux network interface statistics. 8 9There are two main sources of interface statistics in Linux: 10 11 - standard interface statistics based on 12 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`; and 13 - driver-defined statistics available via ethtool. 14 15There are multiple interfaces to reach the former. Most commonly used 16is the `ip` command from `iproute2`:: 17 18 $ ip -s -s link show dev ens4u1u1 19 6: ens4u1u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000 20 link/ether 48:2a:e3:4c:b1:d1 brd ff:ff:ff:ff:ff:ff 21 RX: bytes packets errors dropped overrun mcast 22 74327665117 69016965 0 0 0 0 23 RX errors: length crc frame fifo missed 24 0 0 0 0 0 25 TX: bytes packets errors dropped carrier collsns 26 21405556176 44608960 0 0 0 0 27 TX errors: aborted fifo window heartbeat transns 28 0 0 0 0 128 29 altname enp58s0u1u1 30 31Note that `-s` has been specified twice to see all members of 32:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. 33If `-s` is specified once the detailed errors won't be shown. 34 35`ip` supports JSON formatting via the `-j` option. 36 37Ethtool statistics can be dumped using `ethtool -S $ifc`, e.g.:: 38 39 $ ethtool -S ens4u1u1 40 NIC statistics: 41 tx_single_collisions: 0 42 tx_multi_collisions: 0 43 44uAPIs 45===== 46 47procfs 48------ 49 50The historical `/proc/net/dev` text interface gives access to the list 51of interfaces as well as their statistics. 52 53Note that even though this interface is using 54:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` 55internally it combines some of the fields. 56 57sysfs 58----- 59 60Each device directory in sysfs contains a `statistics` directory (e.g. 61`/sys/class/net/lo/statistics/`) with files corresponding to 62members of :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. 63 64This simple interface is convenient especially in constrained/embedded 65environments without access to tools. However, it's inefficient when 66reading multiple stats as it internally performs a full dump of 67:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` 68and reports only the stat corresponding to the accessed file. 69 70Sysfs files are documented in 71`Documentation/ABI/testing/sysfs-class-net-statistics`. 72 73 74netlink 75------- 76 77`rtnetlink` (`NETLINK_ROUTE`) is the preferred method of accessing 78:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` stats. 79 80Statistics are reported both in the responses to link information 81requests (`RTM_GETLINK`) and statistic requests (`RTM_GETSTATS`, 82when `IFLA_STATS_LINK_64` bit is set in the `.filter_mask` of the request). 83 84ethtool 85------- 86 87Ethtool IOCTL interface allows drivers to report implementation 88specific statistics. Historically it has also been used to report 89statistics for which other APIs did not exist, like per-device-queue 90statistics, or standard-based statistics (e.g. RFC 2863). 91 92Statistics and their string identifiers are retrieved separately. 93Identifiers via `ETHTOOL_GSTRINGS` with `string_set` set to `ETH_SS_STATS`, 94and values via `ETHTOOL_GSTATS`. User space should use `ETHTOOL_GDRVINFO` 95to retrieve the number of statistics (`.n_stats`). 96 97debugfs 98------- 99 100Some drivers expose extra statistics via `debugfs`. 101 102struct rtnl_link_stats64 103======================== 104 105.. kernel-doc:: include/uapi/linux/if_link.h 106 :identifiers: rtnl_link_stats64 107 108Notes for driver authors 109======================== 110 111Drivers should report all statistics which have a matching member in 112:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` exclusively 113via `.ndo_get_stats64`. Reporting such standard stats via ethtool 114or debugfs will not be accepted. 115 116Drivers must ensure best possible compliance with 117:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. 118Please note for example that detailed error statistics must be 119added into the general `rx_error` / `tx_error` counters. 120 121The `.ndo_get_stats64` callback can not sleep because of accesses 122via `/proc/net/dev`. If driver may sleep when retrieving the statistics 123from the device it should do so periodically asynchronously and only return 124a recent copy from `.ndo_get_stats64`. Ethtool interrupt coalescing interface 125allows setting the frequency of refreshing statistics, if needed. 126 127Retrieving ethtool statistics is a multi-syscall process, drivers are advised 128to keep the number of statistics constant to avoid race conditions with 129user space trying to read them. 130 131Statistics must persist across routine operations like bringing the interface 132down and up. 133