Re: [PATCH 5/8] kbase: debuglogs: Add a section describing log outputs and filters
On Mon, Jan 17, 2022 at 04:39:13PM +0100, Peter Krempa wrote:
Outline what the given settings influence.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/kbase/debuglogs.rst | 67 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 67 insertions(+)
diff --git a/docs/kbase/debuglogs.rst b/docs/kbase/debuglogs.rst
index cba57e020d..9ba39b9f85 100644
--- a/docs/kbase/debuglogs.rst
+++ b/docs/kbase/debuglogs.rst
@@ -17,6 +17,73 @@ Moreover, libvirt catches stderr of all running domains. These can be
useful as
well.
+Logging settings in libvirt
+===========================
+
+Log levels
+----------
+
+Libvirt produces log entries in 4 priority levels; higher priority level meaning
"Libvirt log messages are classified into 4 priority levels;...
also
"the higher the priority level, the less is the volume of produced messages"
+more severe log entries, which in turn means less of them. The log
level are
+used by `Log outputs`_ and `Log filters`_ below):
"The log level setting is controlled by the 'log_filters' and
'log_outputs'
settings explained in the `Log outputs`_ and `Log filters`_ sections
respectively."
+
+ * ``1: DEBUG``
+ * ``2: INFO``
+ * ``3: WARNING``
+ * ``4: ERROR``
+
+For debugging it's necessary to capture ``DEBUG`` level entries as the name
s/capture/capture the
+implies.
+
+Log outputs
+-----------
+
+Log outputs describe where the log messages are being recorded. The outputs
+are described by a space-separated list of tuples in the following format:
+
+::
+
+ level:output
+
+``level`` refers to the minimum priority level of entries recorded in the output.
+
+``output`` is one of the following:
+
+ ``file:FILENAME``
+ Logging messages are appended to FILENAME.
+
+ ``journald``
+ Logging goes to the ``journald`` logging daemon.
+
+ ``stderr``
+ Logging goes to the standard error output stream of the libvirt daemon.
+
+ ``syslog:name``
+ Logging goes to syslogd. ``name`` is used to identify the entries.
+
+The default output on systems running ``journald`` is ``3:journald``. Note that
+``journald`` can trottle the amount of logs per process so for capturing debug
s/trottle/throttle
s/for capturing/in order to capture
+logs of libvirt daemons a file output should be used in addition to
the output
+to the logging daemon e.g.:
"logs of a libvirt daemon should go to a file instead (in addition to the
original logging daemon), e.g.:"
+
+::
+
+ "1:file:/var/log/libvirt/libvirtd.log 3:journald"
+
+
+Log filters
+-----------
+
+Log filters allow to avoid logging of messages which are not relevant to the
"Log filters, as the name suggest, help filtering out messages which are
irrelevant to the cause."
+cause. The log filters is a space-separated list of tuples in the
format
+``level:identifer`` and limits messages which match ``identifier`` to the
+configured log level. Identifier supports globbing patterns such as ``*``.
"...list of tuples using the ``level:identifier`` format. Each filter defined
this way will then limit messages coming from a module matching the
``identifier`` pattern (accepts globs too) to the given ``level``."
+
+As ``identifier`` is based on internal naming of modules, the best approach is
s/best approach/preferred way of configuring your filters is to start with the
`Example filter settings`_.
+to select one of `Example filter settings`_. It's also always
better to have
+more information than lack something important.
"The rule of thumb here is to have more logs rather than less and miss something
important".
Only stylistic nitpicks....:
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>