pulse: Document client libraries logging behavior

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 quite easy, thus the need for an
official documentation text.

Signed-off-by: Ahmed S. Darwish <darwish.07@gmail.com>

1 files changed, 33 insertions, 0 deletions

diff --git a/src/pulse/pulseaudio.h b/src/pulse/pulseaudio.h
index 215ba6d64..f5c5b0d13 100644
--- a/src/pulse/pulseaudio.h
+++ b/src/pulse/pulseaudio.h
@@ -125,6 +125,39 @@
  * 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`: Maximum 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, include 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. Rate limiting skips certain log messages when their frequency
+ *     is considered too high.
+ *
  * \section pkgconfig pkg-config
  *
  * The PulseAudio libraries provide pkg-config snippets for the different