Documentation/networking/statistics.rst

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