On Tue, Jun 13, 2023 at 8:04 PM Bruce Richardson <bruce.richard...@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.richard...@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 >
