man: describe various logging configuration variables

Fixes #17484.

This patch affects systemctl(1), as well as all man pages that include
all of common-variables.xml, i.e. most of our command line tools.

2 files changed, 78 insertions, 0 deletions

diff --git a/man/common-variables.xml b/man/common-variables.xml
index 809a9084a2..b875e38d39 100644
--- a/man/common-variables.xml
+++ b/man/common-variables.xml
@@ -7,6 +7,79 @@
   <title>Environment</title>
 
   <variablelist class='environment-variables'>
+    <varlistentry id='log-level'>
+      <term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
+
+      <listitem><para>The maximum log level of emitted messages (messages with a higher log level, i.e. less
+      important ones, will be suppressed). Either one of (in order of decreasing importance)
+      <constant>emerg</constant>, <constant>alert</constant>, <constant>crit</constant>,
+      <constant>err</constant>, <constant>warning</constant>, <constant>notice</constant>,
+      <constant>info</constant>, <constant>debug</constant>, or an integer in the range 0…7. See
+      <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      for more information.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-color'>
+      <term><varname>$SYSTEMD_LOG_COLOR</varname></term>
+
+      <listitem><para>A boolean. If true, messages written to the tty will be colored according to
+      priority.</para>
+
+      <para>This setting is only useful when messages are written directly to the terminal, because
+      <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
+      other tools that display logs will color messages based on the log level on their own.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-time'>
+      <term><varname>$SYSTEMD_LOG_TIME</varname></term>
+
+      <listitem><para>A boolean. If true, log messages will be prefixed with a timestamp.</para>
+
+      <para>This setting is only useful when messages are written directly to the terminal or a file, because
+      <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
+      other tools that display logs will attach timestamps based on the entry metadata on their own.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-location'>
+      <term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
+
+      <listitem><para>A boolean. If true, messages will be prefixed with a filename and line number
+      in the source code where the message originates.</para>
+
+      <para>Note that the log location is often attached as metadata to journal entries anyway. Including it
+      directly in the message text can nevertheless be convenient when debugging programs.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-tid'>
+      <term><varname>$SYSTEMD_LOG_TID</varname></term>
+
+      <listitem><para>A boolean. If true, messages will be prefixed with the current numerical thread ID
+      (TID).</para>
+
+      <para>Note that the this information is attached as metadata to journal entries anyway. Including it
+      directly in the message text can nevertheless be convenient when debugging programs.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry id='log-target'>
+      <term><varname>$SYSTEMD_LOG_TARGET</varname></term>
+
+      <listitem><para>The destination for log messages. One of <constant>console</constant> (log to the
+      attached tty), <constant>console-prefixed</constant> (log to the attached tty but with prefixes
+      encoding the log level and "facility", see <citerefentry
+      project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <constant>kmsg</constant> (log to the kernel circular log buffer), <constant>journal</constant> (log to
+      the journal), <constant>journal-or-kmsg</constant> (log to the journal if available, and to kmsg
+      otherwise), <constant>auto</constant> (dermine the appropriate log target automatically, the default),
+      <constant>null</constant> (disable log output).</para>
+      <!-- <constant>syslog</constant>, <constant>syslog-or-kmsg</constant> are deprecated -->
+      </listitem>
+    </varlistentry>
+
     <varlistentry id='pager'>
       <term><varname>$SYSTEMD_PAGER</varname></term>
 
diff --git a/man/systemctl.xml b/man/systemctl.xml
index 62bc7fe832..8402b9508a 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -2407,6 +2407,11 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
         </para></listitem>
       </varlistentry>
     </variablelist>
+    <xi:include href="common-variables.xml" xpointer="log-level"/>
+    <xi:include href="common-variables.xml" xpointer="log-color"/>
+    <xi:include href="common-variables.xml" xpointer="log-time"/>
+    <xi:include href="common-variables.xml" xpointer="log-location"/>
+    <xi:include href="common-variables.xml" xpointer="log-target"/>
     <xi:include href="common-variables.xml" xpointer="pager"/>
     <xi:include href="common-variables.xml" xpointer="less"/>
     <xi:include href="common-variables.xml" xpointer="lesscharset"/>