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 93FEE42CB9; Wed, 14 Jun 2023 13:36:01 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 6CC9A40E0F; Wed, 14 Jun 2023 13:36:01 +0200 (CEST) Received: from NAM10-MW2-obe.outbound.protection.outlook.com (mail-mw2nam10on2049.outbound.protection.outlook.com [40.107.94.49]) by mails.dpdk.org (Postfix) with ESMTP id 1B53940DDB for ; Wed, 14 Jun 2023 13:35:59 +0200 (CEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=nTM3iIfSjq8iDqB5VH0CxTdNUW0NslPzBxBm6KDnrCA28E9eE+wRWt2AlqcjCWEBS1UzafOwjCSx+vycUIkPmzl9p/hXYiq+mlFijtW4c40GgFyqp+jDgX6H2MK22lh6s/Dbl78oCIzA0dibcV2phRkFSF7sql+4e+jUoEg26mG0BNp1ub0HIxpNBEb1naDdf4de7RrB2f8nvz+R0fu/dG8UfBVd7R3oJ4WZB1nqlUw2KB7r6qy1m1GkS+slwsCsLMNopbakkyIvb49BXPryOkM+uPzQJ2qNRroOtL8J5LKrI8lQbIchGO8aQ9yrbrpeXfGy3lSNwcRnp028U4X4Ng== 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=0GvSom1/FEK2Yso6p6YTow71Fg44DRT+Bv7pTgTwbjo=; b=k7fNKgoYY25xhpRQ/G/3NvjDWyk47EKfnA37evr64IFz4+LrSGLY+FJALatSDb8HEyUjw0FHTkUcsffcECivv7N0WYoI/1Jnlb5bpHMpb+2v7jF30xGlV1UlUoOAb2CB1J5NkFva5awYgL+8lbo/6/iU4cbwfo66VTOMQfP0gj1TqcNU3b8f3rWSB8zfFGe/ieoJB/GeRErPgdN04ZxxcqEMiYyPjSjBDFY/S8iXVBVYfdNk96/kRvO0WlmEkuou3r1dGzj2ch0VsutyUnuA0ivSTbdN6wGVv9KSBOgtSZE23nfjZcx6znivLoxYInfvXRMAWgQDWs1Dq1ubz12nSg== 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=0GvSom1/FEK2Yso6p6YTow71Fg44DRT+Bv7pTgTwbjo=; b=wQKqvtBzgopUowYz9/YWEkM9Xs+WiHkX8u1f9sKRv0d5zXRB8uZM47K1rHW5NfptJHM6v8+LlnfVKwVdRISGPsUcPHzK9xFUXWpDiyh7+7hQsUmFBKcQ9ySCLwC0OMn32C8zeCYPu9DkwbcAR3Vq4hxQHISoO6LfrejhxS6fv1Q= 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 PH8PR12MB7111.namprd12.prod.outlook.com (2603:10b6:510:22d::8) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6455.44; Wed, 14 Jun 2023 11:35:56 +0000 Received: from CH2PR12MB4294.namprd12.prod.outlook.com ([fe80::16e3:326c:5c2a:be42]) by CH2PR12MB4294.namprd12.prod.outlook.com ([fe80::16e3:326c:5c2a:be42%3]) with mapi id 15.20.6477.037; Wed, 14 Jun 2023 11:35:56 +0000 Message-ID: <5f70df87-72c6-7504-5972-0ac042a4142a@amd.com> Date: Wed, 14 Jun 2023 12:35:51 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.12.0 Content-Language: en-US To: Bruce Richardson , dev@dpdk.org References: <20230613143355.77914-1-bruce.richardson@intel.com> <20230613143355.77914-3-bruce.richardson@intel.com> From: Ferruh Yigit Subject: Re: [PATCH 2/2] doc/contributing: guidelines for logging, tracing and telemetry In-Reply-To: <20230613143355.77914-3-bruce.richardson@intel.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-ClientProxiedBy: LO2P265CA0384.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:a3::36) To CH2PR12MB4294.namprd12.prod.outlook.com (2603:10b6:610:a9::11) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: CH2PR12MB4294:EE_|PH8PR12MB7111:EE_ X-MS-Office365-Filtering-Correlation-Id: f28bfc76-980b-477c-7f6c-08db6ccb846f X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: vrlJlESQIflmOF46ZLCgtTSOkVROkFSpp06orPugXwN5hZtdoLL9mOfsx/pChjAgh5TSBThwv4CdkiMSwNIFBVX8iyVRS1NFvJIiL/MgmQm509djilnQmxA1fbR1yDalgvkBOYucvFQYRGLtkuHEn3h6V1mfHQ8RI/mDXx4kGz914BfJTSbUfyWQhU6LfFsQkFKIFqvKdijXW3PrupTTzLf/khibxj9eSWTqwtWp2OZKwkAUOVqCnv4uzrqMDxOOdkuxI0MqyoUAFlS8aZybOReLms8VK4I9X53PKA2YpFpmXTysUZBPYS50THzWe80bBQ96M1YIiGr+6o9bK/ILjxD78ARjfnXokCAF2hh7q32ET0kxx94Wi/3yXdiDVBjp7jxWx77GkytCXptSwXa5yxyzWlcXc2ZJqAejQ19Kxc8QWYpRsNvcz3B9wvbusfKyVVebcag/LmM7Zv5rwV0viQux2AkecZj7NS1t2ftT8gqQa81H7EutlEEiZjgL+M1wbLT8R3qEDw+Y5cwGKVFC1njupnNyLMgyM7ZnqIPJeily5LdXgRCWo3ES1oRC5fxWR/L9qcLUKHND8UEXihvsJPbKhhnmnfEkMOi4Rm9+SbTWpj4gvwsRI1CeRmXHns0LWy/CRvoWaWPcUEbho5E+9g== 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)(366004)(39860400002)(136003)(376002)(396003)(346002)(451199021)(2616005)(83380400001)(31696002)(38100700002)(36756003)(86362001)(478600001)(31686004)(44832011)(966005)(6666004)(6486002)(2906002)(8936002)(8676002)(5660300002)(66946007)(66476007)(66556008)(316002)(53546011)(186003)(6512007)(6506007)(41300700001)(26005)(43740500002)(45980500001); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?cmp0VUlyMXdoTjlzeTJWK1J0K3o1Sno2cm1saEQxejE4bEQ1RExHb2l4RkpF?= =?utf-8?B?ekhoU0tlbGdHYnMrODNmYi9aNzhwZVZCUUF2SUN3aldpbEYzb0w5a1R2eTJl?= =?utf-8?B?Yk02Ly8rcUwycXMvb3k2NHpRTk1SSjhHWU1NcUtNWFJST2c4bTd4a1NUeFB1?= =?utf-8?B?MHpINis5QkQxc3dsNTFSTjBENTZDcU9DZkRjaHh0Y1A2S3NzVEVVc1FJdmpC?= =?utf-8?B?T0cxeTBoTy8zOHFPbjRTRUFHZ0h5OFd0eCtMVnE3MEJnVGU3eDZUcFE3QWJl?= =?utf-8?B?MDVHUnFEcjlhZHdnT3p5VTMvRDR1SGZFUmxtV2t0TFdBSHVRbWk5ZzRBc1hp?= =?utf-8?B?MDQwUlorUWtKYnpjR3d3aWUrS1VtTXNOUjhoZDRkV1lEdTlQK3dJWHo2Rmd3?= =?utf-8?B?MzRnOWIzNUF5SXJaNWVyZHE3Mlk1L2Y4bDlhNjhwcjdHQ2NQQ2c0ekVBTFdq?= =?utf-8?B?dzA2eFp4cUhOMEZsNlpEMGNPbWdyTkt1T1B1dVFkb2owMWtNZEhyN0YwTngz?= =?utf-8?B?REV3OUNDNXhOMmhBUGUyZ0VXRncyQ3NzMkxJUEZaRmFpQ3g1OGNWYmJQTXZh?= =?utf-8?B?Z2NKL1pXU0VxSWVKOCtESjc4bkE4QnhXZjYwdFNLM3FZTkNYYkpVazJLTE9V?= =?utf-8?B?NmYyQjkzMno0SkZxeUo5WjV6aWFGYWZLTE9ISVRiOUsyQmRzamJkR1NRbHM4?= =?utf-8?B?MDNaNzhLQ0JPV0xIYUdkYkpsQisrNXRndjJjR2pUNm5FUWcyYnFaaWJ5RU80?= =?utf-8?B?a2ZXdTBXSktqT09QajdLZElOejhtTTM5cjBXT3BNRnBXZVNpOHZXaXNlQnRi?= =?utf-8?B?TWFzMy81NGlqWENiWVhqb1RpbFdoQmNqNUx5d0twbWphVUVLMzRORDBid0hX?= =?utf-8?B?bmJqQjBCOG85a1pYU1V4Nms5ZkhLK2pvLyttdXU4bXNvaVdxVitaRlRtc2Q2?= =?utf-8?B?WlVOcnpIZktSMVRSMVNndGJKb1RSNE1XWEJ1VWdZUlo4Wk5YOGlUNzgzUHdo?= =?utf-8?B?SjNkSHkrem9BTm5QNWxvbjVoTzYxdlVQM2Vyc2w2TmdaczB5TmxLdlpsbzVF?= =?utf-8?B?MDl1SWpxMTUyNW5Dcm5VZEpNUXN5dG9GVnFxTkRBaVo0MlhVVUhwaSttV1U3?= =?utf-8?B?MnJwRklwazgwR0FrL3dUMEptd2hSVzMrRGFxV2tKTGNGajZsZkd3V3U3ellX?= =?utf-8?B?eUh3dUJpeEwxbXFxaDJKazJGMWEwQzFoYWROa2w4cVBtTGtLYlIyUGdTYzJG?= =?utf-8?B?a3RQOHZ6TVRWZHYrVWVoTDF2cnJ2R2RLSVhhSjRGeXY4cStjRDJXYm95SjVF?= =?utf-8?B?SVIxMjF4VGhwQy9TczdmTFVwa0RtbGFKSmczV2Q5Y0pyRUVIN3NFNTBBU3Rx?= =?utf-8?B?M2srdEVuTzA1TVVqUmVXeTVOalN1ME1YOGU0MFdENGszSzJkazlkSk43dFl6?= =?utf-8?B?c0tZY3RnbTJOdGdLQnl6WVlTeHhSd2E4dGszbUt2clZMT2NCZnZvR2tkUjZh?= =?utf-8?B?eEtwVk5XNkVaZEo1cDVLem4wVnQwTm13TkdNME1vUENOY1FENDlHcEtkWm5D?= =?utf-8?B?OTY1L3BXMjBrdXR2SHVTbjlIRndIS203bGFTRm01YmNxNmtuTTNHdkFPbEpt?= =?utf-8?B?ampCWjBuVnRXY3hWWGZEd3Z2aEhMUzUzK2xRSnF1bkt1d0d2RXlSNTFYL0Fw?= =?utf-8?B?WjF4TDNLYk85Y3lCOWkvcHBCc2NEb0FyeGtXanlzbmRNbm9HZVpVUEZtYy91?= =?utf-8?B?QTVXcklzMzkzTGw1VzFhR0dlL1VvU3JScStBekVKZHdIM21KYVJ6NzRyLzUr?= =?utf-8?B?dzJYNDc3ZitHbkVlaHRwRjlQcDNZUS9UTUtFd2M0SFFlam1CaFY3bDhrNEJV?= =?utf-8?B?Z01hVXVXaEVTSW5PekhZWk44QWZwY2d0UzU1Y2Vxc01nbjNvMXNmNjJ3OElQ?= =?utf-8?B?NTcvSVBCZHVOanJCQUp0a2dycHJSN0V0WmJCR2c0cFdUNHpJQk5yRVB3dHdv?= =?utf-8?B?NDk2SEhjWXI2KyszQ1RMM3d4OHJuSEVKKzlsTFpwOTBPenBZT01LclJNSDJh?= =?utf-8?B?YlI0RkdpTkE3QW1rR2xxcUpJcnd4MVlJcmV2SkJla0hnUEkxQWVZM1FrdGg0?= =?utf-8?Q?SBqPcJYmXaDdGlb5KqPv3Tb5P?= X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-Network-Message-Id: f28bfc76-980b-477c-7f6c-08db6ccb846f X-MS-Exchange-CrossTenant-AuthSource: CH2PR12MB4294.namprd12.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 14 Jun 2023 11:35:56.0794 (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: 8uHoFSRTvfdy9It/mkQ8qoF56IQCcXk/ujHrwMJ4wQ1nNB2+hnmd0jFJAhYNdFnS X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH8PR12MB7111 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 6/13/2023 3:33 PM, Bruce Richardson wrote: > 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 > --- > 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. > I think target audience matters, who is consumer of the runtime information, possible candidates I can think of: - dev-ops engineer deploys and maintains a dpdk application - DPDK based application developer - DPDK developer Should we distinguish them? Like I guess telemetry output can be more useful to dev-ops engineer, but debug output can be more useful to application developer. To roughly set target consumer for each method may help developer to decide which one to use, but not sure if we can narrow it like this. > +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. +1 > +* 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. I think DEBUG logging is still useful for control path, 'tracing' is missing the custom message, so I found it more useful for to analyze order and frequency of a function call, which suits more to datapath. > + 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.> I am for preferring 'logging' for this case, because there is extra effort required to analyze the trace output, but logs are simple and just there. > + * 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. > + > +1 to use tracing mainly for datapath Also there is logging support for datapath, it would be nice to clarify that usage too. Datapath logging used: a) RTE_LOG_DP macros where code compiled out based on selected log level b) 'RTE_ETHDEV_DEBUG_RX' & 'RTE_ETHDEV_DEBUG_TX' macros ethdev layer use b for logging, drivers use combination of a & b Tracing helps on datapath to get profiling etc, but there are cases driver needs to log some variables, like descriptor details to ensure *functionality* is correct. I suggest to remove/deprecate RTE_LOG_DP [1], and use 'RTE_ETHDEV_DEBUG_x' macros for developer logging, and use tracing for profiling. What do you think? [1] Intention is good with RTE_LOG_DP macro to set the desired log level and compile out not used logs so that they won't take extra cycle. But every time log level changed, it requires compiling again anyway, and in practice there is no multiple level logging need for datapath, most of the time single macro to enable/disable logging is sufficient. That why I believe simpler to use an explicit macro to enable/disable datapath logging, like 'RTE_ETHDEV_DEBUG_RX' & 'RTE_ETHDEV_DEBUG_TX'. > +* For numerical or statistical data generated by a component, for example, per-packet statistics, > + *telemetry* should be used. > +1 > +* 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. > + +1 Should we explicitly state that telemetry only used as readonly? I think it implicitly states, but since there was a patch in the past, I wonder if this needs to be highlighted?