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

[Jerin Jacob]

On Tue, Jun 13, 2023 at 8:04 PM Bruce Richardson
<bruce.richardson at intel.com> 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 <bruce.richardson at intel.com>
> ---
>  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.
> +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 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.
> +* 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.
> +  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.
> +  * 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.


If you think it makes sense, the following point may be added for trace.
# Since trace is using CommonTraceFormat, it is possible to write
_reusable_ post-processing tools with
https://babeltrace.org/docs/v1.5/python/babeltrace/ like finding idle
CPU time etc.

Rest looks good to me.



> +
> +* 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.
> +
> +
>  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
>  =============
>
> --
> 2.39.2
>