mirror of
https://gitlab.freedesktop.org/pipewire/wireplumber.git
synced 2026-02-06 18:50:29 +01:00
139 lines
4.6 KiB
ReStructuredText
139 lines
4.6 KiB
ReStructuredText
.. _logging:
|
|
|
|
Debug Logging
|
|
=============
|
|
|
|
Getting debug messages on the command line is a matter of setting the
|
|
``WIREPLUMBER_DEBUG`` environment variable. The generic syntax is:
|
|
|
|
.. code::
|
|
|
|
WIREPLUMBER_DEBUG=level:category1,category2,...
|
|
|
|
``level`` can be one of ``CEWMIDT`` or a numerical log level as listed below.
|
|
In either case it defines the minimum debug level to show:
|
|
|
|
0. critical warnings and fatal errors (``C`` & ``E`` in the log)
|
|
1. warnings (``W``)
|
|
2. normal messages (``M``)
|
|
3. informational messages (``I``)
|
|
4. debug messages (``D``)
|
|
5. trace messages (``T``)
|
|
|
|
``category1,category2,...`` is an *optional* comma-separated list of debug
|
|
categories to show. Any categories not listed here will *not* appear in the log.
|
|
If no categories are specified, then all messages are printed.
|
|
|
|
Categories support
|
|
`glob style patterns <https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html>`_
|
|
containing ``*`` and ``?``, for convenience.
|
|
|
|
Well known categories include:
|
|
|
|
- **wireplumber**: messages from the wireplumber daemon
|
|
- **pw**: messages from libpipewire & spa plugins
|
|
- **wp-***: messages from libwireplumber
|
|
- **wp-core**: messages from *WpCore*
|
|
- **wp-proxy**: messages from *WpProxy*
|
|
- ... and so on ...
|
|
- **m-***: messages from wireplumber modules
|
|
- **m-default-profile**: messages from *libwireplumber-module-default-profile*
|
|
- **m-default-routes**: messages from *libwireplumber-module-default-routes*
|
|
- ... and so on ...
|
|
- **script/***: messages from scripts
|
|
- **script/policy-node**: messages from the *policy-node.lua* script
|
|
- ... and so on ...
|
|
|
|
Examples
|
|
--------
|
|
|
|
Show all messages:
|
|
|
|
.. code::
|
|
|
|
WIREPLUMBER_DEBUG=T
|
|
|
|
Show all messages up to the *debug* level (E, C, W, M, I & D), excluding *trace*:
|
|
|
|
.. code::
|
|
|
|
WIREPLUMBER_DEBUG=D
|
|
|
|
Show all messages up to the *message* level (E, C, W & M),
|
|
excluding *info*, *debug* & *trace*
|
|
(this is also the default when ``WIREPLUMBER_DEBUG`` is omitted):
|
|
|
|
.. code::
|
|
|
|
WIREPLUMBER_DEBUG=2
|
|
|
|
Show all messages from the wireplumber library:
|
|
|
|
.. code::
|
|
|
|
WIREPLUMBER_DEBUG=T:wp-*
|
|
|
|
Show all messages from ``wp-registry``, libpipewire and all modules:
|
|
|
|
.. code::
|
|
|
|
WIREPLUMBER_DEBUG=T:wp-registry,pw,m-*
|
|
|
|
Relationship with the GLib log handler & G_MESSAGES_DEBUG
|
|
---------------------------------------------------------
|
|
|
|
Older versions of WirePlumber used to use ``G_MESSAGES_DEBUG`` to control their
|
|
log output, which is the environment variable that affects GLib's default
|
|
log handler.
|
|
|
|
As of WirePlumber 0.3, ``G_MESSAGES_DEBUG`` is no longer used, since
|
|
libwireplumber replaces the default log handler.
|
|
|
|
If you are writing your own application based on libwireplumber, you can choose
|
|
if you want to replace this log handler using the flags passed to
|
|
:c:func:`wp_init`.
|
|
|
|
Relationship with the PipeWire log handler & PIPEWIRE_DEBUG
|
|
-----------------------------------------------------------
|
|
|
|
libpipewire uses the ``PIPEWIRE_DEBUG`` environment variable, with a similar syntax.
|
|
WirePlumber replaces the log handler of libpipewire with its own, rendering
|
|
``PIPEWIRE_DEBUG`` useless. Instead, you should use ``WIREPLUMBER_DEBUG`` and the
|
|
``pw`` category to control log messages from libpipewire & its plugins.
|
|
|
|
If you are writing your own application based on libwireplumber, you can choose
|
|
if you want to replace this log handler using the flags passed to
|
|
:c:func:`wp_init`.
|
|
|
|
Mapping of PipeWire debug levels to WirePlumber
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Both WirePlumber and PipeWire support 6 levels of debug logging, from 0 to 5
|
|
|
|
PipeWire uses a slightly different semantic for the first 3 levels:
|
|
|
|
===== ======== ===========
|
|
Level PipeWire WirePlumber
|
|
===== ======== ===========
|
|
0 no log Critical / fatal Errors
|
|
1 Errors Warnings
|
|
2 Warnings Messages
|
|
===== ======== ===========
|
|
|
|
When PipeWire log messages are printed by the WirePlumber log handler, the
|
|
level number stays the same and the semantic changes. PipeWire's errors are
|
|
printed in the ``W`` category and PipeWire's warnings are printed in the
|
|
``M`` category.
|
|
|
|
In WirePlumber's (actually GLib's) semantics, this feels more appropriate
|
|
because:
|
|
|
|
- GLib's errors are fatal (``abort()`` is called)
|
|
- GLib's critical warnings are assertion failures (i.e. programming mistakes,
|
|
not runtime errors)
|
|
- PipeWire's errors are neither fatal, nor programming mistakes; they are
|
|
just bad situations that are not meant to happen
|
|
- GLib's warnings are exactly that: bad runtime situations that are not meant
|
|
to happen, so mapping PipeWire errors to GLib warnings makes sense
|
|
- The **Messages** log level does not exist in PipeWire, so it can be used to
|
|
fill the gap for PipeWire warnings
|