0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ====================
0004 Interface statistics
0005 ====================
0006
0007 Overview
0008 ========
0009
0010 This document is a guide to Linux network interface statistics.
0011
0012 There are three main sources of interface statistics in Linux:
0013
0014 - standard interface statistics based on
0015 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`;
0016 - protocol-specific statistics; and
0017 - driver-defined statistics available via ethtool.
0018
0019 Standard interface statistics
0020 -----------------------------
0021
0022 There are multiple interfaces to reach the standard statistics.
0023 Most commonly used is the `ip` command from `iproute2`::
0024
0025 $ ip -s -s link show dev ens4u1u1
0026 6: ens4u1u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
0027 link/ether 48:2a:e3:4c:b1:d1 brd ff:ff:ff:ff:ff:ff
0028 RX: bytes packets errors dropped overrun mcast
0029 74327665117 69016965 0 0 0 0
0030 RX errors: length crc frame fifo missed
0031 0 0 0 0 0
0032 TX: bytes packets errors dropped carrier collsns
0033 21405556176 44608960 0 0 0 0
0034 TX errors: aborted fifo window heartbeat transns
0035 0 0 0 0 128
0036 altname enp58s0u1u1
0037
0038 Note that `-s` has been specified twice to see all members of
0039 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`.
0040 If `-s` is specified once the detailed errors won't be shown.
0041
0042 `ip` supports JSON formatting via the `-j` option.
0043
0044 Protocol-specific statistics
0045 ----------------------------
0046
0047 Protocol-specific statistics are exposed via relevant interfaces,
0048 the same interfaces as are used to configure them.
0049
0050 ethtool
0051 ~~~~~~~
0052
0053 Ethtool exposes common low-level statistics.
0054 All the standard statistics are expected to be maintained
0055 by the device, not the driver (as opposed to driver-defined stats
0056 described in the next section which mix software and hardware stats).
0057 For devices which contain unmanaged
0058 switches (e.g. legacy SR-IOV or multi-host NICs) the events counted
0059 may not pertain exclusively to the packets destined to
0060 the local host interface. In other words the events may
0061 be counted at the network port (MAC/PHY blocks) without separation
0062 for different host side (PCIe) devices. Such ambiguity must not
0063 be present when internal switch is managed by Linux (so called
0064 switchdev mode for NICs).
0065
0066 Standard ethtool statistics can be accessed via the interfaces used
0067 for configuration. For example ethtool interface used
0068 to configure pause frames can report corresponding hardware counters::
0069
0070 $ ethtool --include-statistics -a eth0
0071 Pause parameters for eth0:
0072 Autonegotiate: on
0073 RX: on
0074 TX: on
0075 Statistics:
0076 tx_pause_frames: 1
0077 rx_pause_frames: 1
0078
0079 General Ethernet statistics not associated with any particular
0080 functionality are exposed via ``ethtool -S $ifc`` by specifying
0081 the ``--groups`` parameter::
0082
0083 $ ethtool -S eth0 --groups eth-phy eth-mac eth-ctrl rmon
0084 Stats for eth0:
0085 eth-phy-SymbolErrorDuringCarrier: 0
0086 eth-mac-FramesTransmittedOK: 1
0087 eth-mac-FrameTooLongErrors: 1
0088 eth-ctrl-MACControlFramesTransmitted: 1
0089 eth-ctrl-MACControlFramesReceived: 0
0090 eth-ctrl-UnsupportedOpcodesReceived: 1
0091 rmon-etherStatsUndersizePkts: 1
0092 rmon-etherStatsJabbers: 0
0093 rmon-rx-etherStatsPkts64Octets: 1
0094 rmon-rx-etherStatsPkts65to127Octets: 0
0095 rmon-rx-etherStatsPkts128to255Octets: 0
0096 rmon-tx-etherStatsPkts64Octets: 2
0097 rmon-tx-etherStatsPkts65to127Octets: 3
0098 rmon-tx-etherStatsPkts128to255Octets: 0
0099
0100 Driver-defined statistics
0101 -------------------------
0102
0103 Driver-defined ethtool statistics can be dumped using `ethtool -S $ifc`, e.g.::
0104
0105 $ ethtool -S ens4u1u1
0106 NIC statistics:
0107 tx_single_collisions: 0
0108 tx_multi_collisions: 0
0109
0110 uAPIs
0111 =====
0112
0113 procfs
0114 ------
0115
0116 The historical `/proc/net/dev` text interface gives access to the list
0117 of interfaces as well as their statistics.
0118
0119 Note that even though this interface is using
0120 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`
0121 internally it combines some of the fields.
0122
0123 sysfs
0124 -----
0125
0126 Each device directory in sysfs contains a `statistics` directory (e.g.
0127 `/sys/class/net/lo/statistics/`) with files corresponding to
0128 members of :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`.
0129
0130 This simple interface is convenient especially in constrained/embedded
0131 environments without access to tools. However, it's inefficient when
0132 reading multiple stats as it internally performs a full dump of
0133 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`
0134 and reports only the stat corresponding to the accessed file.
0135
0136 Sysfs files are documented in
0137 `Documentation/ABI/testing/sysfs-class-net-statistics`.
0138
0139
0140 netlink
0141 -------
0142
0143 `rtnetlink` (`NETLINK_ROUTE`) is the preferred method of accessing
0144 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` stats.
0145
0146 Statistics are reported both in the responses to link information
0147 requests (`RTM_GETLINK`) and statistic requests (`RTM_GETSTATS`,
0148 when `IFLA_STATS_LINK_64` bit is set in the `.filter_mask` of the request).
0149
0150 ethtool
0151 -------
0152
0153 Ethtool IOCTL interface allows drivers to report implementation
0154 specific statistics. Historically it has also been used to report
0155 statistics for which other APIs did not exist, like per-device-queue
0156 statistics, or standard-based statistics (e.g. RFC 2863).
0157
0158 Statistics and their string identifiers are retrieved separately.
0159 Identifiers via `ETHTOOL_GSTRINGS` with `string_set` set to `ETH_SS_STATS`,
0160 and values via `ETHTOOL_GSTATS`. User space should use `ETHTOOL_GDRVINFO`
0161 to retrieve the number of statistics (`.n_stats`).
0162
0163 ethtool-netlink
0164 ---------------
0165
0166 Ethtool netlink is a replacement for the older IOCTL interface.
0167
0168 Protocol-related statistics can be requested in get commands by setting
0169 the `ETHTOOL_FLAG_STATS` flag in `ETHTOOL_A_HEADER_FLAGS`. Currently
0170 statistics are supported in the following commands:
0171
0172 - `ETHTOOL_MSG_PAUSE_GET`
0173 - `ETHTOOL_MSG_FEC_GET`
0174
0175 debugfs
0176 -------
0177
0178 Some drivers expose extra statistics via `debugfs`.
0179
0180 struct rtnl_link_stats64
0181 ========================
0182
0183 .. kernel-doc:: include/uapi/linux/if_link.h
0184 :identifiers: rtnl_link_stats64
0185
0186 Notes for driver authors
0187 ========================
0188
0189 Drivers should report all statistics which have a matching member in
0190 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` exclusively
0191 via `.ndo_get_stats64`. Reporting such standard stats via ethtool
0192 or debugfs will not be accepted.
0193
0194 Drivers must ensure best possible compliance with
0195 :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`.
0196 Please note for example that detailed error statistics must be
0197 added into the general `rx_error` / `tx_error` counters.
0198
0199 The `.ndo_get_stats64` callback can not sleep because of accesses
0200 via `/proc/net/dev`. If driver may sleep when retrieving the statistics
0201 from the device it should do so periodically asynchronously and only return
0202 a recent copy from `.ndo_get_stats64`. Ethtool interrupt coalescing interface
0203 allows setting the frequency of refreshing statistics, if needed.
0204
0205 Retrieving ethtool statistics is a multi-syscall process, drivers are advised
0206 to keep the number of statistics constant to avoid race conditions with
0207 user space trying to read them.
0208
0209 Statistics must persist across routine operations like bringing the interface
0210 down and up.
0211
0212 Kernel-internal data structures
0213 -------------------------------
0214
0215 The following structures are internal to the kernel, their members are
0216 translated to netlink attributes when dumped. Drivers must not overwrite
0217 the statistics they don't report with 0.
0218
0219 - ethtool_pause_stats()
0220 - ethtool_fec_stats()
