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 47Some of the interfaces used for configuring devices are also able 48to report related statistics. For example ethtool interface used 49to configure pause frames can report corresponding hardware counters:: 50 51 $ ethtool --include-statistics -a eth0 52 Pause parameters for eth0: 53 Autonegotiate: on 54 RX: on 55 TX: on 56 Statistics: 57 tx_pause_frames: 1 58 rx_pause_frames: 1 59 60Driver-defined statistics 61------------------------- 62 63Driver-defined ethtool statistics can be dumped using `ethtool -S $ifc`, e.g.:: 64 65 $ ethtool -S ens4u1u1 66 NIC statistics: 67 tx_single_collisions: 0 68 tx_multi_collisions: 0 69 70uAPIs 71===== 72 73procfs 74------ 75 76The historical `/proc/net/dev` text interface gives access to the list 77of interfaces as well as their statistics. 78 79Note that even though this interface is using 80:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` 81internally it combines some of the fields. 82 83sysfs 84----- 85 86Each device directory in sysfs contains a `statistics` directory (e.g. 87`/sys/class/net/lo/statistics/`) with files corresponding to 88members of :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. 89 90This simple interface is convenient especially in constrained/embedded 91environments without access to tools. However, it's inefficient when 92reading multiple stats as it internally performs a full dump of 93:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` 94and reports only the stat corresponding to the accessed file. 95 96Sysfs files are documented in 97`Documentation/ABI/testing/sysfs-class-net-statistics`. 98 99 100netlink 101------- 102 103`rtnetlink` (`NETLINK_ROUTE`) is the preferred method of accessing 104:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` stats. 105 106Statistics are reported both in the responses to link information 107requests (`RTM_GETLINK`) and statistic requests (`RTM_GETSTATS`, 108when `IFLA_STATS_LINK_64` bit is set in the `.filter_mask` of the request). 109 110ethtool 111------- 112 113Ethtool IOCTL interface allows drivers to report implementation 114specific statistics. Historically it has also been used to report 115statistics for which other APIs did not exist, like per-device-queue 116statistics, or standard-based statistics (e.g. RFC 2863). 117 118Statistics and their string identifiers are retrieved separately. 119Identifiers via `ETHTOOL_GSTRINGS` with `string_set` set to `ETH_SS_STATS`, 120and values via `ETHTOOL_GSTATS`. User space should use `ETHTOOL_GDRVINFO` 121to retrieve the number of statistics (`.n_stats`). 122 123ethtool-netlink 124--------------- 125 126Ethtool netlink is a replacement for the older IOCTL interface. 127 128Protocol-related statistics can be requested in get commands by setting 129the `ETHTOOL_FLAG_STATS` flag in `ETHTOOL_A_HEADER_FLAGS`. Currently 130statistics are supported in the following commands: 131 132 - `ETHTOOL_MSG_PAUSE_GET` 133 134debugfs 135------- 136 137Some drivers expose extra statistics via `debugfs`. 138 139struct rtnl_link_stats64 140======================== 141 142.. kernel-doc:: include/uapi/linux/if_link.h 143 :identifiers: rtnl_link_stats64 144 145Notes for driver authors 146======================== 147 148Drivers should report all statistics which have a matching member in 149:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` exclusively 150via `.ndo_get_stats64`. Reporting such standard stats via ethtool 151or debugfs will not be accepted. 152 153Drivers must ensure best possible compliance with 154:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`. 155Please note for example that detailed error statistics must be 156added into the general `rx_error` / `tx_error` counters. 157 158The `.ndo_get_stats64` callback can not sleep because of accesses 159via `/proc/net/dev`. If driver may sleep when retrieving the statistics 160from the device it should do so periodically asynchronously and only return 161a recent copy from `.ndo_get_stats64`. Ethtool interrupt coalescing interface 162allows setting the frequency of refreshing statistics, if needed. 163 164Retrieving ethtool statistics is a multi-syscall process, drivers are advised 165to keep the number of statistics constant to avoid race conditions with 166user space trying to read them. 167 168Statistics must persist across routine operations like bringing the interface 169down and up. 170 171Kernel-internal data structures 172------------------------------- 173 174The following structures are internal to the kernel, their members are 175translated to netlink attributes when dumped. Drivers must not overwrite 176the statistics they don't report with 0. 177 178- ethtool_pause_stats() 179