shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-03-28 02:50:16 +03:00
Code

man: add a whole section detailing journal stdout/stderr stream logging

Browse Source 
Details about EPIPE/SIGPIPE handling, metadata and more.

Fixes: #6620
This commit is contained in:
Lennart Poettering 2017-09-15 14:17:32 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent fa69a4c74b
commit 157148d6d3
1 changed files with 48 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
man/systemd-journald.service.xml
View File

@ -70,19 +70,18 @@
<itemizedlist>
<listitem><para>Kernel log messages, via kmsg</para></listitem>
<listitem><para>Simple system log messages, via the libc
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<listitem><para>Simple system log messages, via the <filename>libc</filename> <citerefentry
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call</para></listitem>
<listitem><para>Structured system log messages via the native
Journal API, see
<citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry></para></listitem>
<listitem><para>Standard output and standard error of system
services</para></listitem>
<listitem><para>Standard output and standard error of service units. For further details see
below.</para></listitem>
<listitem><para>Audit records, via the audit
subsystem</para></listitem>
<listitem><para>Audit records, originating from the kernel audit subsystem</para></listitem>
</itemizedlist>
<para>The daemon will implicitly collect numerous metadata fields
@ -111,6 +110,49 @@ systemd-tmpfiles --create --prefix /var/log/journal</programlisting>
for information about the configuration of this service.</para>
</refsect1>
<refsect1>
<title>Stream logging</title>
<para>The systemd service manager invokes all service processes with standard output and standard error connected
to the journal by default. This behaviour may be altered via the
<varname>StandardOutput=</varname>/<varname>StandardError=</varname> unit file settings, see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The
journal converts the log byte stream received this way into individual log records, splitting the stream at newline
(<literal>\n</literal>, ASCII <constant>10</constant>) and <constant>NUL</constant> bytes.</para>
<para>If <filename>systemd-journald.service</filename> is stopped, the stream connections associated with all
services are terminated. Further writes to those streams by the service will result in <constant>EPIPE</constant>
errors. In order to react gracefully in this case it is recommended that programs logging to standard output/error
ignore such errors. If the the <constant>SIGPIPE</constant> UNIX signal handler is not blocked or turned off, such
write attempts will also result in such process signals being generated, see
<citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. To mitigate this issue,
systemd service manager explicitly turns off the <constant>SIGPIPE</constant> signal for all invoked processes by
default (this may be changed for each unit individually via the <varname>IgnoreSIGPIPE=</varname> option, see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details). After the standard output/standard error streams have been terminated they may not be recovered until the
services they are associated with are restarted. Note that during normal operation,
<filename>systemd-journald.service</filename> stores copies of the file descriptors for those streams in the
service manager. If <filename>systemd-journald.service</filename> is restarted using <command>systemctl
restart</command> or equivalent operation instead of a pair of separate <command>systemctl stop</command> and
<command>systemctl start</command> commands (or equivalent operations), these stream connections are not terminated
and survive the restart. It is thus safe to restart <filename>systemd-journald.service</filename>, but stopping it
is not recommended.</para>
<para>Note that the log record metadata for records transferred via such standard output/error streams reflect the
metadata of the peer the stream was originally created for. If the stream connection is passed on to other
processes (such as further child processes forked off the main service process), the log records will not reflect
their metadata, but will continue to describe the original process. This is different from the other logging
transports listed above, which are inherently record based and where the metadata is always associated with the
individual record.</para>
<para>In addition to the the implicit standard output/error logging of services, stream logging is also available
via the <citerefentry><refentrytitle>systemd-cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> command
line tool.</para>
<para> Currently, the number of parallel log streams <filename>systemd-journald</filename> will accept is limited
to 4096.</para>
</refsect1>
<refsect1>
<title>Signals</title>