From patchwork Tue Jun 13 14:33:54 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 128621 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 358D942CAB; Tue, 13 Jun 2023 16:34:22 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 2776741611; Tue, 13 Jun 2023 16:34:22 +0200 (CEST) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by mails.dpdk.org (Postfix) with ESMTP id 0EB0D41611 for ; Tue, 13 Jun 2023 16:34:19 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1686666860; x=1718202860; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=ZzzefauLzEGXgccZl2Z+MVT53ADmYI0KSZupWC/MRV8=; b=NcJgNtKcSupK6qLnzaSq5PEmlEMabajHP3bExvSeo5puRmBf160qxz5P r1NPiOOTfyhrzhw3i/I+Y4A9ozD6CQnhXPaLr6UJ5T4jSzS/xls4UMqWK a9GexOdPLZCbJ3mkGxaN+7U3j6iZutUJw2A/wWGT7SkaV2YwcpD9yvvHY z89V0kjMLIyiBS+UxHVORdNVM5HE+L+sRo5xgj1oZebR7sZsectgru7wL NpjV9mpoglVnWtns8ZMkzlcSNqDhcRavLTSE27VjFQ0FjMvOC2+U199/n 4GBMMxZbTpS7GgRQ9UgsLTgYcONQGmXWEJseA4RHK981NK2aywS9PQd/T Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10740"; a="343039780" X-IronPort-AV: E=Sophos;i="6.00,239,1681196400"; d="scan'208";a="343039780" Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 13 Jun 2023 07:34:18 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10740"; a="1041787628" X-IronPort-AV: E=Sophos;i="6.00,239,1681196400"; d="scan'208";a="1041787628" Received: from silpixa00401385.ir.intel.com ([10.237.214.11]) by fmsmga005.fm.intel.com with ESMTP; 13 Jun 2023 07:34:15 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson Subject: [PATCH 1/2] doc/contributing: provide coding details for dynamic logging Date: Tue, 13 Jun 2023 15:33:54 +0100 Message-Id: <20230613143355.77914-2-bruce.richardson@intel.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230613143355.77914-1-bruce.richardson@intel.com> References: <20230613143355.77914-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 While the section on dynamic logging in the contributors guide covered the details of the logging naming scheme, it failed to cover exactly how the component developer, i.e. the contributor, could actually use dynamic logging in their component. Fix this by splitting the details of the naming scheme into a separate subsection, and adding to the introduction on logging, a recommendation (and example) to use RTE_LOG_REGISTER_DEFAULT. Similarly, when discussing specialization, include a reference to the RTE_LOG_REGISTER_SUFFIX macro. Signed-off-by: Bruce Richardson --- doc/guides/contributing/coding_style.rst | 17 +++++++++++++++++ lib/cfgfile/rte_cfgfile.c | 2 ++ 2 files changed, 19 insertions(+) diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index 00d6270624..f50a78a346 100644 --- a/doc/guides/contributing/coding_style.rst +++ b/doc/guides/contributing/coding_style.rst @@ -803,6 +803,21 @@ logging of a particular topic, the ``--log-level`` parameter can be provided to EAL, which will change the log level. DPDK code can register topics, which allows the user to adjust the log verbosity for that specific topic. +To register a library or driver for dynamic logging, +using the standardized naming scheme described below, +use ``RTE_LOG_REGISTER_DEFAULT`` macro to define a log-type variable inside your component's main C file. +Thereafter, it is usual to define a macro or macros inside your component to make logging more convenient. + +For example, the ``rte_cfgfile`` library defines: + +.. literalinclude:: ../../../lib/cfgfile/rte_cfgfile.c + :language: c + :start-after: Setting up dynamic logging 8< + :end-before: >8 End of setting up dynamic logging + +Dynamic Logging Naming Scheme +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + In general, the naming scheme is as follows: ``type.section.name`` * Type is the type of component, where ``lib``, ``pmd``, ``bus`` and ``user`` @@ -837,6 +852,8 @@ A specialization looks like this: * Initialization output: ``type.section.name.init`` * PF/VF mailbox output: ``type.section.name.mbox`` +These specializations are created using the ``RTE_LOG_REGISTER_SUFFIX`` macro. + A real world example is the i40e poll mode driver which exposes two specializations, one for initialization ``pmd.net.i40e.init`` and the other for the remaining driver logs ``pmd.net.i40e.driver``. diff --git a/lib/cfgfile/rte_cfgfile.c b/lib/cfgfile/rte_cfgfile.c index 9fa7d010ef..eefba6e408 100644 --- a/lib/cfgfile/rte_cfgfile.c +++ b/lib/cfgfile/rte_cfgfile.c @@ -27,11 +27,13 @@ struct rte_cfgfile { struct rte_cfgfile_section *sections; }; +/* Setting up dynamic logging 8< */ RTE_LOG_REGISTER_DEFAULT(cfgfile_logtype, INFO); #define CFG_LOG(level, fmt, args...) \ rte_log(RTE_LOG_ ## level, cfgfile_logtype, "%s(): " fmt "\n", \ __func__, ## args) +/* >8 End of setting up dynamic logging */ /** when we resize a file structure, how many extra entries * for new sections do we add in */ From patchwork Tue Jun 13 14:33:55 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 128622 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 8087842CAB; Tue, 13 Jun 2023 16:34:27 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4DCCC42BAC; Tue, 13 Jun 2023 16:34:23 +0200 (CEST) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by mails.dpdk.org (Postfix) with ESMTP id B4F0440A8A for ; Tue, 13 Jun 2023 16:34:20 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1686666860; x=1718202860; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=sCfvjlpwLWHxy0YdjLiyg+mSO86NrATV5JUQXmNPqzA=; b=NISMCiOvFXvwf1l1/KaJAryZGtWu6S4UVDR09gwsjY0AHCAlRWXsdcb/ e/ywcGl8PyQ+vgKEypwabNVB35AqWIV1PUPUT5puGCh5D1O0cDDtM7WME XGnz5/clGZFZqA1Xu4jYBoHg3n4RIX+JZBsidhhCtEa1zHcC8YwFfyXHn 7seV0q5wkX7t8bRUTdljsN2li54HMPsGDx5MWdEELee0HJj7f3RrMjyAT LCN6VpY92WSJXfzKcsDgXgVM0gmJl9OFv5HpxFCtPQTaRlpg75x2zpvar tS18SgcyhuSaekCTXXIiXH4DMeN1lm8C6saSDE5pH650cuY6oziB4m06o A==; X-IronPort-AV: E=McAfee;i="6600,9927,10740"; a="343039786" X-IronPort-AV: E=Sophos;i="6.00,239,1681196400"; d="scan'208";a="343039786" Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 13 Jun 2023 07:34:19 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10740"; a="1041787645" X-IronPort-AV: E=Sophos;i="6.00,239,1681196400"; d="scan'208";a="1041787645" Received: from silpixa00401385.ir.intel.com ([10.237.214.11]) by fmsmga005.fm.intel.com with ESMTP; 13 Jun 2023 07:34:18 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson Subject: [PATCH 2/2] doc/contributing: guidelines for logging, tracing and telemetry Date: Tue, 13 Jun 2023 15:33:55 +0100 Message-Id: <20230613143355.77914-3-bruce.richardson@intel.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230613143355.77914-1-bruce.richardson@intel.com> References: <20230613143355.77914-1-bruce.richardson@intel.com> MIME-Version: 1.0 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 As discussed by DPDK technical board [1], out contributor guide should include some details as to when to use logging vs tracing vs telemetry to provide the end user with information about the running process and the DPDK libraries it uses. [1] https://mails.dpdk.org/archives/dev/2023-March/265204.html Signed-off-by: Bruce Richardson Acked-by: Morten Brørup --- doc/guides/contributing/coding_style.rst | 2 ++ doc/guides/contributing/design.rst | 34 ++++++++++++++++++++++++ doc/guides/prog_guide/telemetry_lib.rst | 2 ++ doc/guides/prog_guide/trace_lib.rst | 2 ++ 4 files changed, 40 insertions(+) diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index f50a78a346..13b2390d9e 100644 --- a/doc/guides/contributing/coding_style.rst +++ b/doc/guides/contributing/coding_style.rst @@ -794,6 +794,8 @@ Control Statements /* NOTREACHED */ } +.. _dynamic_logging: + Dynamic Logging --------------- diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst index d24a7ff6a0..9edf3ea43b 100644 --- a/doc/guides/contributing/design.rst +++ b/doc/guides/contributing/design.rst @@ -4,6 +4,40 @@ Design ====== +Runtime Information - Logging, Tracing and Telemetry +------------------------------------------------------- + +It is often desirable to provide information to the end-user as to what is happening to the application at runtime. +DPDK provides a number of built-in mechanisms to provide this introspection: + +* :ref:`Logging` +* :ref:`Tracing` +* :ref:`Telemetry` + +Each of these has it's own strengths and suitabilities for use within DPDK components. + +Below are some guidelines for when each should be used: + +* For reporting error conditions, or other abnormal runtime issues, *logging* should be used. + Depending on the severity of the issue, the appropriate log level, for example, + ``ERROR``, ``WARNING`` or ``NOTICE``, should be used. +* In general, it is not recommended that the DPDK logging functions should be used for debugging. + Although the ``DEBUG`` log level may be used in components, it should only be used sparingly, + and the *tracing* functionality used instead. + More specifically: + + * for cases where a path through the code is only likely to be taken once, + for example, initialization code, either *logging* at ``DEBUG`` level or *tracing* may be used - + though tracing is preferred. + * where a path is to be taken multiple times within a short timeframe, for example, + datapath or regular control plane code, *tracing* should be used. + +* For numerical or statistical data generated by a component, for example, per-packet statistics, + *telemetry* should be used. +* For any data where the data may need to be gathered at any point in the execution to help assess the state of the application component, + for example, core configuration, device information, *telemetry* should be used. + + Environment or Architecture-specific Sources -------------------------------------------- diff --git a/doc/guides/prog_guide/telemetry_lib.rst b/doc/guides/prog_guide/telemetry_lib.rst index 32f525a67f..71f8bd735e 100644 --- a/doc/guides/prog_guide/telemetry_lib.rst +++ b/doc/guides/prog_guide/telemetry_lib.rst @@ -1,6 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2020 Intel Corporation. +.. _telemetry_library: + Telemetry Library ================= diff --git a/doc/guides/prog_guide/trace_lib.rst b/doc/guides/prog_guide/trace_lib.rst index e5718feddc..a3b8a7c2eb 100644 --- a/doc/guides/prog_guide/trace_lib.rst +++ b/doc/guides/prog_guide/trace_lib.rst @@ -1,6 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(C) 2020 Marvell International Ltd. +.. _trace_library: + Trace Library =============