DPDK patches and discussions
 help / color / mirror / Atom feed
From: Kevin Laatz <kevin.laatz@intel.com>
To: dev@dpdk.org
Cc: anatoly.burakov@intel.com, Kevin Laatz <kevin.laatz@intel.com>
Subject: [PATCH v6 4/4] doc: add howto guide for lcore poll busyness
Date: Tue, 13 Sep 2022 14:19:41 +0100	[thread overview]
Message-ID: <20220913131941.582819-5-kevin.laatz@intel.com> (raw)
In-Reply-To: <20220913131941.582819-1-kevin.laatz@intel.com>

Add a new section to the howto guides for using the new lcore poll
busyness telemetry endpoints and describe general usage.

Signed-off-by: Kevin Laatz <kevin.laatz@intel.com>

---
v6:
  * Add mention of perf autotest in note mentioning perf impact.

v4:
  * Include note on perf impact when the feature is enabled
  * Add doc to toctree
  * Updates to incorporate changes made earlier in the patchset

v3:
  * Update naming to poll busyness
---
 doc/guides/howto/index.rst               |  1 +
 doc/guides/howto/lcore_poll_busyness.rst | 93 ++++++++++++++++++++++++
 2 files changed, 94 insertions(+)
 create mode 100644 doc/guides/howto/lcore_poll_busyness.rst

diff --git a/doc/guides/howto/index.rst b/doc/guides/howto/index.rst
index bf6337d021..0a9060c1d3 100644
--- a/doc/guides/howto/index.rst
+++ b/doc/guides/howto/index.rst
@@ -21,3 +21,4 @@ HowTo Guides
     debug_troubleshoot
     openwrt
     avx512
+    lcore_poll_busyness
diff --git a/doc/guides/howto/lcore_poll_busyness.rst b/doc/guides/howto/lcore_poll_busyness.rst
new file mode 100644
index 0000000000..be5ea2a85d
--- /dev/null
+++ b/doc/guides/howto/lcore_poll_busyness.rst
@@ -0,0 +1,93 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2022 Intel Corporation.
+
+Lcore Poll Busyness Telemetry
+=============================
+
+The lcore poll busyness telemetry provides a built-in, generic method of gathering
+lcore utilization metrics for running applications. These metrics are exposed
+via a new telemetry endpoint.
+
+Since most DPDK APIs polling based, the poll busyness is calculated based on
+APIs receiving 'work' (packets, completions, events, etc). Empty polls are
+considered as idle, while non-empty polls are considered busy. Using the amount
+of cycles spent processing empty polls, the busyness can be calculated and recorded.
+
+Application Specified Busyness
+------------------------------
+
+Improved accuracy of the reported busyness may need more contextual awareness
+from the application. For example, an application may make a number of calls to
+rx_burst before processing packets. If the last burst was an "empty poll", then
+the processing time of the packets would be falsely considered as "idle", since
+the last burst was empty. The application should track if any of the polls
+contained "work" to do and should mark the 'bulk' as "busy" cycles before
+proceeding to the processesing. This type of awareness is only available within
+the application.
+
+Applications can be modified to incorporate the extra contextual awareness in
+order to improve the reported busyness by marking areas of code as "busy" or
+"idle" appropriately. This can be done by inserting the timestamping macro::
+
+    RTE_LCORE_POLL_BUSYNESS_TIMESTAMP(0)    /* to mark section as idle */
+    RTE_LCORE_POLL_BUSYNESS_TIMESTAMP(32)   /* where 32 is nb_pkts to mark section as busy (non-zero is busy) */
+
+All cycles since the last state change (idle to busy, or vice versa) will be
+counted towards the current state's counter.
+
+Consuming the Telemetry
+-----------------------
+
+The telemetry gathered for lcore poll busyness can be read from the `telemetry.py`
+script via the new `/eal/lcore/poll_busyness` endpoint::
+
+    $ ./usertools/dpdk-telemetry.py
+    --> /eal/lcore/poll_busyness
+    {"/eal/lcore/poll_busyness": {"12": -1, "13": 85, "14": 84}}
+
+* Cores not collecting poll busyness will report "-1". E.g. control cores or inactive cores.
+* All enabled cores will report their poll busyness in the range 0-100.
+
+Enabling and Disabling Lcore Poll Busyness Telemetry
+----------------------------------------------------
+
+By default, the lcore poll busyness telemetry is disabled at compile time. In
+order to allow DPDK to gather this metric, the ``enable_lcore_poll_busyness``
+meson option must be set to ``true``.
+
+.. note::
+    Enabling lcore poll busyness telemetry may impact performance due to the
+    additional timestamping, potentially per poll depending on the application.
+    This can be measured with the `lcore_poll_busyness_perf_autotest`.
+
+At compile time
+^^^^^^^^^^^^^^^
+
+Support can be enabled/disabled at compile time via the meson option.
+It is disabled by default.::
+
+    $ meson configure -Denable_lcore_poll_busyness=true     #enable
+
+    $ meson configure -Denable_lcore_poll_busyness=false    #disable
+
+At run time
+^^^^^^^^^^^
+
+Support can also be enabled/disabled during runtime (if the meson option is
+enabled at compile time). Disabling at runtime comes at the cost of an additional
+branch, however no additional function calls are performed.
+
+To enable/disable support at runtime, a call can be made to the appropriately
+telemetry endpoint.
+
+Disable::
+
+    $ ./usertools/dpdk-telemetry.py
+    --> /eal/lcore/poll_busyness_disable
+    {"/eal/lcore/poll_busyness_disable": {"poll_busyness_enabled": 0}}
+
+Enable::
+
+    $ ./usertools/dpdk-telemetry.py
+    --> /eal/lcore/poll_busyness_enable
+    {"/eal/lcore/poll_busyness_enable": {"poll_busyness_enabled": 1}}
-- 
2.31.1


  parent reply	other threads:[~2022-09-13 13:17 UTC|newest]

