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 E34C242EAC; Tue, 18 Jul 2023 22:23:55 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 77E8442D17; Tue, 18 Jul 2023 22:23:55 +0200 (CEST) Received: from NAM04-BN8-obe.outbound.protection.outlook.com (mail-bn8nam04on2043.outbound.protection.outlook.com [40.107.100.43]) by mails.dpdk.org (Postfix) with ESMTP id C0206410D3 for ; Tue, 18 Jul 2023 22:23:53 +0200 (CEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=WpudslGwZIGOYLoo8MeFDyhL0270vOQKXfhdKE2ezE04WLl6fbv03OzQz45U++hj4knsRmTwrTuw44XXcatQL/UFgXYOh0KhlWw5qr91Zsv3ncpoey3YXr1CFIMrG7URvM+ZglHo3Tg4IlpPPuotJMFx+YD9O8e6WIdYQNervT5wW1G3E8sIYTmO4Ou8sbovQVTOX7hrGxH1SYf1RqK6sUzbpybAUkCGY0yMYisxSWGpWaL0yUJLPbdIAed0Q9DFeXCDR9HVztiOUrKWyzuF2hf79M3YCtN1rPHNYXTub45Pzx8i4PV6jn8eo0VWoLioIyknUA+c45LJFjaJdS89Pw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=oWWrNsZNkAlZ4p6iKem7+tUAZsWU9Bdm8ao8e7mJshw=; b=iiVmHig5K8z41tH6jxAKVAV+BhqYsW9cwUhF+/U/2+D97pYpESL5W/qcRVXpr0CXEahN/kxVuUtc0hWe+epFfOoqRXAjSN1XdfHnhWm37kE0qnFX3c+hHwlcJqhZFoYhaUlvn74ChlWo9RcR+MfRghi//+jmuxcYqP3fA0W3c+fndV/0xRjeX3HCb1ue8/hpSmKRyQRZEFHmBgS5wPgg7GRDsMsNTicW1qMqD3S+3AxEPZwNjC/ioBG7u0jEp619QP48X8Iih/KbUNUQz9pLTTAB4Fk0lL7HZD8K7KZJY/9BCAks1L5lp1mt3pq2cw+fwFBmK0j+XEPm7UM0sTTiyw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=amd.com; dmarc=pass action=none header.from=amd.com; dkim=pass header.d=amd.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=oWWrNsZNkAlZ4p6iKem7+tUAZsWU9Bdm8ao8e7mJshw=; b=3rmNKKi1coloHiC2KAmMQnGoDRtkhlW2PFaJzDIH6X6XzS9dvLBjQWvrpKs6UQ4E+yNGaURbkjwnkEGxRbGR0zJZwie5qaQXqmc1RWu1+WHfAsYAECyUVzk0+B3zFB0kDFRpWOq5XYtkwjptOPvt7r3fuwWIz+ttRtJUYioDBks= Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=amd.com; Received: from CH2PR12MB4294.namprd12.prod.outlook.com (2603:10b6:610:a9::11) by SN7PR12MB6887.namprd12.prod.outlook.com (2603:10b6:806:261::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6588.28; Tue, 18 Jul 2023 20:23:51 +0000 Received: from CH2PR12MB4294.namprd12.prod.outlook.com ([fe80::15a9:4e83:4217:8b49]) by CH2PR12MB4294.namprd12.prod.outlook.com ([fe80::15a9:4e83:4217:8b49%7]) with mapi id 15.20.6588.031; Tue, 18 Jul 2023 20:23:51 +0000 Message-ID: Date: Tue, 18 Jul 2023 21:23:45 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.13.0 Subject: Re: [PATCH v3 2/2] doc/contributing: guidelines for logging, tracing and telemetry Content-Language: en-US To: Bruce Richardson , dev@dpdk.org Cc: david.marchand@redhat.com, =?UTF-8?Q?Morten_Br=c3=b8rup?= References: <20230613143355.77914-1-bruce.richardson@intel.com> <20230718164802.110560-1-bruce.richardson@intel.com> <20230718164802.110560-3-bruce.richardson@intel.com> From: Ferruh Yigit In-Reply-To: <20230718164802.110560-3-bruce.richardson@intel.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-ClientProxiedBy: LO4P123CA0090.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:190::23) To CH2PR12MB4294.namprd12.prod.outlook.com (2603:10b6:610:a9::11) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: CH2PR12MB4294:EE_|SN7PR12MB6887:EE_ X-MS-Office365-Filtering-Correlation-Id: 209d5402-351b-4f3a-2ae6-08db87cce620 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: FWvX1psd4CcnDQvo8vlQT2onN1P0BB4wSqECs8BQ8PzJZKTfxjY6z0hRyKfEIiEtQmJbB6GiBIVBheanRy2jTb2hOlHB+xMpaPw18rdD5zBnZRP1AumI/JhMnaVS0RSVHq92ZthEVoEnpCgfKHhSa09O0DmNYaIq8z0DEdBi2y+yZ2xbYI8k3mVFds32TZAZu+rNk7KN3JwFR9HHUTGPuXk5K2sul+72tCT0qwU02tiXKAuMbs/vGm8nWL1zUsGm/X8UDgDPE2S1nbbXgjYTUMPIJRbQdhc2zcXp1cAxAPTRQkyZ9WwlEHMZtsGaS9v+PeIKS8kqG8Uj3khx/kDsYhuXCjgHxg0WJpkA2YNremGUEA0IzdW80Hm+tT1TZE1W1+gazkVWPYJR1uYRZh7S/1d7mNbGTu8ZUV8EsAwjA+g6dv8OfqyjBEhnP2F3i+CLDf6puVQ+emZas7jKmvtWXodiJq9L931z9tjp309hy5nRyRz74+70Q+sjx7h+T8BP1IDLq/VIBYdnavJI5UgfmEqtK49uzRoDo6jheZlS3NhDIz7jDO0ABl2SiA0vp0Ma1BhTN08Kvxd5rHQZWDx1pCiMy10Q0Coi0G5xlGgC4l5u1Vg4x8w1TdtJXPKeZrNaTvQmTjuFIUHOcZLKcPpnMg== X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:CH2PR12MB4294.namprd12.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230028)(4636009)(376002)(39860400002)(346002)(136003)(366004)(396003)(451199021)(31686004)(478600001)(6486002)(6666004)(2616005)(31696002)(86362001)(66574015)(2906002)(186003)(83380400001)(6512007)(53546011)(6506007)(966005)(26005)(38100700002)(44832011)(66946007)(66556008)(316002)(8676002)(5660300002)(66476007)(41300700001)(4326008)(8936002)(36756003)(43740500002)(45980500001); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?N0lFbVI3dmlEd1RqRlB2RXR6TU5mUC83Skd6R3RyWEZneG1ISFhKRTcrSWpn?= =?utf-8?B?K000VkRqTEhzbG9vcXZSQXd3TzhvTDRra0VwQ3paT2tialRVT08yaC8xbkNE?= =?utf-8?B?R0lQOFFyWmtkWVhyRVh3ektGR2RGSldrVE81SVVhVE1qNUNxaFdoU2NuTC8x?= =?utf-8?B?MDVETHhtTXdEUkVJZU80RURsMGpZTkk5NTBpZFdlTC8vcklsTFNESGNCeWdZ?= =?utf-8?B?MTZjTlpobGtzQmJzM2Y5bkQ3dzViMWMxKzUwQU5DejFpNVFWZndwQXdiNEdm?= =?utf-8?B?NXJrb3VhWFJHWnZaZFBHYWt2ZHhXdE1Fc1BldzBqWkJkbEhxNzRoNVpJeDZK?= =?utf-8?B?UjQzd0dNZTYwRjc3dWg3Rmcrc211SFAzMEYwakQ2NzFKdEZGQ1FGUjBvR1Nl?= =?utf-8?B?dmIvempSM2oxQU8wUjA4ZUsrNWg3a1U5cm9qZk5DT0RuV2NKbTkxb1ZXUkJE?= =?utf-8?B?VnZMZkxnN1hoYnV5bW9WUHVDU2FnMmNKcDRaaE95MFF5V1F5RkVSa0FLbnBM?= =?utf-8?B?UVBsMEdrRC9IbUtyb2R3bHl1M1Rwa1V3T3pBeGJLdSt5bTczMEJXWGtjV1py?= =?utf-8?B?Vk9mYmd0RGlEcEtHeGw2TDVWaDJHSkt6VTBhWjZHRlc0eWYvZXVONjhkVSts?= =?utf-8?B?ejdTNFo4UnhTbTFEdVdaUjRrajBBandmNGFncTNXcmFWcEtuUk04dWlORjVo?= =?utf-8?B?M3R6VjJLRUY2c3JGQTh2ZG1QbG9xQ2QzbkR0WUdkRHBsZlQ5MFdFRE1zYlBD?= =?utf-8?B?NE9MRGhiUmpQVlozaWw3RG1paStPUnBRamY2eWV0Kzc4V0tRQ2hWMDdwMHpQ?= =?utf-8?B?MUVDNzQxaWpVNmdoYjMxNFNibmVkdjQ3dzdWaDdickd6WlhDWmc3bDJVc3JS?= =?utf-8?B?eUZ2ZVVVUkZJRXFtOU9mMHhTVlBSbFlNbk1MNGV6cllGejJIcGlHRitabldX?= =?utf-8?B?Y2Ztb25qUExBT1JiTEN1TGJ0d0dkZVd4cDhyZVB5WGJXaGxQbGVWTXprSjhv?= =?utf-8?B?UUlnLzUzeFplNDk1SEhsankwK1MxbGZqS25WdmRUTW1kLzlLQWxkSElCOW10?= =?utf-8?B?QzV2SnpqeHZ2djFCTmN4ZTQzVWprUEhiRXpMM0hEb3d0bENWcWE1UTdLU3N4?= =?utf-8?B?Q28wTDlNZWp2K1lGeVRndHJJQzJ2clI2dWwySmRpY2wvOENlUFFJWTBVaTlK?= =?utf-8?B?SWZxNkhMdTVlU0lmT2Nnc2g4QjVYRy9rQUovNlljYjF0aFFvUmlJRDV2V1RX?= =?utf-8?B?MS9QOCtiZWJ1Um1EamVJa2tPRHZLdU95TFlBSU9VVHVmUVR5NTQyVEdhRlRs?= =?utf-8?B?MFZmc1puLzRGbzQwQ1lGWkV6UzdPOG5lTGJRR1ErQkp0WHE5L3NYdm1VRm53?= =?utf-8?B?N0RSK3FxcmtrYm8xaU83aVBMUU15eDQxQUFRRkNmc1hFd1BWNW14MzcrMENh?= =?utf-8?B?c3RjOGVnSG9XWGRaZjVsM2VDdlBwR3ZITDJYMGY5cVFkS3NZbXFGMG5QODl6?= =?utf-8?B?YUZNSFZJUXBLdTlzVEI4NlZobDJlWXJnUG9HZEZTV3BVdVE5L0l3aFdYbFNC?= =?utf-8?B?dGljcUovcTlrTW1GMTJSNHFETnZUcGV4aDlCcHdUdDFTTnpGd1FMM3JLSzhC?= =?utf-8?B?SGN6ZkdmbFQwYzdKYlJ1aE1xUHQ5L2VWOWZTQkpKTzM4d3AzbXdpaHQ1VGly?= =?utf-8?B?SFJzWkxsK3E0WHBtM1liQ0tQakFMVUROYjV4SVAvaE05Q0ZjRUlMZXNKUjhR?= =?utf-8?B?OGZsQU1JdUcrb3l4bHFPQXQwZFJBWFBXVmRMQm84elFXck1zdUNDUk9VQTF0?= =?utf-8?B?WWhIY3B6OWM4eW1OdWxvZUtzajE0UExKamV3WkxKa29KUEtqWDFvWTJEVjJB?= =?utf-8?B?Y2hDUlB4RGtoRlBxWGlBZzdXeFlZNHc2UzNiT2VKMUd1N1ZrcTk4VVVGNEh3?= =?utf-8?B?NVdUTk82M2NYUWg5Q1hnYVlkRVYwS1pwQVpDOTBMWVArU3d2M2dRenNkWDJN?= =?utf-8?B?TnBsOUVpTTZSc1pxUDF2bDhLM2FzUWpmL3BITHE1N1RjS050L1lHRWNoaGU3?= =?utf-8?B?UWxPNWkrVG8rUlRjNkIrenl2WTRFS2ZITjBJa1o2RTJ0KzNhdkRrY2xTWUU3?= =?utf-8?Q?3UgJPDCniRCbfbIS0p/0cALlY?= X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-Network-Message-Id: 209d5402-351b-4f3a-2ae6-08db87cce620 X-MS-Exchange-CrossTenant-AuthSource: CH2PR12MB4294.namprd12.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 18 Jul 2023 20:23:51.0578 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: pPgzMkakDu13RnRRHv/qHC5+gjE5Sr7rwI0gyE/kraJyvyfom7L+J4fq2ZqHjvxH X-MS-Exchange-Transport-CrossTenantHeadersStamped: SN7PR12MB6887 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 On 7/18/2023 5:48 PM, Bruce Richardson wrote: > 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 > Acked-by: Ferruh Yigit > --- > doc/guides/contributing/coding_style.rst | 2 + > doc/guides/contributing/design.rst | 49 ++++++++++++++++++++++++ > doc/guides/prog_guide/telemetry_lib.rst | 2 + > doc/guides/prog_guide/trace_lib.rst | 2 + > 4 files changed, 55 insertions(+) > > diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst > index f41f88c632..2d8d9a1469 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..5a4c4b7ed1 100644 > --- a/doc/guides/contributing/design.rst > +++ b/doc/guides/contributing/design.rst > @@ -4,6 +4,7 @@ > Design > ====== > > + > Environment or Architecture-specific Sources > -------------------------------------------- > > @@ -68,6 +69,54 @@ Adding a new static field or flag must be an exception matching many criteria > like (non exhaustive): wide usage, performance, size. > > > +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 its 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 of 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. > + +1 to note, this is a good addition. > +* 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". > + +1 > +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. > + > + > Library Statistics > ------------------ > > 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 > ============= >