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 DA2A6A0543; Wed, 24 Aug 2022 18:22:02 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7425A40DDE; Wed, 24 Aug 2022 18:22:02 +0200 (CEST) Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by mails.dpdk.org (Postfix) with ESMTP id 6B9554067B for ; Wed, 24 Aug 2022 18:22:01 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1661358121; x=1692894121; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=CzZi+HjlAulJGNYdg6frUjBQkcK74Sy42zSNa22KgOY=; b=DKWqoP58TqAYhu5Q/RZGNxmq2DYzYxGsIg4NcnKUKX9NDELvzNQhuCY3 PYg3ygewwPIAUqCc9fjiXjJRlbTqanuKpxgbSFjjY+/Jmx13UiVKoq1rz IjWrRfjEJ0+hKdlIo2AqZkYDo8DOh6dUBXVTRA7DWpVTHjr90OqD7oRIU fSRtgn7Pkz5jrKV0qXRpsYUG6YJW/DCuMK4d1QKlB/oiV6wVcbYIFrD3+ voeBz9y7VO84jcamt6YuB2Muk7dVO7NLByuZmY48N2dcq6HHO0FrZALsR 9exCqlKZHVkbZm9UwuIHI0R9Cy1wUyNYu99Sc4S8td4ahzbN1EKZO9Ysz A==; X-IronPort-AV: E=McAfee;i="6500,9779,10449"; a="295291916" X-IronPort-AV: E=Sophos;i="5.93,260,1654585200"; d="scan'208";a="295291916" Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 24 Aug 2022 09:21:55 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.93,260,1654585200"; d="scan'208";a="699128531" Received: from silpixa00401122.ir.intel.com ([10.237.213.42]) by FMSMGA003.fm.intel.com with ESMTP; 24 Aug 2022 09:21:53 -0700 From: Kevin Laatz To: dev@dpdk.org Cc: anatoly.burakov@intel.com, Kevin Laatz Subject: [PATCH v2 3/3] doc: add howto guide for lcore poll busyness Date: Wed, 24 Aug 2022 17:24:42 +0100 Message-Id: <20220824162442.631456-4-kevin.laatz@intel.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20220824162442.631456-1-kevin.laatz@intel.com> References: <24c49429394294cfbf0d9c506b205029bac77c8b.1657890378.git.anatoly.burakov@intel.com> <20220824162442.631456-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 --- doc/guides/howto/lcore_busyness.rst | 79 +++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 doc/guides/howto/lcore_busyness.rst diff --git a/doc/guides/howto/lcore_busyness.rst b/doc/guides/howto/lcore_busyness.rst new file mode 100644 index 0000000000..c8ccd3f513 --- /dev/null +++ b/doc/guides/howto/lcore_busyness.rst @@ -0,0 +1,79 @@ +.. 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 poll for packets, the poll busyness is calculated based on +APIs receiving packets. 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, a pipelined application may make a number of +calls to rx_burst before processing packets. Any processing done on this 'bulk' +would need to be marked as "busy" cycles, not just the last received burst. 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_TELEMETRY_TIMESTAMP(0) /* to mark section as idle */ + RTE_LCORE_TELEMETRY_TIMESTAMP(32) /* where 32 is nb_pkts to mark section as busy (non-zero is busy) */ + +All cycles since the last state change 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 busyness will report "-1". E.g. control cores or inactive cores. +* All enabled cores will report their busyness in the range 0-100. + +Disabling Lcore Poll Busyness Telemetry +---------------------------------- + +Some applications may not want lcore poll busyness telemetry to be tracked, for +example performance critical applications or applications that are already being +monitored by other tools gathering similar or more application specific information. + +For those applications, there are two ways in which this telemetry can be disabled. + +At compile time +^^^^^^^^^^^^^^^ + +Support can be disabled at compile time via the meson option. It is enabled by +default.:: + + $ meson configure -Denable_lcore_poll_busyness=false + +At run time +^^^^^^^^^^^ + +Support can also be disabled during runtime. This comes at the cost of an +additional branch, however no additional function calls are performed. + +To disable support at runtime, a call can be made to the +`/eal/lcore/poll_busyness_disable` endpoint:: + + $ ./usertools/dpdk-telemetry.py + --> /eal/lcore/poll_busyness_disable + {"/eal/lcore/poll_busyness_disable": {"busyness_enabled": 0}} + +It can be re-enabled at run time with the `/eal/lcore/poll_busyness_enable` +endpoint. -- 2.31.1