Debian Codegraph @

docs/rst/daemon/logging.rst

raw
1 .. _daemon_logging:
2
3 Debug Logging
4 =============
5
6 WirePlumber is instrumented with log messages in its entire codebase. These
7 messages are categorized based on two heuristics: the log topic and the log
8 level.
9
10 The log topic is a string that identifies which component of the code this
11 message is coming from. Well-known topics include:
12
13 - **wireplumber**: messages from the wireplumber daemon
14 - **wp-***: messages from libwireplumber
15
16 - **wp-core**: messages from *WpCore*
17 - **wp-proxy**: messages from *WpProxy*
18 - ... and so on ...
19
20 - **m-***: messages from wireplumber modules
21
22 - **m-default-profile**: messages from *libwireplumber-module-default-profile*
23 - **m-default-routes**: messages from *libwireplumber-module-default-routes*
24 - ... and so on ...
25
26 - **s-***: messages from scripts
27
28 - **s-linking**: messages from the *linking/\*.lua* scripts
29 - **s-default-nodes**: messages from the *default-nodes/\*.lua* scripts
30 - ... and so on ...
31
32 - **pw.***: messages from libpipewire
33 - **spa.***: messages from spa plugins
34 - **mod.***: messages from libpipewire modules
35 - **conn.***: messages to debug the pipewire socket connection
36
37 The log level is a value that designates the importance of the message.
38 The levels that exist in WirePlumber are the following:
39
40 - ``F``: *Fatal errors*. These messages represent situations where execution
41 of the program cannot continue. In the extremely unlikely case that
42 they appear, these messages also cause the process to be terminated.
43 - ``E``: *Critical warnings* (or "errors" in the PipeWire terminology).
44 These messages represent situations where something unexpected has happened
45 and someone with understanding of the code should probably take a look at it.
46 These situations are usually programming mistakes or omissions.
47 This does not necessarily mean that the program is not functioning correctly.
48 It may mean, though, that the specific part of the program that logged the
49 message (the plugin, subsystem, ...) may not work optimally.
50 - ``W``: *Warnings*. These messages represent situations where something has
51 gone unintentionally wrong, but it was not totally unexpected. The situation
52 is recovered and the program can continue. In many cases, this warning may
53 mean that there is something wrong with the configuration or the environment
54 and may need attention from the user.
55 - ``N``: *Notices*. These are important messages that the user should notice,
56 like warnings, but they do not necessarily mean a bad situation.
57 - ``I``: *Informational messages*. These messages provide information about
58 the internal operations of the program.
59 - ``D``: *Debug messages*. These messages provide details about the
60 internal operations of the program, which can be useful for debugging.
61 - ``T``: *Traces*. These messages provide very verbose printouts of internal
62 operations and data that affects these operations. These can be useful for
63 debugging as well, but it may be best to be enabled only for the topic(s)
64 that are intended to be debugged, as they can be very big in volume.
65
66 By default, WirePlumber logs only messages from levels ``F``, ``E``, ``W``
67 and ``N``. These messages are printed on the standard error (``stderr``) stream,
68 or they are logged to the systemd journal, if WirePlumber was started as a
69 systemd service.
70
71 The ``WIREPLUMBER_DEBUG`` environment variable can be used to change which
72 topics and levels are enabled. The generic syntax is:
73
74 .. code::
75
76 WIREPLUMBER_DEBUG=[<topic pattern>:]<level>,...,
77
78 This is a comma-separated list of topics to enable, paired with a level for
79 each topic.
80
81 ``<level>`` can be one of ``FEWNIDT`` or a numerical log level as listed below.
82
83 0. fatal errors (``F``)
84 1. critical warnings (``E``)
85 2. warnings and notices (``W`` & ``N``)
86 3. informational messages (``I``)
87 4. debug messages (``D``)
88 5. trace messages (``T``)
89
90 Each level always includes messages from the previous levels, so for instance
91 enabling level ``3`` (or ``I``) will also enable messages from levels ``2``
92 and ``1`` (``N``, ``W``, ``E`` and ``F``)
93
94 ``<topic pattern>`` is an *optional* description of one or more topics.
95 This supports
96 `glob style patterns <https://developer-old.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html>`_
97 containing ``*`` and ``?``.
98
99 If a ``<topic pattern>`` is not specified, then the given ``<level>`` is
100 considered to be the global log level, which applies to all topics that have
101 no explicit level specified.
102
103 Changing log level at runtime
104 -----------------------------
105
106 The debug log level can be changed at runtime using ``wpctl``:
107
108 .. code::
109
110 wpctl set-log-level D # enable debug logging for Wireplumber
111 wpctl set-log-level - # restore default logging for Wireplumber
112
113 wpctl set-log-level 0 4 # enable debug logging for Pipewire daemon
114 wpctl set-log-level 0 - # restore default logging for Pipewire daemon
115
116 Equivalently, it is also possible to adjust the logging by setting
117 ``log.level`` in the ``settings`` metadata:
118
119 .. code::
120
121 pw-metadata -n settings <ID> log.level "D" # WirePlumber logging
122
123 pw-metadata -n settings 0 log.level 4 # PipeWire daemon logging
124
125 Above, ``<ID>`` should be replaced by the WirePlumber daemon client ID.
126
127 Note that PipeWire daemon log levels must be specified by numbers, not
128 letter codes.
129
130 Changing log level via static configuration
131 -------------------------------------------
132
133 If you need to capture logs from WirePlumber at startup or in other circumstances
134 where changing the level at runtime or setting an environment variable is not
135 feasible, then you may also set the log level in the configuration file.
136
137 The log level changes via the ``log.level`` key in the ``context.properties``
138 section:
139
140 .. code::
141
142 context.properties = {
143 log.level = "D"
144 }
145
146 You may use the same syntax as in ``WIREPLUMBER_DEBUG`` to describe the exact
147 logging you want to achieve. For instance, to log debug messages from all
148 scripts and informational messages from everywhere else:
149
150 .. code::
151
152 context.properties = {
153 log.level = "I,s-*:D"
154 }
155
156 The easiest way to configure this is to drop a
157 :ref:`fragment file <config_conf_file_fragments>` that contains just this.
158
159 .. code-block:: bash
160
161 $ mkdir -p ~/.config/wireplumber/wireplumber.conf.d
162 $ echo 'context.properties = { log.level = "D" }' > ~/.config/wireplumber/wireplumber.conf.d/log.conf
163
164 See also :ref:`config_modifying_configuration`
165
166 Examples
167 --------
168
169 Show *all* messages:
170
171 .. code::
172
173 WIREPLUMBER_DEBUG=T
174
175 Show all messages up to the *debug* level (F, E, W, N, I & D), excluding *trace*:
176
177 .. code::
178
179 WIREPLUMBER_DEBUG=D
180
181 Show all messages up to the *notice* level (F, E, W & N),
182 excluding *info*, *debug* & *trace*
183 (this is also the default when ``WIREPLUMBER_DEBUG`` is omitted):
184
185 .. code::
186
187 WIREPLUMBER_DEBUG=2
188
189 Show all messages from the wireplumber library (including traces), but only
190 up to informational messages from other topics:
191
192 .. code::
193
194 WIREPLUMBER_DEBUG=I,wp-*:T
195
196 Show debug messages from ``wp-registry``, libpipewire and all modules, keeping
197 all other topics up to the *notice* level.
198
199 .. code::
200
201 WIREPLUMBER_DEBUG=2,wp-registry:4,pw.*:4,m-*:4
202
203 Relationship with the GLib log handler & G_MESSAGES_DEBUG
204 ---------------------------------------------------------
205
206 Older versions of WirePlumber used to use ``G_MESSAGES_DEBUG`` to control their
207 log output, which is the environment variable that affects GLib's default
208 log handler.
209
210 As of WirePlumber 0.3, ``G_MESSAGES_DEBUG`` is no longer used, since
211 libwireplumber replaces the default log handler.
212
213 If you are writing your own application based on libwireplumber, you can choose
214 if you want to replace this log handler using the flags passed to
215 :c:func:`wp_init`.
216
217 Relationship with the PipeWire log handler & PIPEWIRE_DEBUG
218 -----------------------------------------------------------
219
220 libpipewire uses the ``PIPEWIRE_DEBUG`` environment variable, with a similar syntax.
221 WirePlumber replaces the log handler of libpipewire with its own, rendering
222 ``PIPEWIRE_DEBUG`` useless. Instead, you should use ``WIREPLUMBER_DEBUG``.
223 All the log topics that apply to libpipewire and its modules / plugins work
224 the same in ``WIREPLUMBER_DEBUG``.
225
226 If you are writing your own application based on libwireplumber, you can choose
227 if you want to replace this log handler using the flags passed to
228 :c:func:`wp_init`.
229
230 Mapping of PipeWire debug levels to WirePlumber
231 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
232
233 PipeWire supports 5 levels of debug logging. WirePlumber, on the other hand,
234 supports 7 levels. Some levels seem common, but the terminology and the
235 semantics are slightly different. The following table shows how the various
236 levels are mapped:
237
238 ============= =============== ========================
239 Numeric Level PipeWire WirePlumber
240 ============= =============== ========================
241 0 no log ``F`` - Fatal Error
242 1 ``E`` - Error ``E`` - Critical Warning
243 2 ``W`` - Warning ``W`` - Warning,
244 ``N`` - Notice
245 3 ``I`` - Info ``I`` - Info
246 4 ``D`` - Debug ``D`` - Debug
247 5 ``T`` - Trace ``T`` - Trace
248 ============= =============== ========================