log: update docs for daemons to improve user understanding

Strongly recommend against use of the log_levels setting since it
creates overly verbose logs and has a serious performance impact.

Describe the log filter syntax better and mention use of shell
glob syntax. Also provide more realistic example of good settings
to use. The libvirtd example is biased towards QEMU, but when the
drivers split off each daemon can get its own more appropriate
example.
Reviewed-by: NJohn Ferlan <jferlan@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

src/locking/test_virtlockd.aug.in

@@ -3,7 +3,7 @@ module Test_virtlockd =
 
    test Virtlockd.lns get conf =
         { "log_level" = "3" }
-        { "log_filters" = "3:remote 4:event" }
+        { "log_filters" = "1:locking 4:object 4:json 4:event 1:util" }
         { "log_outputs" = "3:syslog:virtlockd" }
         { "max_clients" = "1024" }
         { "admin_max_clients" = "5" }

src/locking/virtlockd.conf

@@ -8,46 +8,75 @@
 
 # Logging level: 4 errors, 3 warnings, 2 information, 1 debug
 # basically 1 will log everything possible
+#
+# WARNING: USE OF THIS IS STRONGLY DISCOURAGED.
+#
+# WARNING: It outputs too much information to practically read.
+# WARNING: The "log_filters" setting is recommended instead.
+#
+# WARNING: Journald applies rate limiting of messages and so libvirt
+# WARNING: will limit "log_level" to only allow values 3 or 4 if
+# WARNING: journald is the current output.
+#
+# WARNING: USE OF THIS IS STRONGLY DISCOURAGED.
 #log_level = 3
 
 # Logging filters:
 # A filter allows to select a different logging level for a given category
-# of logs
-# The format for a filter is one of:
-#    x:name
-#    x:+name
-#      where name is a string which is matched against source file name,
-#      e.g., "remote", "qemu", or "util/json", the optional "+" prefix
-#      tells libvirt to log stack trace for each message matching name,
-#      and x is the minimal level where matching messages should be logged:
+# of logs. The format for a filter is one of:
+#
+#    level:match
+#    level:+match
+#
+# where 'match' is a string which is matched against the category
+# given in the VIR_LOG_INIT() at the top of each libvirt source
+# file, e.g., "remote", "qemu", or "util.json". The 'match' in the
+# filter matches using shell wildcard syntax (see 'man glob(7)').
+# The 'match' is always treated as a substring match. IOW a match
+# string 'foo' is equivalent to '*foo*'.
+#
+# If 'match' contains the optional "+" prefix, it tells libvirt
+# to log stack trace for each message matching name.
+#
+# 'level' is the minimal level where matching messages should
+#  be logged:
+#
 #    1: DEBUG
 #    2: INFO
 #    3: WARNING
 #    4: ERROR
 #
-# Multiple filter can be defined in a single @filters, they just need to be
-# separated by spaces.
+# Multiple filters can be defined in a single @log_filters, they just need
+# to be separated by spaces. Note that libvirt performs "first" match, i.e.
+# if there are concurrent filters, the first one that matches will be applied,
+# given the order in @log_filters.
+#
+# For the virtlockd daemon, a typical need is to capture information
+# from the locking code and some of the utility code. Some utility
+# code is very verbose and is generally not desired. A suitable filter
+# string for debugging might be to turn off object, json & event logging,
+# but enable the rest of the util and the locking code:
 #
-# e.g. to only get warning or errors from the remote layer and only errors
-# from the event layer:
-#log_filters="3:remote 4:event"
+#log_filters="1:locking 4:object 4:json 4:event 1:util"
 
 # Logging outputs:
 # An output is one of the places to save logging information
 # The format for an output can be:
-#    x:stderr
+#    level:stderr
 #      output goes to stderr
-#    x:syslog:name
+#    level:syslog:name
 #      use syslog for the output and use the given name as the ident
-#    x:file:file_path
+#    level:file:file_path
 #      output to a file, with the given filepath
-# In all case the x prefix is the minimal level, acting as a filter
+#    level:journald
+#      output to journald logging system
+# In all cases 'level' is the minimal priority, acting as a filter
 #    1: DEBUG
 #    2: INFO
 #    3: WARNING
 #    4: ERROR
 #
-# Multiple output can be defined, they just need to be separated by spaces.
+# Multiple outputs can be defined, they just need to be separated by spaces.
 # e.g. to log all warnings and errors to syslog under the virtlockd ident:
 #log_outputs="3:syslog:virtlockd"
 #

src/logging/test_virtlogd.aug.in

@@ -3,7 +3,7 @@ module Test_virtlogd =
 
    test Virtlogd.lns get conf =
         { "log_level" = "3" }
-        { "log_filters" = "3:remote 4:event" }
+        { "log_filters" = "1:logging 4:object 4:json 4:event 1:util" }
         { "log_outputs" = "3:syslog:virtlogd" }
         { "max_clients" = "1024" }
         { "admin_max_clients" = "5" }

src/logging/virtlogd.conf

@@ -8,48 +8,75 @@
 
 # Logging level: 4 errors, 3 warnings, 2 information, 1 debug
 # basically 1 will log everything possible
+#
+# WARNING: USE OF THIS IS STRONGLY DISCOURAGED.
+#
+# WARNING: It outputs too much information to practically read.
+# WARNING: The "log_filters" setting is recommended instead.
+#
+# WARNING: Journald applies rate limiting of messages and so libvirt
+# WARNING: will limit "log_level" to only allow values 3 or 4 if
+# WARNING: journald is the current output.
+#
+# WARNING: USE OF THIS IS STRONGLY DISCOURAGED.
 #log_level = 3
 
 # Logging filters:
 # A filter allows to select a different logging level for a given category
-# of logs
-# The format for a filter is one of:
-#    x:name
-#    x:+name
-#      where name is a string which is matched against source file name,
-#      e.g., "remote", "qemu", or "util/json", the optional "+" prefix
-#      tells libvirt to log stack trace for each message matching name,
-#      and x is the minimal level where matching messages should be logged:
+# of logs. The format for a filter is one of:
+#
+#    level:match
+#    level:+match
+#
+# where 'match' is a string which is matched against the category
+# given in the VIR_LOG_INIT() at the top of each libvirt source
+# file, e.g., "remote", "qemu", or "util.json". The 'match' in the
+# filter matches using shell wildcard syntax (see 'man glob(7)').
+# The 'match' is always treated as a substring match. IOW a match
+# string 'foo' is equivalent to '*foo*'.
+#
+# If 'match' contains the optional "+" prefix, it tells libvirt
+# to log stack trace for each message matching name.
+#
+# 'level' is the minimal level where matching messages should
+#  be logged:
+#
 #    1: DEBUG
 #    2: INFO
 #    3: WARNING
 #    4: ERROR
 #
-# Multiple filter can be defined in a single @filters, they just need to be
-# separated by spaces.
+# Multiple filters can be defined in a single @log_filters, they just need
+# to be separated by spaces. Note that libvirt performs "first" match, i.e.
+# if there are concurrent filters, the first one that matches will be applied,
+# given the order in @log_filters.
+#
+# For the virtlogd daemon, a typical need is to capture information
+# from the logging code and some of the utility code. Some utility
+# code is very verbose and is generally not desired. A suitable filter
+# string for debugging might be to turn off object, json & event logging,
+# but enable the rest of the util and the logging code:
 #
-# e.g. to only get warning or errors from the remote layer and only errors
-# from the event layer:
-#log_filters="3:remote 4:event"
+#log_filters="1:logging 4:object 4:json 4:event 1:util"
 
 # Logging outputs:
 # An output is one of the places to save logging information
 # The format for an output can be:
-#    x:stderr
+#    level:stderr
 #      output goes to stderr
-#    x:syslog:name
+#    level:syslog:name
 #      use syslog for the output and use the given name as the ident
-#    x:file:file_path
+#    level:file:file_path
 #      output to a file, with the given filepath
-#    x:journald
-#      ouput to the systemd journal
-# In all case the x prefix is the minimal level, acting as a filter
+#    level:journald
+#      output to journald logging system
+# In all cases 'level' is the minimal priority, acting as a filter
 #    1: DEBUG
 #    2: INFO
 #    3: WARNING
 #    4: ERROR
 #
-# Multiple output can be defined, they just need to be separated by spaces.
+# Multiple outputs can be defined, they just need to be separated by spaces.
 # e.g. to log all warnings and errors to syslog under the virtlogd ident:
 #log_outputs="3:syslog:virtlogd"
 #

src/remote/libvirtd.conf

@@ -338,54 +338,70 @@
 
 # Logging level: 4 errors, 3 warnings, 2 information, 1 debug
 # basically 1 will log everything possible
-# Note: Journald may employ rate limiting of the messages logged
-# and thus lock up the libvirt daemon. To use the debug level with
-# journald you have to specify it explicitly in 'log_outputs', otherwise
-# only information level messages will be logged.
+#
+# WARNING: USE OF THIS IS STRONGLY DISCOURAGED.
+#
+# WARNING: It outputs too much information to practically read.
+# WARNING: The "log_filters" setting is recommended instead.
+#
+# WARNING: Journald applies rate limiting of messages and so libvirt
+# WARNING: will limit "log_level" to only allow values 3 or 4 if
+# WARNING: journald is the current output.
+#
+# WARNING: USE OF THIS IS STRONGLY DISCOURAGED.
 #log_level = 3
 
 # Logging filters:
 # A filter allows to select a different logging level for a given category
-# of logs
-# The format for a filter is one of:
-#    x:name
-#    x:+name
-
-#      where name is a string which is matched against the category
-#      given in the VIR_LOG_INIT() at the top of each libvirt source
-#      file, e.g., "remote", "qemu", or "util.json" (the name in the
-#      filter can be a substring of the full category name, in order
-#      to match multiple similar categories), the optional "+" prefix
-#      tells libvirt to log stack trace for each message matching
-#      name, and x is the minimal level where matching messages should
-#      be logged:
-
+# of logs. The format for a filter is one of:
+#
+#    level:match
+#    level:+match
+#
+# where 'match' is a string which is matched against the category
+# given in the VIR_LOG_INIT() at the top of each libvirt source
+# file, e.g., "remote", "qemu", or "util.json". The 'match' in the
+# filter matches using shell wildcard syntax (see 'man glob(7)').
+# The 'match' is always treated as a substring match. IOW a match
+# string 'foo' is equivalent to '*foo*'.
+#
+# If 'match' contains the optional "+" prefix, it tells libvirt
+# to log stack trace for each message matching name.
+#
+# 'level' is the minimal level where matching messages should
+#  be logged:
+#
 #    1: DEBUG
 #    2: INFO
 #    3: WARNING
 #    4: ERROR
 #
-# Multiple filters can be defined in a single @filters, they just need to be
-# separated by spaces. Note that libvirt performs "first" match, i.e. if
-# there are concurrent filters, the first one that matches will be applied,
-# given the order in log_filters.
+# Multiple filters can be defined in a single @log_filters, they just need
+# to be separated by spaces. Note that libvirt performs "first" match, i.e.
+# if there are concurrent filters, the first one that matches will be applied,
+# given the order in @log_filters.
+#
+# A typical need is to capture information from a hypervisor driver,
+# public API entrypoints and some of the utility code. Some utility
+# code is very verbose and is generally not desired. Taking the QEMU
+# hypervisor as an example, a suitable filter string for debugging
+# might be to turn off object, json & event logging, but enable the
+# rest of the util code:
 #
-# e.g. to only get warning or errors from the remote layer and only errors
-# from the event layer:
-#log_filters="3:remote 4:event"
+#log_filters="1:qemu 1:libvirt 4:object 4:json 4:event 1:util"
 
 # Logging outputs:
 # An output is one of the places to save logging information
 # The format for an output can be:
-#    x:stderr
+#    level:stderr
 #      output goes to stderr
-#    x:syslog:name
+#    level:syslog:name
 #      use syslog for the output and use the given name as the ident
-#    x:file:file_path
+#    level:file:file_path
 #      output to a file, with the given filepath
-#    x:journald
+#    level:journald
 #      output to journald logging system
-# In all case the x prefix is the minimal level, acting as a filter
+# In all cases 'level' is the minimal priority, acting as a filter
 #    1: DEBUG
 #    2: INFO
 #    3: WARNING

src/remote/test_libvirtd.aug.in

@@ -49,7 +49,7 @@ module Test_libvirtd =
         { "admin_max_queued_clients" = "5" }
         { "admin_max_client_requests" = "5" }
         { "log_level" = "3" }
-        { "log_filters" = "3:remote 4:event" }
+        { "log_filters" = "1:qemu 1:libvirt 4:object 4:json 4:event 1:util" }
         { "log_outputs" = "3:syslog:libvirtd" }
         { "audit_level" = "2" }
         { "audit_logging" = "1" }