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