네트워크 인터페이스 통계

Linux 인터페이스 통계의 세 출처

Linux 네트워크 인터페이스 통계는 세 출처로 나뉩니다. `struct rtnl_link_stats64` 기반 표준 인터페이스 통계, 각 protocol의 구성 인터페이스에 노출되는 protocol-specific 통계, `ethtool`로 제공하는 driver-defined 통계입니다.

.. SPDX-License-Identifier: GPL-2.0

====================
Interface statistics
====================

Overview
========

This document is a guide to Linux network interface statistics.

There are three main sources of interface statistics in Linux:

 - standard interface statistics based on
   :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`;
 - protocol-specific statistics; and
 - driver-defined statistics available via ethtool.

표준 통계와 queue 통계

가장 흔한 표준 통계 조회는 iproute2의 `ip -s -s link show dev <ifc>`입니다. `-s`를 두 번 지정해야 `rtnl_link_stats64`의 상세 error member까지 표시되고 한 번만 쓰면 세부 오류는 생략됩니다. `-j`는 JSON 출력을 제공합니다.

출력에는 RX/TX byte와 packet, 일반 error·drop, length·CRC·frame·FIFO·missed, carrier·collision 등 표준 member가 나타납니다. queue별 통계는 `netdev` netlink family로 접근합니다. 널리 배포된 CLI는 아직 없지만 kernel 개발 도구 `ynl`로 시험할 수 있으며 Netlink specification 소개 문서를 참조합니다.

Standard interface statistics
-----------------------------

There are multiple interfaces to reach the standard statistics.
Most commonly used is the `ip` command from `iproute2`::

  $ ip -s -s link show dev ens4u1u1
  6: ens4u1u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether 48:2a:e3:4c:b1:d1 brd ff:ff:ff:ff:ff:ff
    RX: bytes  packets  errors  dropped overrun mcast
    74327665117 69016965 0       0       0       0
    RX errors: length   crc     frame   fifo    missed
               0        0       0       0       0
    TX: bytes  packets  errors  dropped carrier collsns
    21405556176 44608960 0       0       0       0
    TX errors: aborted  fifo   window heartbeat transns
               0        0       0       0       128
    altname enp58s0u1u1

Note that `-s` has been specified twice to see all members of
:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`.
If `-s` is specified once the detailed errors won't be shown.

`ip` supports JSON formatting via the `-j` option.

Queue statistics
~~~~~~~~~~~~~~~~

Queue statistics are accessible via the netdev netlink family.

Currently no widely distributed CLI exists to access those statistics.
Kernel development tools (ynl) can be used to experiment with them,
see `Documentation/userspace-api/netlink/intro-specs.rst`.

Protocol-specific와 표준 ethtool 통계

protocol-specific 통계는 해당 기능을 구성하는 것과 같은 인터페이스에서 제공합니다. ethtool의 공통 low-level 통계는 driver software가 아니라 device가 유지해야 합니다. 반면 뒤의 driver-defined 통계는 software와 hardware 값을 섞을 수 있습니다.

관리되지 않는 internal switch가 있는 legacy SR-IOV 또는 multi-host NIC에서는 MAC/PHY port에서 사건을 세어 local host interface에 해당하지 않는 packet도 포함할 수 있습니다. Linux가 internal switch를 관리하는 switchdev mode에서는 이러한 모호성이 없어야 합니다.

구성 API에 `--include-statistics`를 붙여 관련 hardware counter를 볼 수 있습니다. 예를 들어 `ethtool --include-statistics -a eth0`는 pause 설정과 `tx_pause_frames`, `rx_pause_frames`를 함께 표시합니다.

특정 기능과 연결되지 않은 Ethernet 통계는 `ethtool -S eth0 --groups eth-phy eth-mac eth-ctrl rmon`으로 조회합니다. PHY symbol error, 정상 송신 frame, 너무 긴 frame, MAC control opcode, RMON packet size bucket 같은 표준 group이 제공됩니다.

Protocol-specific statistics
----------------------------

Protocol-specific statistics are exposed via relevant interfaces,
the same interfaces as are used to configure them.

ethtool
~~~~~~~

Ethtool exposes common low-level statistics.
All the standard statistics are expected to be maintained
by the device, not the driver (as opposed to driver-defined stats
described in the next section which mix software and hardware stats).
For devices which contain unmanaged
switches (e.g. legacy SR-IOV or multi-host NICs) the events counted
may not pertain exclusively to the packets destined to
the local host interface. In other words the events may
be counted at the network port (MAC/PHY blocks) without separation
for different host side (PCIe) devices. Such ambiguity must not
be present when internal switch is managed by Linux (so called
switchdev mode for NICs).

Standard ethtool statistics can be accessed via the interfaces used
for configuration. For example ethtool interface used
to configure pause frames can report corresponding hardware counters::

  $ ethtool --include-statistics -a eth0
  Pause parameters for eth0:
  Autonegotiate:        on
  RX:                        on
  TX:                        on
  Statistics:
    tx_pause_frames: 1
    rx_pause_frames: 1

General Ethernet statistics not associated with any particular
functionality are exposed via ``ethtool -S $ifc`` by specifying
the ``--groups`` parameter::

  $ ethtool -S eth0 --groups eth-phy eth-mac eth-ctrl rmon
  Stats for eth0:
  eth-phy-SymbolErrorDuringCarrier: 0
  eth-mac-FramesTransmittedOK: 1
  eth-mac-FrameTooLongErrors: 1
  eth-ctrl-MACControlFramesTransmitted: 1
  eth-ctrl-MACControlFramesReceived: 0
  eth-ctrl-UnsupportedOpcodesReceived: 1
  rmon-etherStatsUndersizePkts: 1
  rmon-etherStatsJabbers: 0
  rmon-rx-etherStatsPkts64Octets: 1
  rmon-rx-etherStatsPkts65to127Octets: 0
  rmon-rx-etherStatsPkts128to255Octets: 0
  rmon-tx-etherStatsPkts64Octets: 2
  rmon-tx-etherStatsPkts65to127Octets: 3
  rmon-tx-etherStatsPkts128to255Octets: 0

Driver-defined ethtool 통계

드라이버가 정의한 통계는 `ethtool -S <ifc>`로 dump합니다. 이름과 의미는 드라이버가 정하며 예로 `tx_single_collisions`, `tx_multi_collisions` 같은 NIC-specific counter가 있습니다.

Driver-defined statistics
-------------------------

Driver-defined ethtool statistics can be dumped using `ethtool -S $ifc`, e.g.::

  $ ethtool -S ens4u1u1
  NIC statistics:
     tx_single_collisions: 0
     tx_multi_collisions: 0

procfs와 sysfs uAPI

역사적인 `/proc/net/dev` text interface는 인터페이스 목록과 통계를 함께 제공합니다. 내부적으로 `rtnl_link_stats64`를 쓰지만 일부 field를 합쳐 노출하므로 구조체 member와 1:1 대응하지 않습니다.

각 `/sys/class/net/<dev>/statistics/` 디렉터리에는 `rtnl_link_stats64` member에 대응하는 파일이 있습니다. 도구가 없는 embedded 환경에서 편리하지만 여러 값을 읽을 때 비효율적입니다. 파일 하나를 읽을 때마다 구조체 전체를 dump한 뒤 요청한 값 하나만 반환하기 때문입니다. 파일 정의는 `Documentation/ABI/testing/sysfs-class-net-statistics`에 있습니다.

uAPIs
=====

procfs
------

The historical `/proc/net/dev` text interface gives access to the list
of interfaces as well as their statistics.

Note that even though this interface is using
:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`
internally it combines some of the fields.

sysfs
-----

Each device directory in sysfs contains a `statistics` directory (e.g.
`/sys/class/net/lo/statistics/`) with files corresponding to
members of :c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`.

This simple interface is convenient especially in constrained/embedded
environments without access to tools. However, it's inefficient when
reading multiple stats as it internally performs a full dump of
:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`
and reports only the stat corresponding to the accessed file.

Sysfs files are documented in
Documentation/ABI/testing/sysfs-class-net-statistics.

Netlink, ethtool과 debugfs uAPI

`rtnetlink`의 `NETLINK_ROUTE`가 `rtnl_link_stats64` 접근의 권장 방법입니다. `RTM_GETLINK` 응답과, request `.filter_mask`에 `IFLA_STATS_LINK_64` bit를 설정한 `RTM_GETSTATS` 응답에서 통계를 받습니다. `netdev` generic netlink family는 page pool과 queue별 통계를 제공합니다.

구형 ethtool IOCTL은 구현별 통계를 driver가 보고하게 합니다. 과거에는 queue별 통계나 RFC2863처럼 다른 API가 없던 표준 통계도 여기에 넣었습니다. 이름은 `ETHTOOL_GSTRINGS`와 `ETH_SS_STATS`, 값은 `ETHTOOL_GSTATS`로 별도 조회하고, 먼저 `ETHTOOL_GDRVINFO`의 `.n_stats`로 개수를 얻어야 합니다.

ethtool netlink는 IOCTL의 후속 인터페이스입니다. get command의 `ETHTOOL_A_HEADER_FLAGS`에 `ETHTOOL_FLAG_STATS`를 설정해 protocol 통계를 요청합니다. 현재 `ETHTOOL_MSG_PAUSE_GET`, `ETHTOOL_MSG_FEC_GET`, `ETHTOOL_MSG_MM_GET`가 지원합니다. 일부 driver는 추가 통계를 `debugfs`에 노출합니다.

netlink
-------

`rtnetlink` (`NETLINK_ROUTE`) is the preferred method of accessing
:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` stats.

Statistics are reported both in the responses to link information
requests (`RTM_GETLINK`) and statistic requests (`RTM_GETSTATS`,
when `IFLA_STATS_LINK_64` bit is set in the `.filter_mask` of the request).

netdev (netlink)
~~~~~~~~~~~~~~~~

`netdev` generic netlink family allows accessing page pool and per queue
statistics.

ethtool
-------

Ethtool IOCTL interface allows drivers to report implementation
specific statistics. Historically it has also been used to report
statistics for which other APIs did not exist, like per-device-queue
statistics, or standard-based statistics (e.g. RFC 2863).

Statistics and their string identifiers are retrieved separately.
Identifiers via `ETHTOOL_GSTRINGS` with `string_set` set to `ETH_SS_STATS`,
and values via `ETHTOOL_GSTATS`. User space should use `ETHTOOL_GDRVINFO`
to retrieve the number of statistics (`.n_stats`).

ethtool-netlink
---------------

Ethtool netlink is a replacement for the older IOCTL interface.

Protocol-related statistics can be requested in get commands by setting
the `ETHTOOL_FLAG_STATS` flag in `ETHTOOL_A_HEADER_FLAGS`. Currently
statistics are supported in the following commands:

  - `ETHTOOL_MSG_PAUSE_GET`
  - `ETHTOOL_MSG_FEC_GET`
  - `ETHTOOL_MSG_MM_GET`

debugfs
-------

Some drivers expose extra statistics via `debugfs`.

rtnl_link_stats64와 드라이버 작성 규칙

`struct rtnl_link_stats64`의 전체 member 정의는 `include/uapi/linux/if_link.h` kernel-doc에서 포함됩니다. 일치하는 표준 member가 있는 통계는 오직 `.ndo_get_stats64`로 보고해야 하며 ethtool이나 debugfs에 중복 노출하는 구현은 허용되지 않습니다.

드라이버는 구조체 의미를 최대한 정확히 지켜야 합니다. 예를 들어 상세 RX/TX error는 해당 세부 counter뿐 아니라 일반 `rx_error` 또는 `tx_error`에도 합산해야 합니다.

`/proc/net/dev` 경로에서 호출될 수 있어 `.ndo_get_stats64`는 sleep할 수 없습니다. 장치 통계를 읽는 과정이 sleep할 수 있다면 별도 비동기 작업으로 주기적으로 갱신하고 callback은 최근 copy만 반환해야 합니다. 필요하면 ethtool interrupt coalescing API로 refresh 빈도를 설정할 수 있습니다.

ethtool 통계 조회는 여러 syscall에 걸치므로 userspace가 이름과 값을 읽는 사이 race를 피하려면 통계 개수를 일정하게 유지하는 것이 좋습니다. interface down/up 같은 일상 작업 뒤에도 통계값은 유지되어야 합니다.

내부 `ethtool_pause_stats()`와 `ethtool_fec_stats()` 구조의 member는 dump 시 netlink attribute로 변환됩니다. 드라이버는 자신이 보고하지 않는 통계를 0으로 덮어쓰면 안 됩니다.

struct rtnl_link_stats64
========================

.. kernel-doc:: include/uapi/linux/if_link.h
    :identifiers: rtnl_link_stats64

Notes for driver authors
========================

Drivers should report all statistics which have a matching member in
:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>` exclusively
via `.ndo_get_stats64`. Reporting such standard stats via ethtool
or debugfs will not be accepted.

Drivers must ensure best possible compliance with
:c:type:`struct rtnl_link_stats64 <rtnl_link_stats64>`.
Please note for example that detailed error statistics must be
added into the general `rx_error` / `tx_error` counters.

The `.ndo_get_stats64` callback can not sleep because of accesses
via `/proc/net/dev`. If driver may sleep when retrieving the statistics
from the device it should do so periodically asynchronously and only return
a recent copy from `.ndo_get_stats64`. Ethtool interrupt coalescing interface
allows setting the frequency of refreshing statistics, if needed.

Retrieving ethtool statistics is a multi-syscall process, drivers are advised
to keep the number of statistics constant to avoid race conditions with
user space trying to read them.

Statistics must persist across routine operations like bringing the interface
down and up.

Kernel-internal data structures
-------------------------------

The following structures are internal to the kernel, their members are
translated to netlink attributes when dumped. Drivers must not overwrite
the statistics they don't report with 0.

- ethtool_pause_stats()
- ethtool_fec_stats()