Hi list,
What it is
==========
This is a new feature which plugs into the current logging system to enhance
the debugging experiences for users and developers. It would log all level's
messages in a separate place, therefore it have the following benefits:
- The most important of this feature is that we don't need to restart
PulseAudio with a verbose output to view what's wrong under the hood
when there's something wrong. It's not only useful for developers but
also very useful for end users to report issues. In this case, we
don't need to ask the end users to kill PulseAudio and restart
PulseAudio which is too advanced for them. Instead, we can just ask
them to send the ring buffer log to us, which is only one command
away. Easy for them to follow.
- It doesn't clobber your normal log output. The normal log output is where you
specified it as log target. However this log's info is totally in another
place.
- It collects all level's messages. It makes the process of peeking into the
internals in a quick and easy way. We don't need to change the log level
dynamically to more verbose one and then change it back.
- The buffer runs in a circular buffer, which means that it wouldn't take too
much spaces from your whole system. And if you runs PulseAudio in a really
memory tight system, we provide an option to disable this feature totally.
How to use it
=============
Unless you compile PulseAudio from source with `--disable-ring-buffer` option,
this feature should be enabled by default. We don't need anything to enable,
it just runs under the hood.
The only interface right now to use it is to call the following commands:
pactl get-log
Just as anything `pactl` sub-commands, we can even specify another machine. So
we can get the log information from a remote server. However, it's subject to
`pactl`'s normal authentication and configuration.
The implementation details
==========================
Note that the best solution is to have a lock-free implementation, but
at the current stage, we still have a little bit locking, it's still
for experimental purposes, we'd like to resolve this issue.
Due to the fact that PulseAudio takes the thread model. We have each smaller
buffer for each thread.
Therefore, for each logging, each thread runs at its own, there's no locking at
all from 'thread1' to 'buffer1' as illustrated in the following chart.
+---------+ +---------+ +---------+
| thread1 | | thread2 | ... | thread3 |
+---------+ +---------+ +---------+
| | |
v v v
+---------+ +---------+ +---------+
| buffer1 | | buffer2 | ... | buffer3 |
+---------+ +---------+ +---------+
| | |
`-----------+---------------'
|
v
+------------+
| all output |
+------------+
When a user wants to introspect what's going on under the neath, and invokes
the `get-log` command, PulseAudio would reassemble the log messages from each
thread buffer into a large one and would return it back to users. There is a
small compensation for locking here, but as the freqency of `get-log` command
is rather low, the cost for locking is at its minimal.
Ask for comments
================
We design this feature to try to be useful for users and developers. We'd like
to hear from you how do you think. Please don't hesitate to give your valuable
feedback!
Thanks!
Deng Zhengrong
