Re: [PATCH v2 4/4] log: update docs for daemons to improve user understanding

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 




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@xxxxxxxxxx>
> ---
>  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@xxxxxxxxxx>

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" }
> 

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux