Generic networking statistics for netlink users

통계 그룹

일반 네트워킹 통계 카운터는 구조체별로 묶입니다. `gnet_stats_basic`은 `TCA_STATS_BASIC` 기본 통계, `gnet_stats_rate_est`는 `TCA_STATS_RATE_EST` 속도 추정치, `gnet_stats_queue`는 `TCA_STATS_QUEUE` 큐 통계로 내보냅니다. 애플리케이션 전용 데이터는 고정 구조체 없이 `TCA_STATS_APP` TLV를 사용합니다.

.. SPDX-License-Identifier: GPL-2.0

===============================================
Generic networking statistics for netlink users
===============================================

Statistic counters are grouped into structs:

==================== ===================== =====================
Struct               TLV type              Description
==================== ===================== =====================
gnet_stats_basic     TCA_STATS_BASIC       Basic statistics
gnet_stats_rate_est  TCA_STATS_RATE_EST    Rate estimator
gnet_stats_queue     TCA_STATS_QUEUE       Queue statistics
none                 TCA_STATS_APP         Application specific
==================== ===================== =====================

통계 수집

필요한 통계 구조체를 qdisc 전용 구조 안에 선언합니다. 예제는 `gnet_stats_basic bstats`와 `gnet_stats_queue qstats`를 둡니다. 카운터 갱신은 `qdisc->running`을 소유한 상태의 `dequeue()` 메서드에서만 수행해야 하며, 패킷 수를 증가시키고 `skb->pkt_len`을 backlog에 더하는 방식입니다.

Collecting:
-----------

Declare the statistic structs you need::

        struct mystruct {
                struct gnet_stats_basic        bstats;
                struct gnet_stats_queue        qstats;
                ...
        };

Update statistics, in dequeue() methods only, (while owning qdisc->running)::

        mystruct->tstats.packet++;
        mystruct->qstats.backlog += skb->pkt_len;

사용자 공간으로 내보내기

dump 루틴은 `struct gnet_dump`를 만들고 `gnet_stats_start_copy()`로 `TCA_STATS2` 복사를 시작합니다. 이 호출에는 출력 `skb`, 잠금, dump 상태, 정렬용 `TCA_PAD`를 전달합니다. 실패하면 공통 `rtattr_failure` 경로로 이동합니다.

그다음 `gnet_stats_copy_basic()`, `gnet_stats_copy_queue()`, `gnet_stats_copy_app()`으로 필요한 통계를 순서대로 복사합니다. 하나라도 실패하면 중단하고, 모두 성공하면 `gnet_stats_finish_copy()`로 중첩 속성을 마무리합니다.

Export to userspace (Dump):
---------------------------

::

    my_dumping_routine(struct sk_buff *skb, ...)
    {
            struct gnet_dump dump;

            if (gnet_stats_start_copy(skb, TCA_STATS2, &mystruct->lock, &dump,
                                    TCA_PAD) < 0)
                    goto rtattr_failure;

            if (gnet_stats_copy_basic(&dump, &mystruct->bstats) < 0 ||
                gnet_stats_copy_queue(&dump, &mystruct->qstats) < 0 ||
                    gnet_stats_copy_app(&dump, &xstats, sizeof(xstats)) < 0)
                    goto rtattr_failure;

            if (gnet_stats_finish_copy(&dump) < 0)
                    goto rtattr_failure;
            ...
    }

TCA_STATS/TCA_XSTATS 호환성

기존 `struct tc_stats`와 확장 통계 사용자는 `gnet_stats_start_copy_compat()` 호환 래퍼로 `TCA_STATS2`와 함께 이전 `TCA_STATS`, `TCA_XSTATS` TLV도 계속 제공할 수 있습니다. 이후 `gnet_stats_copy_*` 호출 과정에서 `struct tc_stats`가 채워져 `skb`에 추가됩니다.

`gnet_stats_copy_app()`을 호출한 경우에만 `TCA_XSTATS`가 제공됩니다. 따라서 새 중첩 통계 형식으로 전환하면서도 오래된 사용자 공간 도구가 기대하는 형식을 유지할 수 있습니다.

