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 D69E542EAD; Wed, 19 Jul 2023 03:07:57 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id B0D6440EDF; Wed, 19 Jul 2023 03:07:57 +0200 (CEST) Received: from szxga01-in.huawei.com (szxga01-in.huawei.com [45.249.212.187]) by mails.dpdk.org (Postfix) with ESMTP id EBCD040ED8 for ; Wed, 19 Jul 2023 03:07:55 +0200 (CEST) Received: from kwepemm600004.china.huawei.com (unknown [172.30.72.53]) by szxga01-in.huawei.com (SkyGuard) with ESMTP id 4R5Hj945qczrRmG; Wed, 19 Jul 2023 09:07:09 +0800 (CST) Received: from [10.67.103.231] (10.67.103.231) by kwepemm600004.china.huawei.com (7.193.23.242) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.27; Wed, 19 Jul 2023 09:07:53 +0800 Message-ID: <83da59f6-537c-92b3-f145-c3471f7e3633@huawei.com> Date: Wed, 19 Jul 2023 09:07:52 +0800 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101 Thunderbird/91.2.0 Subject: Re: [PATCH v3 2/2] doc/contributing: guidelines for logging, tracing and telemetry To: Bruce Richardson , CC: , =?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: "lihuisong (C)" In-Reply-To: <20230718164802.110560-3-bruce.richardson@intel.com> Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: 8bit X-Originating-IP: [10.67.103.231] X-ClientProxiedBy: dggems701-chm.china.huawei.com (10.3.19.178) To kwepemm600004.china.huawei.com (7.193.23.242) X-CFilter-Loop: Reflected 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 在 2023/7/19 0:48, Bruce Richardson 写道: > 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 > --- > 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. > + > +* 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. > + +1 now more clear Acked-by: Huisong Li > + > 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 > ============= >