Debug Logging

Getting debug messages on the command line is a matter of setting the WIREPLUMBER_DEBUG environment variable. The generic syntax is:

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:

  1. critical warnings and fatal errors (C & E in the log)

  2. warnings (W)

  3. normal messages (M)

  4. informational messages (I)

  5. debug messages (D)

  6. 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 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:

WIREPLUMBER_DEBUG=D

Show all messages up to the debug level (E, C, W, M, I & D), excluding trace:

WIREPLUMBER_DEBUG=M

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):

WIREPLUMBER_DEBUG=2

Show all messages from the wireplumber library:

WIREPLUMBER_DEBUG=D:wp-*

Show all messages from wp-registry, libpipewire and all modules:

WIREPLUMBER_DEBUG=D: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 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 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