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 7D21FA0544; Fri, 2 Sep 2022 17:56:14 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 1F12742829; Fri, 2 Sep 2022 17:56:01 +0200 (CEST) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by mails.dpdk.org (Postfix) with ESMTP id 3983040685 for ; Fri, 2 Sep 2022 17:55:58 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1662134158; x=1693670158; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=V76wwhT/nOz1DXeXuWBaMc++vsxuKKY+5X3CuYzgANQ=; b=Mv12I90bi4+A7neU45qsL3xPBarYsEtMxFYRxQEcwkv9qb41CtIM3CNL oYi3yhS6js3arWURO3Mb6H69OSv14XdHkzyixp0qBbngRbsBHTIcqw26I RfcYHHGWWmdwUmZyvUWgMISQfr8kjSBlaKyYOpGwZmyLI+U0ITZmDmqXu qitInESmwLyWIBodkLKRyZoGpmnrA7ruQofXx0Z8GT+qkRz3VUea4IarK q5fasZcrDd4zT76AW2APy+8Ffu5NN/e73aiFOLaza+zOK9raAmjDXEYkQ 7DU62naX7iZMziwPp2He5cbDWrAiilX/F0ZW9GaIrg5MnKdH7R7I5oL4c Q==; X-IronPort-AV: E=McAfee;i="6500,9779,10458"; a="359965267" X-IronPort-AV: E=Sophos;i="5.93,283,1654585200"; d="scan'208";a="359965267" Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Sep 2022 08:55:57 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.93,283,1654585200"; d="scan'208";a="941327853" Received: from silpixa00401122.ir.intel.com ([10.237.213.42]) by fmsmga005.fm.intel.com with ESMTP; 02 Sep 2022 08:55:56 -0700 From: Kevin Laatz To: dev@dpdk.org Cc: anatoly.burakov@intel.com, Kevin Laatz Subject: [PATCH v5 3/3] doc: add howto guide for lcore poll busyness Date: Fri, 2 Sep 2022 16:58:27 +0100 Message-Id: <20220902155827.79076-4-kevin.laatz@intel.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20220902155827.79076-1-kevin.laatz@intel.com> References: <24c49429394294cfbf0d9c506b205029bac77c8b.1657890378.git.anatoly.burakov@intel.com> <20220902155827.79076-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