Debug Logging — WirePlumber 0.4.1 documentation

# 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 a number from 1 to 5 and 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 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=5

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

    WIREPLUMBER_DEBUG=4

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=5:wp-*

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

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