Some nits on the doc (that I can fix when applying if you are ok with them) :
On Mon, Jul 31, 2023 at 5:39 PM Bruce Richardson <bruce.richard...@intel.com> wrote: > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst > b/doc/guides/prog_guide/env_abstraction_layer.rst > index 93c8a031be..8033f6cebd 100644 > --- a/doc/guides/prog_guide/env_abstraction_layer.rst > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst > @@ -443,9 +443,7 @@ Per-lcore variables are implemented using *Thread Local > Storage* (TLS) to provid > Logs > ~~~~ > > -A logging API is provided by EAL. > -By default, in a Linux application, logs are sent to syslog and also to the > console. > -However, the log function can be overridden by the user to use a different > logging mechanism. > +While originally part of EAL, DPDK logging functionality is now provided by > the :ref:`Log_Library`. :doc:`log_lib` > > Trace and Debug Functions > ^^^^^^^^^^^^^^^^^^^^^^^^^ > diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst > index d89cd3edb6..ac91060992 100644 > --- a/doc/guides/prog_guide/index.rst > +++ b/doc/guides/prog_guide/index.rst > @@ -12,6 +12,7 @@ Programmer's Guide > overview > source_org > env_abstraction_layer > + log_lib > service_cores > trace_lib > rcu_lib > diff --git a/doc/guides/prog_guide/log_lib.rst > b/doc/guides/prog_guide/log_lib.rst > new file mode 100644 > index 0000000000..706ddcfef3 > --- /dev/null > +++ b/doc/guides/prog_guide/log_lib.rst > @@ -0,0 +1,115 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright(c) 2023 Intel Corporation. > + > +.. _log_library: Since we can directly point at this part of the documentation via :doc:`/path/to/log_lib`, no need for an anchor at the top of the file. > + > +Log Library > +============ nit: too long by one =. > + > +The DPDK Log library provides the logging functionality for other DPDK > libraries and drivers. > +By default, in a Linux application, logs are sent to syslog and also to the > console. > +On FreeBSD and Windows applications, logs are sent only to the console. > +However, the log function can be overridden by the user to use a different > logging mechanism. > + > +Log Levels > +----------- Idem. > + > +Log messages from apps and libraries are reported with a given level of > severity. > +These levels, specified in ``rte_log.h`` are (from most to least important): > + > +#. Emergency > +#. Alert > +#. Critical > +#. Error > +#. Warning > +#. Notice > +#. Information > +#. Debug > + > +At runtime, only messages of a configured level or above (i.e. of higher > importance) > +will be emitted by the application to the log output. > +That level can be configured either by the application calling the relevant > APIs from the logging library, > +or by the user passing the ``--log-level`` parameter to the EAL via the > application. > + > +Setting Global Log Level > +~~~~~~~~~~~~~~~~~~~~~~~~~ Idem. > + > +To adjust the global log level for an application, > +just pass a numeric level or a level name to the ``--log-level`` EAL > parameter. > +For example:: > + > + /path/to/app --log-level=error > + > + /path/to/app --log-level=debug > + > + /path/to/app --log-level=5 # warning > + > +Within an application, the log level can be similarly set using the > ``rte_log_set_global_level`` API. > + > +Setting Log Level for a Component > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Idem. > + > +In some cases, for example, for debugging purposes, > +it may be desirable to increase or decrease the log level for only a > specific component, or set of components. > +To facilitate this, the ``--log-level`` argument also accepts an, optionally > wildcarded, component name, > +along with the desired level for that component. > +For example:: > + > + /path/to/app --log-level=lib.eal:crit > + > + /path/to/app --log-level=lib.*:warning > + > +Within an application, the same result can be got using the > ``rte_log_set_level_pattern()`` or ``rte_log_set_level_regex()`` APIs. > + > +Using Logging APIs to Generate Log Messages > +-------------------------------------------- Idem. > + > +To output log messages, ``rte_log()`` API function should be used. > +As well as the log message, ``rte_log()`` takes two additional parameters: > + > +* The log level > +* The log component type > + -- David Marchand
