[PATCH] doc: enhance the global log level documentation

[PATCH] doc: enhance the global log level documentation

[David Marchand]

The current documentation is non intuitive in that the global log level
can be understood as being a single knob controlling all components
logs.
On the contrary, all the global log level is for is to reduce verbosity
globally.

Remove examples of setting --log-level=8|debug, which is a noop.

Cc: stable@dpdk.org

Signed-off-by: David Marchand <david.marchand@redhat.com>
---
 doc/guides/cryptodevs/octeontx.rst |  2 +-
 doc/guides/prog_guide/log_lib.rst  | 10 ++++++----
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/guides/cryptodevs/octeontx.rst b/doc/guides/cryptodevs/octeontx.rst
index a39f3f3d02..97e13514f3 100644
--- a/doc/guides/cryptodevs/octeontx.rst
+++ b/doc/guides/cryptodevs/octeontx.rst
@@ -114,7 +114,7 @@ OCTEON TX crypto PMD.
 
 .. code-block:: console
 
-        ./build/ipsec-secgw --log-level=8 -c 0xff -- -P -p 0x3 -u 0x2 --config
+        ./build/ipsec-secgw -c 0xff -- -P -p 0x3 -u 0x2 --config
         "(1,0,0),(0,0,0)" -f ep1.cfg
 
 Testing
diff --git a/doc/guides/prog_guide/log_lib.rst b/doc/guides/prog_guide/log_lib.rst
index ff9d1b54a2..965b7e9961 100644
--- a/doc/guides/prog_guide/log_lib.rst
+++ b/doc/guides/prog_guide/log_lib.rst
@@ -32,18 +32,20 @@ or by the user passing the ``--log-level`` parameter to the EAL via the applicat
 Setting Global Log Level
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-To adjust the global log level for an application,
-just pass a numeric level or a level name to the ``--log-level`` EAL parameter.
+By default, the global log level is set to ``RTE_LOG_DEBUG``.
+
+To reduce the verbosity of an application globally,
+adjust the global log level by passing 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.
 
+For setting per component log levels, see below.
+
 Setting Log Level for a Component
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.45.2

Re: [PATCH] doc: enhance the global log level documentation

[Ilya Maximets]

On 6/26/24 17:09, David Marchand wrote:
> The current documentation is non intuitive in that the global log level
> can be understood as being a single knob controlling all components
> logs.
> On the contrary, all the global log level is for is to reduce verbosity
> globally.
> 
> Remove examples of setting --log-level=8|debug, which is a noop.
> 
> Cc: stable@dpdk.org
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>
> ---
>  doc/guides/cryptodevs/octeontx.rst |  2 +-
>  doc/guides/prog_guide/log_lib.rst  | 10 ++++++----
>  2 files changed, 7 insertions(+), 5 deletions(-)

Thanks, David!  Though I still find this part of the documentation
extremely confusing.

> 
> diff --git a/doc/guides/cryptodevs/octeontx.rst b/doc/guides/cryptodevs/octeontx.rst
> index a39f3f3d02..97e13514f3 100644
> --- a/doc/guides/cryptodevs/octeontx.rst
> +++ b/doc/guides/cryptodevs/octeontx.rst
> @@ -114,7 +114,7 @@ OCTEON TX crypto PMD.
>  
>  .. code-block:: console
>  
> -        ./build/ipsec-secgw --log-level=8 -c 0xff -- -P -p 0x3 -u 0x2 --config
> +        ./build/ipsec-secgw -c 0xff -- -P -p 0x3 -u 0x2 --config
>          "(1,0,0),(0,0,0)" -f ep1.cfg
>  
>  Testing
> diff --git a/doc/guides/prog_guide/log_lib.rst b/doc/guides/prog_guide/log_lib.rst
> index ff9d1b54a2..965b7e9961 100644
> --- a/doc/guides/prog_guide/log_lib.rst
> +++ b/doc/guides/prog_guide/log_lib.rst
> @@ -32,18 +32,20 @@ or by the user passing the ``--log-level`` parameter to the EAL via the applicat
>  Setting Global Log Level
>  ~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -To adjust the global log level for an application,
> -just pass a numeric level or a level name to the ``--log-level`` EAL parameter.
> +By default, the global log level is set to ``RTE_LOG_DEBUG``.

This reads as I'll see debug logs from every component unless
I turn them off.  Which is not true.  The main issue is that
this doc doesn't define what 'global log level' means.

> +
> +To reduce the verbosity of an application globally,
> +adjust the global log level by passing 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.
>  
> +For setting per component log levels, see below.
> +
>  Setting Log Level for a Component
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  

I'd suggest to remove the 'Setting Global Log Level' section entirely.
Rename the 'Setting Log Level for a Component' into 'Setting Log Levels'
and restructure it in a way:

To set the log level for a particular component, use:
   --log-level=component:level <...>
For example, to see warnings and higher errors from <...> use <...>.

To set the log level for multiple components with wildcard match, use:
   --log-level=my_compon*:level <...>

For example, to see warnings and higher errors from all PMDs use <...>.
To see all the messages including debug logs from all PMDs use <...>

To set the desired log level for everything at once, use:
   --log-level=*:level

Also, the following syntax can be used to *decrease* log level globally:
   --log-level=level  # works only for decreasing current verbosity

What do you think?

(Some wording may need changes obviously.  For example, the doc says
the more critical levels are 'above' because they have 'higher importance',
but numbers are going the opposite direction.  So words like 'reduce' or
'increase' are hard to interpret in this context.)

Best regards, Ilya Maximets.

Re: [PATCH] doc: enhance the global log level documentation

[Stephen Hemminger]

On Wed, 26 Jun 2024 19:10:48 +0200
Ilya Maximets <i.maximets@ovn.org> wrote:

> On 6/26/24 17:09, David Marchand wrote:
> > The current documentation is non intuitive in that the global log level
> > can be understood as being a single knob controlling all components
> > logs.
> > On the contrary, all the global log level is for is to reduce verbosity
> > globally.
> > 
> > Remove examples of setting --log-level=8|debug, which is a noop.
> > 
> > Cc: stable@dpdk.org
> > 
> > Signed-off-by: David Marchand <david.marchand@redhat.com>
> > ---

Yes, the global log level pre-dates the introduction of component logs.

The wording would be better if it was more precise.

Something like:

By default, all log messages enabled by a particular component are visible.
But this may be too verbose. For example, to suppress all logs below warning level:
      
	/path/to-app --log-level=warning