Thread overview: 87+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-07-15 13:12 [PATCH v1 1/2] eal: add lcore busyness telemetry Anatoly Burakov
2022-07-15 13:12 ` [PATCH v1 2/2] eal: add cpuset lcore telemetry entries Anatoly Burakov
2022-07-15 13:35 ` [PATCH v1 1/2] eal: add lcore busyness telemetry Burakov, Anatoly
2022-07-15 13:46 ` Jerin Jacob
2022-07-15 14:11   ` Bruce Richardson
2022-07-15 14:18   ` Burakov, Anatoly
2022-07-15 22:13 ` Morten Brørup
2022-07-16 14:38   ` Thomas Monjalon
2022-07-17  3:10   ` Honnappa Nagarahalli
2022-07-17  9:56     ` Morten Brørup
2022-07-18  9:43       ` Burakov, Anatoly
2022-07-18 10:59         ` Morten Brørup
2022-07-19 12:20           ` Thomas Monjalon
2022-07-18 15:46         ` Stephen Hemminger
2022-08-24 16:24 ` [PATCH v2 0/3] Add lcore poll " Kevin Laatz
2022-08-24 16:24   ` [PATCH v2 1/3] eal: add " Kevin Laatz
2022-08-24 16:24   ` [PATCH v2 2/3] eal: add cpuset lcore telemetry entries Kevin Laatz
2022-08-24 16:24   ` [PATCH v2 3/3] doc: add howto guide for lcore poll busyness Kevin Laatz
2022-08-25  7:47   ` [PATCH v2 0/3] Add lcore poll busyness telemetry Morten Brørup
2022-08-25 10:53     ` Kevin Laatz
2022-08-25 15:28 ` [PATCH v3 " Kevin Laatz
2022-08-25 15:28   ` [PATCH v3 1/3] eal: add " Kevin Laatz
2022-08-26  7:05     ` Jerin Jacob
2022-08-26  8:07       ` Bruce Richardson
2022-08-26  8:16         ` Jerin Jacob
2022-08-26  8:29           ` Morten Brørup
2022-08-26 15:27             ` Kevin Laatz
2022-08-26 15:46               ` Morten Brørup
2022-08-29 10:41                 ` Bruce Richardson
2022-08-29 10:53                   ` Thomas Monjalon
2022-08-29 12:36                     ` Kevin Laatz
2022-08-29 12:49                       ` Morten Brørup
2022-08-29 13:37                         ` Kevin Laatz
2022-08-29 13:44                           ` Morten Brørup
2022-08-29 14:21                             ` Kevin Laatz
2022-08-29 11:22                   ` Morten Brørup
2022-08-26 22:06     ` Mattias Rönnblom
2022-08-29  8:23       ` Bruce Richardson
2022-08-29 13:16       ` Kevin Laatz
2022-08-30 10:26       ` Kevin Laatz
2022-08-25 15:28   ` [PATCH v3 2/3] eal: add cpuset lcore telemetry entries Kevin Laatz
2022-08-25 15:28   ` [PATCH v3 3/3] doc: add howto guide for lcore poll busyness Kevin Laatz
2022-09-01 14:39 ` [PATCH v4 0/3] Add lcore poll busyness telemetry Kevin Laatz
2022-09-01 14:39   ` [PATCH v4 1/3] eal: add " Kevin Laatz
2022-09-01 14:39   ` [PATCH v4 2/3] eal: add cpuset lcore telemetry entries Kevin Laatz
2022-09-01 14:39   ` [PATCH v4 3/3] doc: add howto guide for lcore poll busyness Kevin Laatz
2022-09-02 15:58 ` [PATCH v5 0/3] Add lcore poll busyness telemetry Kevin Laatz
2022-09-02 15:58   ` [PATCH v5 1/3] eal: add " Kevin Laatz
2022-09-03 13:33     ` Jerin Jacob
2022-09-06  9:37       ` Kevin Laatz
2022-09-02 15:58   ` [PATCH v5 2/3] eal: add cpuset lcore telemetry entries Kevin Laatz
2022-09-02 15:58   ` [PATCH v5 3/3] doc: add howto guide for lcore poll busyness Kevin Laatz
2022-09-13 13:19 ` [PATCH v6 0/4] Add lcore poll busyness telemetry Kevin Laatz
2022-09-13 13:19   ` [PATCH v6 1/4] eal: add " Kevin Laatz
2022-09-13 13:48     ` Morten Brørup
2022-09-13 13:19   ` [PATCH v6 2/4] eal: add cpuset lcore telemetry entries Kevin Laatz
2022-09-13 13:19   ` [PATCH v6 3/4] app/test: add unit tests for lcore poll busyness Kevin Laatz
2022-09-13 13:19   ` Kevin Laatz [this message]
2022-09-14  9:29 ` [PATCH v7 0/4] Add lcore poll busyness telemetry Kevin Laatz
2022-09-14  9:29   ` [PATCH v7 1/4] eal: add " Kevin Laatz
2022-09-14 14:30     ` Stephen Hemminger
2022-09-16 12:35       ` Kevin Laatz
2022-09-19 10:19     ` Konstantin Ananyev
2022-09-22 17:14       ` Kevin Laatz
2022-09-26  9:37         ` Konstantin Ananyev
2022-09-29 12:41           ` Kevin Laatz
2022-09-30 12:32             ` Jerin Jacob
2022-10-01 14:17             ` Konstantin Ananyev
2022-10-03 20:02               ` Mattias Rönnblom
2022-10-04  9:15                 ` Morten Brørup
2022-10-04 11:57                   ` Bruce Richardson
2022-10-04 14:26                     ` Mattias Rönnblom
2022-10-04 23:30                     ` Konstantin Ananyev
2022-09-30 22:13     ` Mattias Rönnblom
2022-09-14  9:29   ` [PATCH v7 2/4] eal: add cpuset lcore telemetry entries Kevin Laatz
2022-09-14  9:29   ` [PATCH v7 3/4] app/test: add unit tests for lcore poll busyness Kevin Laatz
2022-09-30 22:20     ` Mattias Rönnblom
2022-09-14  9:29   ` [PATCH v7 4/4] doc: add howto guide " Kevin Laatz
2022-09-14 14:33   ` [PATCH v7 0/4] Add lcore poll busyness telemetry Stephen Hemminger
2022-09-16 12:35     ` Kevin Laatz
2022-09-16 14:10       ` Kevin Laatz
2022-10-05 13:44   ` Kevin Laatz
2022-10-06 13:25     ` Morten Brørup
2022-10-06 15:26       ` Mattias Rönnblom
2022-10-10 15:22         ` Morten Brørup
2022-10-10 17:38           ` Mattias Rönnblom
2022-10-12 12:25             ` Morten Brørup

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220913131941.582819-5-kevin.laatz@intel.com \
    --to=kevin.laatz@intel.com \
    --cc=anatoly.burakov@intel.com \
    --cc=dev@dpdk.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).