man: reword documentation about logging level and domains in `man NetworkManager.conf`

People keep reporting bugs with `level=DEBUG` or set to a certain
domains. That is generally not useful. Complete debug logs should be
collected, we can always ignore what we don't care about, but we might
miss important information by limiting what we collect.

Try to make that clearer in the manual.

1 files changed, 64 insertions, 13 deletions

diff --git a/man/NetworkManager.conf.xml b/man/NetworkManager.conf.xml
index c1afaad050..cb6b40afa0 100644
--- a/man/NetworkManager.conf.xml
+++ b/man/NetworkManager.conf.xml
@@ -622,9 +622,40 @@ unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth
 
   <refsect1>
     <title><literal>logging</literal> section</title>
-    <para>This section controls NetworkManager's logging.  Any
-    settings here are overridden by the <option>--log-level</option>
-    and <option>--log-domains</option> command-line options.</para>
+    <para>
+    This section controls NetworkManager's logging.
+    Logging is very important to understand what NetworkManager is doing.
+    When you report a bug, do not unnecessarily filter or limit the log file.
+    Just enable <literal>level=TRACE</literal> and <literal>domains=ALL</literal>
+    to collect everything.
+    </para>
+
+    <para>
+    Any settings here are overridden by the <option>--log-level</option>
+    and <option>--log-domains</option> command-line options.
+    Logging can also be reconfigured at runtime with
+    <command>nmcli general logging level "$LEVEL" domains "$DOMAINS"</command>.
+    However, often it is interesting to get a complete log from the
+    start. Especially, when debugging an issue, enable debug logging
+    in NetworkManager.conf and restart the service to enable verbose logging
+    early on.
+    </para>
+
+    <para>
+    NetworkManager's logging aims not to contain private sensitive data
+    and you should be fine sharing the debug logs. Still, there will
+    be IP addresses and your network setup, if you consider that private
+    then review the log before sharing. Do not mangle the logfile in
+    a way that distorts the meaning too much.
+    </para>
+
+    <para>
+    NetworkManager uses syslog or systemd-journald, depending on configuration.
+    In any case, debug logs are verbose and might be rate limited
+    or filtered by the logging daemon. For systemd-journald, see
+    <literal>RateLimitIntervalSec</literal> and <literal>RateLimitBurst</literal>
+    in <literal>journald.conf</literal> manual for how to disable that.
+    </para>
 
     <para>
       <variablelist>
@@ -633,18 +664,33 @@ unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth
           <listitem><para>The default logging verbosity level.
           One of <literal>OFF</literal>, <literal>ERR</literal>,
           <literal>WARN</literal>, <literal>INFO</literal>,
-          <literal>DEBUG</literal>, <literal>TRACE</literal>.  The ERR
-          level logs only critical errors.  WARN logs warnings that may
-          reflect operation. INFO logs various informational messages that
-          are useful for tracking state and operations.  DEBUG enables
-          verbose logging for debugging purposes. TRACE enables even more
-          verbose logging then DEBUG level.  Subsequent levels also log
-          all messages from earlier levels; thus setting the log level
-          to INFO also logs error and warning messages.</para></listitem>
+          <literal>DEBUG</literal>, <literal>TRACE</literal>,
+          in order of verbosity.
+          </para>
+          <para>
+          <literal>OFF</literal> disables all logging. <literal>INFO</literal>
+          is the default verbosity for regular operation. <literal>TRACE</literal>
+          is for debugging.
+          </para>
+          <para>
+          The other levels are in most cases not useful. For example, <literal>DEBUG</literal>
+          is between <literal>TRACE</literal> and <literal>INFO</literal>, but it's too
+          verbose for regular operation and lacks possibly interesting messages for debugging.
+          Almost always, when debugging an issue or reporting a bug, collect full
+          level <literal>TRACE</literal> logs to get the full picture.
+          </para>
+          </listitem>
         </varlistentry>
         <varlistentry>
           <term><varname>domains</varname></term>
-          <listitem><para>The following log domains are available:
+          <listitem>
+          <para>Filter the messages by their topic. When debugging
+          an issue, it's better to collect all logs (<literal>ALL</literal> domain)
+          upfront. The unnecessary parts can always be ignored
+          later.
+          </para>
+          <para>In the uncommon case to tune out certain topics, the following log
+          domains are available:
           PLATFORM, RFKILL, ETHER, WIFI, BT, MB, DHCP4, DHCP6, PPP,
           WIFI_SCAN, IP4, IP6, AUTOIP4, DNS, VPN, SHARING, SUPPLICANT,
           AGENTS, SETTINGS, SUSPEND, CORE, DEVICE, OLPC, WIMAX,
@@ -655,7 +701,12 @@ unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth
           ALL, DEFAULT, DHCP, IP.</para>
           <para>You can specify per-domain log level overrides by
           adding a colon and a log level to any domain. E.g.,
-          "<literal>WIFI:DEBUG,WIFI_SCAN:OFF</literal>".</para></listitem>
+          "<literal>WIFI:DEBUG,WIFI_SCAN:OFF</literal>".
+          Another example is <literal>ALL,VPN_PLUGIN:TRACE</literal>
+          to enable all the logging there is (see about <literal>VPN_PLUGIN</literal>
+          below).
+          </para>
+          </listitem>
         </varlistentry>
         <varlistentry>
           <para>Domain descriptions: