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

On Fri, Apr 20, 2018 at 05:56:39PM +0100, Daniel P. Berrangé wrote: So is it really worth mentioning to use debug with journal, since there are only limitations? How about encouraging to use e.g. file for debug logs and journald for 3+. What about users who use libvirt from a distro package, they don't necessary need to have the sources installed, more importantly they shouldn't really have to care about the sources to successfully set up logging. Reporting the categories in some consumable way that could be generated automatically during libvirt build and shipped afterwards has been on my radar for quite some time... > +# filter matches using shell wildcard syntax (see 'man glob(7)'). > +# The 'match' is always treated 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 @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. 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: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. > -# e.g. to log all warnings and errors to syslog under the virtlockd ident: > +# 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 libvirtd 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..f2078a730c 100644 > --- a/src/logging/virtlogd.conf > +++ b/src/logging/virtlogd.conf > @@ -8,49 +8,80 @@ > > # 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 may employ rate limiting of the messages logged > +# WARNING: and thus lock up the libvirt daemon. To use the debug > +# WARNING: level with journald you have to specify it explicitly in > +# WARNING: 'log_outputs', otherwise only information level messages > +# filter matches using shell wildcard syntax (see 'man glob(7)'). > +# The 'match' is always treated 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 @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. 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: ^This paragraph is a copy-paste from virtlockd bits, so this needs to be fixed. "under libvirt indent" - this doesn't reflect the reality below... there's one more occurrence of this within this patch... Erik