log: add topic loggers and a default topic

pw_log_log/logv now go through the topic-based logger using the
"default" topic. Log topics themselves can be allocated by the call
sites. The simplest way to use a topic from e.g. a module:

    PW_LOG_TOPIC_STATIC(mod_topic, "mod.foo");
    #define PW_LOG_TOPIC_DEFAULT mod_topic
    ...
    void pipewire__module_init() {
  	  PW_LOG_TOPIC_INIT(mod_topic);
  	  ...
    }

With the #define all pw_log_foo() are now routed through the custom
topic. For the cases where the log topic must be specified, a
pw_logt_foo() set of macros is available.

Log topics are enabled through the PIPEWIRE_DEBUG environment variable
which now supports globs, e.g. PIPEWIRE_DEBUG="*:I;mod.access:D"
to enable global INFO but DEBUG for the access module.

Namespaces documented are "pw", "mod" and "conn", for pipewire-internal
stuff, modules and connection dumping. The latter is special-cased to
avoid spamming the log files, it requires an expcit "conn.<glob>"
pattern to enable.

The "default" topic always exists and is the fallback for any
pw_log_foo() invocation that does not use a topic.
This commit is contained in:
Peter Hutterer 2021-09-16 13:43:48 +10:00 committed by Wim Taymans
parent b58282353b
commit 52bd80aaa4
6 changed files with 308 additions and 50 deletions

View file

@ -127,9 +127,16 @@ Allowed configuration file sections are:
\section sec_logging Logging
The `PIPEWIRE_DEBUG` environment variable can be used to enable
more debugging. The format is:
more debugging. This variable supports one of two formats:
`<level>[<category>,<category>,...]`
- `PIPEWIRE_DEBUG=<level>` where `<level>` is either a numerical log level or it's
respective key, see below.
- `PIPEWIRE_DEBUG=<glob1>:<level1>,<glob2>:<level2>,...` where the globs are
shell-globs to match on log topics and the levels are the respective
log level to set for that topic. Globs are applied in-order and a matching
glob overrides an earlier glob for that category. For example,
`PIPEWIRE_DEBUG=*:E,mod.*:D,mod.foo:X" enables global error messages,
debugging on all modules but no messages on the foo module.
- `<level>` specifies the log level:
+ `X` or `0`: no logging is enabled
@ -140,9 +147,14 @@ more debugging. The format is:
+ `T` or `5`: Trace messages are enabled. These messages can be logged
from the realtime threads.
- `<category>`: Specifies a string category to enable. Many categories
can be separated by commas. Current categories are:
+ `connection`: to log connection messages
PipeWire uses a "category.topic" naming scheme, with the following categories:
- `pw.*`: pipewire-internal topics
- `mod.*`: module topics, for example `mod.foo` would usually refer to the
"foo" module
- `conn.*`: connection-specific topics such as printing raw messages sent over
a communication socket. These are in a separate namespace as they are
usually vastly more verbose than the normal debugging topics.
This namespace must be explicitly enabled with a `conn.<glob>` glob.
The behavior of the logging can be further controlled with the following