[pulseaudio-discuss] [PATCH] pulse: Document client libraries logging behavior

[Ahmed S. Darwish]

Document how to modify the client libraries logging behvaior
using any of the PA-specific environment variables.

Using the `PULSE_LOG_*'environment variables makes debugging
and tracing PA applications quie easy, thus the need for an
official documentation text.

Signed-off-by: Ahmed S. Darwish <darwish.07 at gmail.com>
---
 src/pulse/pulseaudio.h | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/src/pulse/pulseaudio.h b/src/pulse/pulseaudio.h
index 215ba6d..fdc8c5f 100644
--- a/src/pulse/pulseaudio.h
+++ b/src/pulse/pulseaudio.h
@@ -125,6 +125,40 @@
  * An error code can be turned into a human readable message using
  * pa_strerror().
  *
+ * \section logging_sec Logging
+ *
+ * You can configure different logging parameters for the PulseAudio client
+ * libraries. The following environment variables are recognized:
+ *
+ *  - `PULSE_LOG`: Maxium log level required. Bigger values result in a
+ *     more verbose logging output. The following values are recognized:
+ *     + `0`: Error messages
+ *     + `1`: Warning messages
+ *     + `2`: Notice messages
+ *     + `3`: Info messages
+ *     + `4`: Debug messages
+ *  - `PULSE_LOG_SYSLOG`: If defined, force all client libraries to log
+ *     their output using the syslog(3) mechanism. Default behavior is to
+ *     log all output to stderr.
+ *  - `PULSE_LOG_COLORS`: If defined, enables colored logging output.
+ *  - `PULSE_LOG_TIME`: If defined, include timestamps with each message.
+ *  - `PULSE_LOG_FILE`: If defined, include each message originating file
+ *     name.
+ *  - `PULSE_LOG_META`: If defined, include each message originating file
+ *     name and path relative to the PulseAudio source tree root.
+ *  - `PULSE_LOG_LEVEL`: If defined, includ a log level prefix with each
+ *     message. Respectively, the prefixes "E", "W", "N", "I", "D" stands
+ *     for Error, Warning, Notice, Info, and Debugging.
+ *  - `PULSE_LOG_BACKTRACE`: Number of functions to display in the backtrace.
+ *     If this variable is not defined, or has a value of zero, no backtrace
+ *     is shown.
+ *  - `PULSE_LOG_BACKTRACE_SKIP`: Number of backtrace levels to skip, from
+ *     the function printing the log message downwards.
+ *  - `PULSE_LOG_NO_RATE_LIMIT`: If defined, do not rate limit the logging
+ *     output of any PulseAudio component or module. This is especially
+ *     true for the udev audio hardware detaection module, where a potential
+ *     for excessive logging output exists.
+ *
  * \section pkgconfig pkg-config
  *
  * The PulseAudio libraries provide pkg-config snippets for the different
-- 
2.5.0