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