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

[Daniel P. Berrangé]

On Mon, Apr 23, 2018 at 08:49:00AM +0200, Erik Skultety wrote:
> On Fri, Apr 20, 2018 at 05:56:39PM +0100, 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        | 70 +++++++++++++++++++++++++++----------
> >  src/logging/test_virtlogd.aug.in  |  2 +-
> >  src/logging/virtlogd.conf         | 73 ++++++++++++++++++++++++++++-----------
> >  src/remote/libvirtd.conf          | 70 +++++++++++++++++++++++--------------
> >  src/remote/test_libvirtd.aug.in   |  2 +-
> >  6 files changed, 150 insertions(+), 69 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..29cefbd74a 100644
> > --- a/src/locking/virtlockd.conf
> > +++ b/src/locking/virtlockd.conf
> > @@ -8,47 +8,79 @@
> >
> >  # 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
> 
> 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+.

Yeah, maybe I'll reword it to

   "Journald applies rate limiting of messages and so libvirt will
    ignore any logging level above 3, if journald is the current
    output."

as that better describes what we're doing.

> > +# WARNING: will be logged.
> > +#
> > +# 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
> 
> 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...

In the majority of debugging scenarios I see with the OpenStack project from
a RHEL support POV, users just do whatever our support / developer engineers
tell them todo and don't try to figure it out themselves.

Even if we had a man page which listed each known logging category, how would
users know which sets of categories are relevant to their problem ? It usually
needs someone who knows the code to make recommendations.

I'd kind of like to figure out a way to be able to extract a list of all
logging categories at runtime from the daemon, but its hard because the
loggnig code doesn't know about categories until a log message is sent.

One idea I had was for VIR_LOG_INIT() to create a function that was marked
with __attribute__((constructor)) that would call virLogRegisterCategory()
so we can build a list of all cats immediately.  Then the virt-admin tool
could list them too

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|