From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 02351A0032; Thu, 1 Sep 2022 16:37:21 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 75BBA42847; Thu, 1 Sep 2022 16:37:10 +0200 (CEST) Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by mails.dpdk.org (Postfix) with ESMTP id 60DEB41181 for ; Thu, 1 Sep 2022 16:37:07 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1662043027; x=1693579027; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=V76wwhT/nOz1DXeXuWBaMc++vsxuKKY+5X3CuYzgANQ=; b=nqFLWno8fFqbSKpBB7JvkKOO/b/1mAEIOWR/zj7GjeoKrS7myEHkedVi z+ZtaKdrf+cYjKyvxrh1qPE2aUrgpRs2G25cgKd/EvbW90EkJOEc2gzcu JryGEYd4X3MtSQ16e8vtHHP0QtAtz2V10mQGTVkJhYsoEJOAZhlvWV0Zy Gik5leRLFYoE9TSSSESW7y36N0WW9tI7FHNoRo6WoXhVu9sD4nGt26QY6 uDufNIRFULk2WR2fsWpBhUgDjahUOpkfWyleEBdqD/yAX4Xq8eeLSTBl5 +quYak3gRRUJ4grE+vZdCKQRwrjiW0x+JSHD4WsAKQ2mik39KeG/Y7WmU Q==; X-IronPort-AV: E=McAfee;i="6500,9779,10457"; a="297014208" X-IronPort-AV: E=Sophos;i="5.93,281,1654585200"; d="scan'208";a="297014208" Received: from fmsmga008.fm.intel.com ([10.253.24.58]) by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 01 Sep 2022 07:37:06 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.93,281,1654585200"; d="scan'208";a="673874911" Received: from silpixa00401122.ir.intel.com ([10.237.213.42]) by fmsmga008.fm.intel.com with ESMTP; 01 Sep 2022 07:37:05 -0700 From: Kevin Laatz To: dev@dpdk.org Cc: anatoly.burakov@intel.com, Kevin Laatz Subject: [PATCH v4 3/3] doc: add howto guide for lcore poll busyness Date: Thu, 1 Sep 2022 15:39:35 +0100 Message-Id: <20220901143936.3549493-4-kevin.laatz@intel.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20220901143936.3549493-1-kevin.laatz@intel.com> References: <24c49429394294cfbf0d9c506b205029bac77c8b.1657890378.git.anatoly.burakov@intel.com> <20220901143936.3549493-1-kevin.laatz@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org 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 --- 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 | 92 ++++++++++++++++++++++++ 2 files changed, 93 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..ebbbd4c44e --- /dev/null +++ b/doc/guides/howto/lcore_poll_busyness.rst @@ -0,0 +1,92 @@ +.. 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. + +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