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