[libvirt] [PATCH v2 4/4] log: update docs for daemons to improve user understanding
John Ferlan
jferlan at redhat.com
Mon Apr 30 15:06:04 UTC 2018
On 04/23/2018 08:28 AM, Daniel P. Berrangé wrote:
> 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.
>
> Signed-off-by: Daniel P. Berrangé <berrange at redhat.com>
> ---
> src/locking/test_virtlockd.aug.in | 2 +-
> src/locking/virtlockd.conf | 65 ++++++++++++++++++++++++++-----------
> src/logging/test_virtlogd.aug.in | 2 +-
> src/logging/virtlogd.conf | 68 +++++++++++++++++++++++++++------------
> src/remote/libvirtd.conf | 68 ++++++++++++++++++++++++---------------
> src/remote/test_libvirtd.aug.in | 2 +-
> 6 files changed, 140 insertions(+), 67 deletions(-)
>
> diff --git a/src/locking/test_virtlockd.aug.in b/src/locking/test_virtlockd.aug.in
> index ad75286be6..f2f6979ef5 100644
> --- a/src/locking/test_virtlockd.aug.in
> +++ b/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" }
> diff --git a/src/locking/virtlockd.conf b/src/locking/virtlockd.conf
> index 1a2b27d0b9..20085de9dd 100644
> --- a/src/locking/virtlockd.conf
> +++ b/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 a substring match. IOW a match
s/treated a/treated as a/
> +# 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 @filters, they just need to be
Probably should be log_filters not @filters
> +# 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"
> #
> diff --git a/src/logging/test_virtlogd.aug.in b/src/logging/test_virtlogd.aug.in
> index 744f3246af..a29e7e3730 100644
> --- a/src/logging/test_virtlogd.aug.in
> +++ b/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" }
> diff --git a/src/logging/virtlogd.conf b/src/logging/virtlogd.conf
> index c22b7737ef..8e3e977cdd 100644
> --- a/src/logging/virtlogd.conf
> +++ b/src/logging/virtlogd.conf
> @@ -8,48 +8,76 @@
>
> # 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 a substring match. IOW a match
s/treated a/treated as a/
> +# 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 @filters, they just need to be
Probably should be log_filters not @filters
> +# 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"
> #
> diff --git a/src/remote/libvirtd.conf b/src/remote/libvirtd.conf
> index 9c0080dc06..8cee30832a 100644
> --- a/src/remote/libvirtd.conf
> +++ b/src/remote/libvirtd.conf
> @@ -338,28 +338,39 @@
>
> # 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 a substring match. IOW a match
s/treated a/treated as a/
> +# 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
For consistency, the same @filters change to log_filters.
> @@ -370,22 +381,27 @@
> # there are concurrent filters, the first one that matches will be applied,
> # given the order in log_filters.
> #
> -# 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"
> +# 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:
> +#
> +#log_filters="1:qemu 1:libvirt 4:object 4:json 4:event 1:util"
FWIW: I've used 1:conf and 3:file (before 1:util) as a suggestion I
found in the wild... The nice part about 3:file is it shows that 3:file
would be used before 1:util. IDC whether or not it's added, but thought
it may be interesting nonetheless.
with the "as a" used.... whether the @filters changes to log_filters is
your call.
Reviewed-by: John Ferlan <jferlan at redhat.com>
John
>
> # 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
> diff --git a/src/remote/test_libvirtd.aug.in b/src/remote/test_libvirtd.aug.in
> index 2bd7ec1bd6..527e3d7d0d 100644
> --- a/src/remote/test_libvirtd.aug.in
> +++ b/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" }
>
More information about the libvir-list
mailing list