[v3,0/2] Improve docs on getting info on running process

  Add details to our documentation on how to register logging for a
component. Also provide guidelines on when to use logs vs tracing
vs telemetry.

V3: Moved new doc section on runtime info, and other minor changes flagged
    by David on review.

V2: extended second patch based on the feedback provided.
    Hopefully, we can keep this section short and clear as the
    revisions roll! :-)

Bruce Richardson (2):
  doc/contributing: provide coding details for dynamic logging
  doc/contributing: guidelines for logging, tracing and telemetry

 doc/guides/contributing/coding_style.rst | 18 +++++++++
 doc/guides/contributing/design.rst       | 49 ++++++++++++++++++++++++
 doc/guides/prog_guide/telemetry_lib.rst  |  2 +
 doc/guides/prog_guide/trace_lib.rst      |  2 +
 lib/cfgfile/rte_cfgfile.c                |  2 +
 5 files changed, 73 insertions(+)

--
2.39.2
  

On Tue, 18 Jul 2023 17:48:00 +0100
Bruce Richardson <bruce.richardson@intel.com> wrote:

> Add details to our documentation on how to register logging for a
> component. Also provide guidelines on when to use logs vs tracing
> vs telemetry.
> 
> V3: Moved new doc section on runtime info, and other minor changes flagged
>     by David on review.
> 
> V2: extended second patch based on the feedback provided.
>     Hopefully, we can keep this section short and clear as the
>     revisions roll! :-)
> 
> Bruce Richardson (2):
>   doc/contributing: provide coding details for dynamic logging
>   doc/contributing: guidelines for logging, tracing and telemetry
> 
>  doc/guides/contributing/coding_style.rst | 18 +++++++++
>  doc/guides/contributing/design.rst       | 49 ++++++++++++++++++++++++
>  doc/guides/prog_guide/telemetry_lib.rst  |  2 +
>  doc/guides/prog_guide/trace_lib.rst      |  2 +
>  lib/cfgfile/rte_cfgfile.c                |  2 +
>  5 files changed, 73 insertions(+)
> 
> --
> 2.39.2
> 

Should we add explicit statements about:
  - Static logtypes (especially LOGTYPE_PMD) should not be used.
  - New static logtypes must not be added.
  

On Tue, Jul 18, 2023 at 10:40:20AM -0700, Stephen Hemminger wrote:
> On Tue, 18 Jul 2023 17:48:00 +0100
> Bruce Richardson <bruce.richardson@intel.com> wrote:
> 
> > Add details to our documentation on how to register logging for a
> > component. Also provide guidelines on when to use logs vs tracing
> > vs telemetry.
> > 
> > V3: Moved new doc section on runtime info, and other minor changes flagged
> >     by David on review.
> > 
> > V2: extended second patch based on the feedback provided.
> >     Hopefully, we can keep this section short and clear as the
> >     revisions roll! :-)
> > 
> > Bruce Richardson (2):
> >   doc/contributing: provide coding details for dynamic logging
> >   doc/contributing: guidelines for logging, tracing and telemetry
> > 
> >  doc/guides/contributing/coding_style.rst | 18 +++++++++
> >  doc/guides/contributing/design.rst       | 49 ++++++++++++++++++++++++
> >  doc/guides/prog_guide/telemetry_lib.rst  |  2 +
> >  doc/guides/prog_guide/trace_lib.rst      |  2 +
> >  lib/cfgfile/rte_cfgfile.c                |  2 +
> >  5 files changed, 73 insertions(+)
> > 
> > --
> > 2.39.2
> > 
> 
> Should we add explicit statements about:
>   - Static logtypes (especially LOGTYPE_PMD) should not be used.
>   - New static logtypes must not be added.

I would hope that should not be necessary especially since this section
talks about dynamic logging only. However, no harm in adding a
one-line note about it. I'll see if I can get a few minutes to spin a V4
with an extra note, but if not I think this set is good to go as-is.

/Bruce
  

On Tue, Jul 18, 2023 at 10:40:20AM -0700, Stephen Hemminger wrote:
> On Tue, 18 Jul 2023 17:48:00 +0100
> Bruce Richardson <bruce.richardson@intel.com> wrote:
> 
> > Add details to our documentation on how to register logging for a
> > component. Also provide guidelines on when to use logs vs tracing
> > vs telemetry.
> > 
> > V3: Moved new doc section on runtime info, and other minor changes flagged
> >     by David on review.
> > 
> > V2: extended second patch based on the feedback provided.
> >     Hopefully, we can keep this section short and clear as the
> >     revisions roll! :-)
> > 
> > Bruce Richardson (2):
> >   doc/contributing: provide coding details for dynamic logging
> >   doc/contributing: guidelines for logging, tracing and telemetry
> > 
> >  doc/guides/contributing/coding_style.rst | 18 +++++++++
> >  doc/guides/contributing/design.rst       | 49 ++++++++++++++++++++++++
> >  doc/guides/prog_guide/telemetry_lib.rst  |  2 +
> >  doc/guides/prog_guide/trace_lib.rst      |  2 +
> >  lib/cfgfile/rte_cfgfile.c                |  2 +
> >  5 files changed, 73 insertions(+)
> > 
> > --
> > 2.39.2
> > 
> 
> Should we add explicit statements about:
>   - Static logtypes (especially LOGTYPE_PMD) should not be used.
>   - New static logtypes must not be added.

How about:

+.. note::
+
+   The statically-defined log types defined in ``rte_log.h`` are for legacy components,
+   and they will likely be removed in a future release.
+   Do not add new entries to this file.
+

Any suggested rewording before I spin a new patch?

/Bruce