[v3,2/2] doc/contributing: guidelines for logging, tracing and telemetry

  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 <bruce.richardson@intel.com>
Acked-by: Morten Brørup <mb@smartsharesystems.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>
---
 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(+)
  

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 <bruce.richardson@intel.com>
> Acked-by: Morten Brørup <mb@smartsharesystems.com>
> Reviewed-by: David Marchand <david.marchand@redhat.com>
>

Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>

> ---
>  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<dynamic_logging>`
> +* :ref:`Tracing<trace_library>`
> +* :ref:`Telemetry<telemetry_library>`
> +
> +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 <https://diamon.org/ctf/>`_ 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_<libname>_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
>  =============
>
  

在 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 <bruce.richardson@intel.com>
> Acked-by: Morten Brørup <mb@smartsharesystems.com>
> Reviewed-by: David Marchand <david.marchand@redhat.com>
> ---
>   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<dynamic_logging>`
> +* :ref:`Tracing<trace_library>`
> +* :ref:`Telemetry<telemetry_library>`
> +
> +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 <https://diamon.org/ctf/>`_ 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_<libname>_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 <lihuisong@huawei.com>
> +
>   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
>   =============
>
  

On Wed, Jul 19, 2023 at 6:38 AM lihuisong (C) <lihuisong@huawei.com> wrote:
>
>
> 在 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 <bruce.richardson@intel.com>
> > Acked-by: Morten Brørup <mb@smartsharesystems.com>
> > Reviewed-by: David Marchand <david.marchand@redhat.com>

Acked-by: Jerin Jacob <jerinj@marvell.com>