Re: [PATCH v7 2/3] log: separate logging functions out of EAL

[David Marchand <david.marchand@redhat.com>]

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.richardson@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