TCA_STATS/TCA_XSTATS backward compatibility:
--------------------------------------------

Prior users of struct tc_stats and xstats can maintain backward
compatibility by calling the compat wrappers to keep providing the
existing TLV types::

    my_dumping_routine(struct sk_buff *skb, ...)
    {
        if (gnet_stats_start_copy_compat(skb, TCA_STATS2, TCA_STATS,
                                        TCA_XSTATS, &mystruct->lock, &dump,
                                        TCA_PAD) < 0)
                    goto rtattr_failure;
            ...
    }

A struct tc_stats will be filled out during gnet_stats_copy_* calls
and appended to the skb. TCA_XSTATS is provided if gnet_stats_copy_app
was called.

잠금

통계 쓰기를 시작하기 전에 잠금을 획득하고 모든 통계를 기록한 뒤 해제합니다. 중간 오류가 발생해도 잠금은 항상 해제됩니다. 다만 잠금 객체 자체를 올바르게 초기화하는 책임은 호출자에게 있습니다.

Locking:
--------

Locks are taken before writing and released once all statistics have
been written. Locks are always released in case of an error. You
are responsible for making sure that the lock is initialized.

속도 추정기

먼저 보통 사용자 공간에서 `tc_estimator` 구조를 담은 추정기 TLV를 준비합니다. TLV는 32비트 정렬과 올바른 길이를 갖춰야 하며 interval과 EWMA log를 커널 형식으로 변환해야 합니다. `tc_estimator.c::tc_setup_estimator()`는 마이크로초 단위 측정 간격과 시간 상수를 받아 전송 가능한 `tc_estimator`를 채우므로 권장되는 변환 함수입니다. 완성한 구조체는 `TCA_RATE` TLV로 커널 코드에 전달합니다.

커널에서는 기본 통계와 속도 통계를 먼저 준비하고, 이 통계에 사용할 잠금을 초기화합니다. 이후 `gen_new_estimator(my_basicstats, my_rate_est_stats, mystats_lock, attr_with_tcestimator_struct)`를 호출합니다. 반환값 0은 성공이며, 이후 `my_rate_est_stats`를 dump할 때마다 최신 추정치가 들어 있습니다.

사용이 끝나면 `gen_kill_estimator(my_basicstats, my_rate_est_stats)`를 호출합니다. 제거 시점에도 두 통계 객체가 존재하고 유효해야 합니다.

Rate Estimator:
---------------

0) Prepare an estimator attribute. Most likely this would be in user
   space. The value of this TLV should contain a tc_estimator structure.
   As usual, such a TLV needs to be 32 bit aligned and therefore the
   length needs to be appropriately set, etc. The estimator interval
   and ewma log need to be converted to the appropriate values.
   tc_estimator.c::tc_setup_estimator() is advisable to be used as the
   conversion routine. It does a few clever things. It takes a time
   interval in microsecs, a time constant also in microsecs and a struct
   tc_estimator to  be populated. The returned tc_estimator can be
   transported to the kernel.  Transfer such a structure in a TLV of type
   TCA_RATE to your code in the kernel.

In the kernel when setting up:

1) make sure you have basic stats and rate stats setup first.
2) make sure you have initialized stats lock that is used to setup such
   stats.
3) Now initialize a new estimator::

    int ret = gen_new_estimator(my_basicstats,my_rate_est_stats,
        mystats_lock, attr_with_tcestimator_struct);

    if ret == 0
        success
    else
        failed

From now on, every time you dump my_rate_est_stats it will contain
up-to-date info.

Once you are done, call gen_kill_estimator(my_basicstats,
my_rate_est_stats) Make sure that my_basicstats and my_rate_est_stats
are still valid (i.e still exist) at the time of making this call.

작성자

이 문서는 Thomas Graf와 Jamal Hadi Salim이 작성했습니다.

Authors:
--------
- Thomas Graf <tgraf@suug.ch>
- Jamal Hadi Salim <hadi@cyberus.ca>