From 7534be6fbcfeb06eac5715729e8e4c95271f5e00 Mon Sep 17 00:00:00 2001
From: Amy Griffis <amy.griffis@hp.com>
Date: Thu, 6 Aug 2009 15:58:38 +0200
Subject: [PATCH] Update logging documentation

* docs/logging.html[.in] try to include a little more description about
  the corner cases, things someone might get hung up on on.
---
 docs/logging.html    | 22 ++++++++++++++++++++--
 docs/logging.html.in | 22 ++++++++++++++++++++--
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/docs/logging.html b/docs/logging.html
index b16a7bb423..0a11c274f6 100644
--- a/docs/logging.html
+++ b/docs/logging.html
@@ -147,24 +147,42 @@
         <ul><li>LIBVIRT_DEBUG: it can take the four following values:
       <ul><li>1 or "debug": asking the library to log every message emitted,
             though the filters can be used to avoid filling up the output</li><li>2 or "info": log all non-debugging informations</li><li>3 or "warn": log warnings and errors, that's the default value</li><li>4 or "error": log only error messages</li></ul></li><li>LIBVIRT_LOG_FILTERS: allow to define logging filters</li><li>LIBVIRT_LOG_OUTPUTS: allow to define logging outputs</li></ul>
+        <p>Note that, for example, setting LIBVIRT_DEBUG= is the same as unset. If
+       you specify an invalid value, it will be ignored with a warning. If you
+       have an error in a filter or output string, some of the settings may be
+       applied up to the point at which libvirt encountered the error.</p>
         <p>Similary the daemon logging behaviour can be tuned using 3 config
     variables, stored in the configuration file:
     </p>
         <ul><li>log_level: accepts the following values:
       <ul><li>4: only errors</li><li>3: warnings and errors</li><li>2: informations, warnings and errors</li><li>1: debug and everything</li></ul></li><li>log_filters: allow to define logging filters</li><li>log_outputs: allow to define logging outputs</li></ul>
-        <p>In both case the syntax for filters and outputs is similar.</p>
+        <p>When starting the libvirt daemon, any logging environment variable
+       settings will override settings in the config file. Command line options
+       take precedence over all. If no outputs are defined for libvirtd, it
+       defaults to logging to syslog when it is running as a daemon, or to
+       stderr when it is running in the foreground.</p>
+        <p>Libvirtd does not reload its logging configuration when issued a SIGHUP.
+       If you want to reload the configuration, you must do a <code>service
+       libvirtd restart</code> or manually stop and restart the daemon
+       yourself.</p>
+        <p>The syntax for filters and outputs is the same for both types of
+       variables.</p>
         <p>The format for a filter is:</p>
         <pre>x:name</pre>
         <p>where <code>name</code> is a match string e.g. <code>remote</code> or
     <code>qemu</code> and the x is the minimal level where matching messages
     should be logged:</p>
         <ul><li>1: DEBUG</li><li>2: INFO</li><li>3: WARNING</li><li>4: ERROR</li></ul>
-        <p>Multiple filter can be defined in a single string, they just need to be
+        <p>Multiple filters can be defined in a single string, they just need to be
     separated by spaces, e.g: <code>"3:remote 4:event"</code> to only get
     warning or errors from the remote layer and only errors from the event
     layer.</p>
         <p>
     </p>
+        <p>If you specify a log priority in a filter that is below the default log
+       priority level, messages that match that filter will still be logged,
+       while others will not. In order to see those messages, you must also have
+       an output defined that includes the priority level of your filter.</p>
         <p>The format for an output can be one of those 3 forms:</p>
         <ul><li><code>x:stderr</code> output goes to stderr</li><li><code>x:syslog:name</code> use syslog for the output and use the
       given <code>name</code> as the ident</li><li><code>x:file:file_path</code>output to a file, with the given
diff --git a/docs/logging.html.in b/docs/logging.html.in
index fcd100ff52..63a0b052e0 100644
--- a/docs/logging.html.in
+++ b/docs/logging.html.in
@@ -44,6 +44,10 @@
       <li>LIBVIRT_LOG_FILTERS: allow to define logging filters</li>
       <li>LIBVIRT_LOG_OUTPUTS: allow to define logging outputs</li>
     </ul>
+    <p>Note that, for example, setting LIBVIRT_DEBUG= is the same as unset. If
+       you specify an invalid value, it will be ignored with a warning. If you
+       have an error in a filter or output string, some of the settings may be
+       applied up to the point at which libvirt encountered the error.</p>
     <p>Similary the daemon logging behaviour can be tuned using 3 config
     variables, stored in the configuration file:
     <ul>
@@ -57,7 +61,17 @@
       <li>log_filters: allow to define logging filters</li>
       <li>log_outputs: allow to define logging outputs</li>
     </ul>
-    <p>In both case the syntax for filters and outputs is similar.</p>
+    <p>When starting the libvirt daemon, any logging environment variable
+       settings will override settings in the config file. Command line options
+       take precedence over all. If no outputs are defined for libvirtd, it
+       defaults to logging to syslog when it is running as a daemon, or to
+       stderr when it is running in the foreground.</p>
+    <p>Libvirtd does not reload its logging configuration when issued a SIGHUP.
+       If you want to reload the configuration, you must do a <code>service
+       libvirtd restart</code> or manually stop and restart the daemon
+       yourself.</p>
+    <p>The syntax for filters and outputs is the same for both types of
+       variables.</p>
     <p>The format for a filter is:</p>
     <pre>x:name</pre>
     <p>where <code>name</code> is a match string e.g. <code>remote</code> or
@@ -69,10 +83,14 @@
       <li>3: WARNING</li>
       <li>4: ERROR</li>
     </ul>
-    <p>Multiple filter can be defined in a single string, they just need to be
+    <p>Multiple filters can be defined in a single string, they just need to be
     separated by spaces, e.g: <code>"3:remote 4:event"</code> to only get
     warning or errors from the remote layer and only errors from the event
     layer.<p>
+    <p>If you specify a log priority in a filter that is below the default log
+       priority level, messages that match that filter will still be logged,
+       while others will not. In order to see those messages, you must also have
+       an output defined that includes the priority level of your filter.</p>
     <p>The format for an output can be one of those 3 forms:</p>
     <ul>
       <li><code>x:stderr</code> output goes to stderr</li>