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 25848A0547; Thu, 25 Aug 2022 17:26:18 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 410794282F; Thu, 25 Aug 2022 17:26:07 +0200 (CEST) Received: from mga17.intel.com (mga17.intel.com [192.55.52.151]) by mails.dpdk.org (Postfix) with ESMTP id 3A77E40156 for ; Thu, 25 Aug 2022 17:26:04 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1661441164; x=1692977164; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=X47QqJDWnTlKxKVZkjd8rV8oFl02QpIADtCRxxbO11k=; b=Rq3q+Lj/TeADr9HA2rZCb289koj81cgRY7+qzy6MRfrDguBiCQpJHnJi 3W4ehbOGpu1th4L4S9jZ7RUXu2LK1W9jKF7oMSyQfbiqZ0Zqm3t6mWmno xlGDA3pUk23Y9raC92g4KIbcDxbPtIY2Zt4b4+30yAoxfOgUU6ap7Ex5G JTEmMWEh+dyI09YF2qduRsiH0usGHsxP55diSKHR3IemG4IVu6SrineYM HmJpK1qTO7YgtPz1REawpknx0x7R48R314FZ2QHFvAvL6f5z7DFDX3OJD 4a4r5PTG6TE8BFxdm0KLCCoxwbuw9ekola/J/+Hip5m0INQyCbbr2Wi8u Q==; X-IronPort-AV: E=McAfee;i="6500,9779,10450"; a="274660731" X-IronPort-AV: E=Sophos;i="5.93,263,1654585200"; d="scan'208";a="274660731" Received: from orsmga001.jf.intel.com ([10.7.209.18]) by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 25 Aug 2022 08:26:03 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.93,263,1654585200"; d="scan'208";a="643291071" Received: from silpixa00401122.ir.intel.com ([10.237.213.42]) by orsmga001.jf.intel.com with ESMTP; 25 Aug 2022 08:26:02 -0700 From: Kevin Laatz To: dev@dpdk.org Cc: anatoly.burakov@intel.com, Kevin Laatz Subject: [PATCH v3 3/3] doc: add howto guide for lcore poll busyness Date: Thu, 25 Aug 2022 16:28:52 +0100 Message-Id: <20220825152852.1231849-4-kevin.laatz@intel.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20220825152852.1231849-1-kevin.laatz@intel.com> References: <24c49429394294cfbf0d9c506b205029bac77c8b.1657890378.git.anatoly.burakov@intel.com> <20220825152852.1231849-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 --- v3: update naming to poll busyness --- 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..ab8dd631c7 --- /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 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. + +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": {"poll_busyness_enabled": 0}} + +It can be re-enabled at run time with the `/eal/lcore/poll_busyness_enable` +endpoint. -- 2.31.1