From patchwork Tue Jun 20 17:07:27 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 128871 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 1FAFC42D0A; Tue, 20 Jun 2023 19:08:02 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 76ACF42BFE; Tue, 20 Jun 2023 19:07:59 +0200 (CEST) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by mails.dpdk.org (Postfix) with ESMTP id 5855542BAC for ; Tue, 20 Jun 2023 19:07: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=1687280878; x=1718816878; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=bV8QoI2hEFFp0fRjFSulknvE0uE1KzAfCTCULJVcp94=; b=eKjnK6n4n4tFyoqbIheXAo2vQsK4y69cWAGLoUVHL8yz3iFUNpTQOVnR fHSWg+8+8qHotAfzuiM6+lKrc7sfQ7Z6N9w1BLXM3Gx5roffh/REC8ciV MGGvSUWshZ3PZRnOqVs6tIdp/+QpzZucjdjy1wCTgZBpS6dKLjuQw/ulL +siFYtrB17nyr/4iyVzW/HwT54ID+YQTmAN2O1D+X9IMOq4Gjllvphkko 9BCO+YKLkQT8mKn2oz7NjrjYTP6wv8JmNWadPI88QTaYP/LaBCgA0Ea9r nMfdL4+LEILdbcYdKkgxOLbAF43oOB/x5xT9tz+hd/+LfsO5kITW+GeVj w==; X-IronPort-AV: E=McAfee;i="6600,9927,10747"; a="425877779" X-IronPort-AV: E=Sophos;i="6.00,257,1681196400"; d="scan'208";a="425877779" Received: from orsmga006.jf.intel.com ([10.7.209.51]) by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 20 Jun 2023 10:07:44 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10747"; a="691507579" X-IronPort-AV: E=Sophos;i="6.00,257,1681196400"; d="scan'208";a="691507579" Received: from silpixa00401385.ir.intel.com ([10.237.214.165]) by orsmga006.jf.intel.com with ESMTP; 20 Jun 2023 10:07:42 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: stephen@networkplumber.org, mb@smartsharesystems.com, ferruh.yigit@amd.com, jerinjacobk@gmail.com, Bruce Richardson Subject: [PATCH v2 1/2] doc/contributing: provide coding details for dynamic logging Date: Tue, 20 Jun 2023 18:07:27 +0100 Message-Id: <20230620170728.74117-2-bruce.richardson@intel.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230620170728.74117-1-bruce.richardson@intel.com> References: <20230613143355.77914-1-bruce.richardson@intel.com> <20230620170728.74117-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 Acked-by: Chengwen Feng Reviewed-by: David Marchand --- 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 89db6260cf..307c7deb9a 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 20 17:07:28 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 128872 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 793AC42D0A; Tue, 20 Jun 2023 19:08:08 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 907FC42BDA; Tue, 20 Jun 2023 19:08:02 +0200 (CEST) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by mails.dpdk.org (Postfix) with ESMTP id 4DD3642BAC for ; Tue, 20 Jun 2023 19:07:59 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1687280879; x=1718816879; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=EkQHT64sFYdo7uDDEEt9AjuGzpBavJ9Y3OZPfa+pwGg=; b=gl1RzBJW3lJ4VlCIVYr5tVcHCUanN34O9V17kwP67TpzzbZm5JrcU1Az FcsO8Olti9jocSmOhBzOigYmvgVaqvZjb1s6qbz0hv/nHJsxiG6AJwllX 5QMbpEr2ak94wnnAffNp5v7t425GML5LlUdOvL0Oev5kb/ueOLHJVhLzw FINqJXLteyxrMUCAmXl++Y6O5agLsEQPvt4wnaNTdNFEHBKLfRlDCK4mB S9K5HiSMfQ4KunLjmVA7HAcL28UPx1rjoYc0/ZJqVtRExGPpaiUb+O1Jn etY5tIkd/GysMM/zSBQTK/tpb82L3oFeOCvo/uOmwn5FCxCn+nEqXuGwF Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10747"; a="425877796" X-IronPort-AV: E=Sophos;i="6.00,257,1681196400"; d="scan'208";a="425877796" Received: from orsmga006.jf.intel.com ([10.7.209.51]) by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 20 Jun 2023 10:07:48 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10747"; a="691507615" X-IronPort-AV: E=Sophos;i="6.00,257,1681196400"; d="scan'208";a="691507615" Received: from silpixa00401385.ir.intel.com ([10.237.214.165]) by orsmga006.jf.intel.com with ESMTP; 20 Jun 2023 10:07:45 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: stephen@networkplumber.org, mb@smartsharesystems.com, ferruh.yigit@amd.com, jerinjacobk@gmail.com, Bruce Richardson Subject: [PATCH v2 2/2] doc/contributing: guidelines for logging, tracing and telemetry Date: Tue, 20 Jun 2023 18:07:28 +0100 Message-Id: <20230620170728.74117-3-bruce.richardson@intel.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230620170728.74117-1-bruce.richardson@intel.com> References: <20230613143355.77914-1-bruce.richardson@intel.com> <20230620170728.74117-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], our 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 Reviewed-by: David Marchand --- V2: * Added note about not logging from unused drivers * Reworked bullets/sub-bullets on tracing vs debug logs for debugging. - Consensus in replies was that people liked having debug logs for single-use, e.g. init cases. - Kept recommendation for tracing for data-path only * Added short discussion of *_dump() functions at end of section * Added sentence to indicate that telemetry should be read-only * Added mention of common trace format and that other tools are available for it. --- doc/guides/contributing/coding_style.rst | 2 + doc/guides/contributing/design.rst | 47 ++++++++++++++++++++++++ doc/guides/prog_guide/telemetry_lib.rst | 2 + doc/guides/prog_guide/trace_lib.rst | 2 + 4 files changed, 53 insertions(+) diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index 307c7deb9a..0861305dc6 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..30104e0bfb 100644 --- a/doc/guides/contributing/design.rst +++ b/doc/guides/contributing/design.rst @@ -4,6 +4,53 @@ 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. + +.. note:: + + Drivers off all classes, including both bus and device drivers, + should not output any log information if the hardware they support is not present. + This is to avoid any changes in output for existing users when a new driver is added to DPDK. + +* For component initialization, or other cases where a path through the code is only likely to be taken once, + either *logging* at ``DEBUG`` level or *tracing* may be used, or potentially both. + In the latter case, tracing can provide basic information as to the code path taken, + with debug-level logging providing additional details on internal state, + not possible to emit via tracing. + +* For a component's data-path, where a path is to be taken multiple times within a short timeframe, + *tracing* should be used. + Since DPDK tracing uses `Common Trace Format `_ for its tracing logs, + post-analysis can be done using a range of external tools. + +* 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. + Telemetry callbacks should not modify any program state, but be "read-only". + +Many libraries also include a ``rte__dump()`` function as part of their API, +writing verbose internal details to a given file-handle. +New libraries are encouraged to provide such functions where it makes sense to do so, +as they provide an additional application-controlled mechanism to get details of the internals of a DPDK component. + 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 =============