237 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3====================4Interface statistics5====================6 7Overview8========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 on15 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`;16 - protocol-specific statistics; and17 - driver-defined statistics available via ethtool.18 19Standard interface statistics20-----------------------------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 ens4u1u126 6: ens4u1u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 100027 link/ether 48:2a:e3:4c:b1:d1 brd ff:ff:ff:ff:ff:ff28 RX: bytes packets errors dropped overrun mcast29 74327665117 69016965 0 0 0 030 RX errors: length crc frame fifo missed31 0 0 0 0 032 TX: bytes packets errors dropped carrier collsns33 21405556176 44608960 0 0 0 034 TX errors: aborted fifo window heartbeat transns35 0 0 0 0 12836 altname enp58s0u1u137 38Note that `-s` has been specified twice to see all members of39: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 44Queue statistics45~~~~~~~~~~~~~~~~46 47Queue statistics are accessible via the netdev netlink family.48 49Currently no widely distributed CLI exists to access those statistics.50Kernel development tools (ynl) can be used to experiment with them,51see `Documentation/userspace-api/netlink/intro-specs.rst`.52 53Protocol-specific statistics54----------------------------55 56Protocol-specific statistics are exposed via relevant interfaces,57the same interfaces as are used to configure them.58 59ethtool60~~~~~~~61 62Ethtool exposes common low-level statistics.63All the standard statistics are expected to be maintained64by the device, not the driver (as opposed to driver-defined stats65described in the next section which mix software and hardware stats).66For devices which contain unmanaged67switches (e.g. legacy SR-IOV or multi-host NICs) the events counted68may not pertain exclusively to the packets destined to69the local host interface. In other words the events may70be counted at the network port (MAC/PHY blocks) without separation71for different host side (PCIe) devices. Such ambiguity must not72be present when internal switch is managed by Linux (so called73switchdev mode for NICs).74 75Standard ethtool statistics can be accessed via the interfaces used76for configuration. For example ethtool interface used77to configure pause frames can report corresponding hardware counters::78 79 $ ethtool --include-statistics -a eth080 Pause parameters for eth0:81 Autonegotiate: on82 RX: on83 TX: on84 Statistics:85 tx_pause_frames: 186 rx_pause_frames: 187 88General Ethernet statistics not associated with any particular89functionality are exposed via ``ethtool -S $ifc`` by specifying90the ``--groups`` parameter::91 92 $ ethtool -S eth0 --groups eth-phy eth-mac eth-ctrl rmon93 Stats for eth0:94 eth-phy-SymbolErrorDuringCarrier: 095 eth-mac-FramesTransmittedOK: 196 eth-mac-FrameTooLongErrors: 197 eth-ctrl-MACControlFramesTransmitted: 198 eth-ctrl-MACControlFramesReceived: 099 eth-ctrl-UnsupportedOpcodesReceived: 1100 rmon-etherStatsUndersizePkts: 1101 rmon-etherStatsJabbers: 0102 rmon-rx-etherStatsPkts64Octets: 1103 rmon-rx-etherStatsPkts65to127Octets: 0104 rmon-rx-etherStatsPkts128to255Octets: 0105 rmon-tx-etherStatsPkts64Octets: 2106 rmon-tx-etherStatsPkts65to127Octets: 3107 rmon-tx-etherStatsPkts128to255Octets: 0108 109Driver-defined statistics110-------------------------111 112Driver-defined ethtool statistics can be dumped using `ethtool -S $ifc`, e.g.::113 114 $ ethtool -S ens4u1u1115 NIC statistics:116 tx_single_collisions: 0117 tx_multi_collisions: 0118 119uAPIs120=====121 122procfs123------124 125The historical `/proc/net/dev` text interface gives access to the list126of interfaces as well as their statistics.127 128Note that even though this interface is using129:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`130internally it combines some of the fields.131 132sysfs133-----134 135Each device directory in sysfs contains a `statistics` directory (e.g.136`/sys/class/net/lo/statistics/`) with files corresponding to137members of :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`.138 139This simple interface is convenient especially in constrained/embedded140environments without access to tools. However, it's inefficient when141reading multiple stats as it internally performs a full dump of142:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`143and reports only the stat corresponding to the accessed file.144 145Sysfs files are documented in146`Documentation/ABI/testing/sysfs-class-net-statistics`.147 148 149netlink150-------151 152`rtnetlink` (`NETLINK_ROUTE`) is the preferred method of accessing153:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` stats.154 155Statistics are reported both in the responses to link information156requests (`RTM_GETLINK`) and statistic requests (`RTM_GETSTATS`,157when `IFLA_STATS_LINK_64` bit is set in the `.filter_mask` of the request).158 159netdev (netlink)160~~~~~~~~~~~~~~~~161 162`netdev` generic netlink family allows accessing page pool and per queue163statistics.164 165ethtool166-------167 168Ethtool IOCTL interface allows drivers to report implementation169specific statistics. Historically it has also been used to report170statistics for which other APIs did not exist, like per-device-queue171statistics, or standard-based statistics (e.g. RFC 2863).172 173Statistics and their string identifiers are retrieved separately.174Identifiers via `ETHTOOL_GSTRINGS` with `string_set` set to `ETH_SS_STATS`,175and values via `ETHTOOL_GSTATS`. User space should use `ETHTOOL_GDRVINFO`176to retrieve the number of statistics (`.n_stats`).177 178ethtool-netlink179---------------180 181Ethtool netlink is a replacement for the older IOCTL interface.182 183Protocol-related statistics can be requested in get commands by setting184the `ETHTOOL_FLAG_STATS` flag in `ETHTOOL_A_HEADER_FLAGS`. Currently185statistics are supported in the following commands:186 187 - `ETHTOOL_MSG_PAUSE_GET`188 - `ETHTOOL_MSG_FEC_GET`189 - `ETHTOOL_MSG_MM_GET`190 191debugfs192-------193 194Some drivers expose extra statistics via `debugfs`.195 196struct rtnl_link_stats64197========================198 199.. kernel-doc:: include/uapi/linux/if_link.h200 :identifiers: rtnl_link_stats64201 202Notes for driver authors203========================204 205Drivers should report all statistics which have a matching member in206:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` exclusively207via `.ndo_get_stats64`. Reporting such standard stats via ethtool208or debugfs will not be accepted.209 210Drivers must ensure best possible compliance with211:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`.212Please note for example that detailed error statistics must be213added into the general `rx_error` / `tx_error` counters.214 215The `.ndo_get_stats64` callback can not sleep because of accesses216via `/proc/net/dev`. If driver may sleep when retrieving the statistics217from the device it should do so periodically asynchronously and only return218a recent copy from `.ndo_get_stats64`. Ethtool interrupt coalescing interface219allows setting the frequency of refreshing statistics, if needed.220 221Retrieving ethtool statistics is a multi-syscall process, drivers are advised222to keep the number of statistics constant to avoid race conditions with223user space trying to read them.224 225Statistics must persist across routine operations like bringing the interface226down and up.227 228Kernel-internal data structures229-------------------------------230 231The following structures are internal to the kernel, their members are232translated to netlink attributes when dumped. Drivers must not overwrite233the statistics they don't report with 0.234 235- ethtool_pause_stats()236- ethtool_fec_stats()237