patches for DPDK stable branches
 help / color / mirror / Atom feed
* [PATCH] doc: enhance the global log level documentation
@ 2024-06-26 15:09 David Marchand
  2024-06-26 17:10 ` Ilya Maximets
  0 siblings, 1 reply; 3+ messages in thread
From: David Marchand @ 2024-06-26 15:09 UTC (permalink / raw)
  To: dev; +Cc: Ilya Maximets, stable, Anoob Joseph

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


^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH] doc: enhance the global log level documentation
  2024-06-26 15:09 [PATCH] doc: enhance the global log level documentation David Marchand
@ 2024-06-26 17:10 ` Ilya Maximets
  2024-10-09 18:50   ` Stephen Hemminger
  0 siblings, 1 reply; 3+ messages in thread
From: Ilya Maximets @ 2024-06-26 17:10 UTC (permalink / raw)
  To: David Marchand, dev; +Cc: i.maximets, stable, Anoob Joseph

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.

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH] doc: enhance the global log level documentation
  2024-06-26 17:10 ` Ilya Maximets
@ 2024-10-09 18:50   ` Stephen Hemminger
  0 siblings, 0 replies; 3+ messages in thread
From: Stephen Hemminger @ 2024-10-09 18:50 UTC (permalink / raw)
  To: Ilya Maximets; +Cc: David Marchand, dev, stable, Anoob Joseph

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


^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2024-10-09 18:50 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-06-26 15:09 [PATCH] doc: enhance the global log level documentation David Marchand
2024-06-26 17:10 ` Ilya Maximets
2024-10-09 18:50   ` Stephen Hemminger

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).