Change in vdsm[ovirt-4.0]: docs: add README about logging configuration

Hello Dan Kenigsberg,

I'd like you to do a code review.  Please visit

https://gerrit.ovirt.org/64515

to review the following change.

Change subject: docs: add README about logging configuration
......................................................................

docs: add README about logging configuration

Most notably, document how to tune the logging
settings of Vdsm at runtime, using Vdsclient

Change-Id: I2653c2a68fcf42b1e085ae1ee703fb119a0cf1fc
Backport-To: 4.0
Signed-off-by: Francesco Romani 
Reviewed-on: https://gerrit.ovirt.org/60533
Continuous-Integration: Jenkins CI
Reviewed-by: Dan Kenigsberg 
---
M Makefile.am
A README.logging
M vdsm.spec.in
3 files changed, 64 insertions(+), 1 deletion(-)

git pull ssh://gerrit.ovirt.org:29418/vdsm refs/changes/15/64515/1

diff --git a/Makefile.am b/Makefile.am
index 9ac2515..1f1f0fe 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -39,6 +39,7 @@
 # rpm from the tarball.
 EXTRA_DIST = \
    .gitignore \
+	README.logging \
    autobuild.sh \
    autogen.sh \
    build-aux/pkg-version \
diff --git a/README.logging b/README.logging
new file mode 100644
index 0000000..c6ec567
--- /dev/null
+++ b/README.logging
@@ -0,0 +1,60 @@
+Logging in Vdsm
+===============
+
+Basic configuration
+-------------------
+
+Vdsm uses the python standard module[1] for logging.
+It can be configured using /etc/vdsm/logger.conf;
+the supervdsm logging is configured separately, using
+/etc/vdsm/svdsm.logger.conf
+
+
+Tuning the logging at runtime
+-----------------------------
+
+Vdsm logging could be configured extensively[2]
+using the configuration files, but this requires a restart of the daemon.
+
+You can also configure the logging to some extent at runtime, without
+any restart, using vdsClient as explained below.
+Please note that any change you make using vdsClient is not permanent, and
+will be lost once Vdsm is restarted.
+
+Using vdsClient, you can tune the log level of any logger Vdsm uses.
+The basic syntax is:
+
+# vdsClient [-s] SERVER setLogLevel LEVEL [LOGGER]
+
+`LEVEL` is one of DEBUG, INFO, WARNING
+`LOGGER` is any logger Vdsm uses. Please check the configuration file
+to learn about some predefined loggers.
+
+If no LOGGER is given, the root logger is used implicitely.
+
+Please note that the logging configuration of Vdsm is quite complex, so
+few trivial settings may yield surprising results.
+
+
+Examples of runtime tuning of logging
+-------------------------------------
+
+1. set everything to the DEBUG level:
+vdsClient -s 0 setLogLevel DEBUG
+
+2. silence virt logs, show only warnings, errors or worse:
+vdsClient -s 0 setLogLevel WARNING virt
+
+3. same as #2, for storage (case is significant here)
+vdsClient -s 0 setLogLevel WARNING Storage
+vdsClient -s 0 setLogLevel WARNING storage
+
+4. silence JSONRPC logs:
+vdsClient -s 0 setLogLevel WARNING jsonrpc
+
+
+Notes
+-----
+
+[1] https://docs.python.org/2/library/logging.html
+[2] https://docs.python.org/2/library/logging.config.html#logging-config-filefor...
diff --git a/vdsm.spec.in b/vdsm.spec.in
index 50c01e8..13596d6 100644
--- a/vdsm.spec.in
+++ b/vdsm.spec.in
@@ -937,7 +937,9 @@

%files
 %defattr(-, root, root, -)
-%doc README lib/vdsm/vdsm.conf.sample
+%doc README
+%doc lib/vdsm/vdsm.conf.sample
+%doc README.logging
 %license COPYING
 /usr/lib/systemd/systemd-vdsmd
 /usr/lib/systemd/system-preset/85-vdsmd.preset