"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-<refentry id="systemd.journal-fields">
+<refentry id="systemd.journal-fields" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd.journal-fields</title>
<para>Entries in the journal (as written by
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
- resemble a UNIX process environment block in syntax but with fields that may include binary data.
- Primarily, fields are formatted UTF-8 text strings, and binary encoding is used only where formatting as
- UTF-8 text strings makes little sense. New fields may freely be defined by applications, but a few fields
- have special meanings. All fields with special meanings are optional. In some cases, fields may appear
- more than once per entry.</para>
+ resemble a UNIX process environment block in syntax but with field values that may include binary data,
+ and with non-unique field names permitted. Primarily, field values are formatted UTF-8 text strings —
+ binary encoding is used only where formatting as UTF-8 text strings makes little sense. New fields may
+ freely be defined by applications, but a few fields have special meanings, which are listed
+ below. Typically, fields may only appear once per log entry, however there are special exceptions: some
+ fields may appear more than once per entry, in which case this is explicitly mentioned below. Even though
+ the logging subsystem makes no restrictions on which fields to accept non-unique values for, it is
+ strongly recommended to avoid relying on this for the fields listed below (except where listed otherwise,
+ as mentioned) in order to avoid unnecessary incompatibilities with other applications.</para>
</refsect1>
<refsect1>
<varlistentry>
<term><varname>MESSAGE=</varname></term>
<listitem>
- <para>The human-readable message string for this entry. This
- is supposed to be the primary text shown to the user. It is
- usually not translated (but might be in some cases), and is
- not supposed to be parsed for metadata.</para>
+ <para>The human-readable message string for this entry. This is supposed to be the primary text
+ shown to the user. It is usually not translated (but might be in some cases), and is not supposed
+ to be parsed for metadata. In order to encode multiple lines in a single log entry, separate them
+ by newline characters (ASCII code 10), but encode them as a single <varname>MESSAGE=</varname>
+ field. Do not add multiple values of this field type to the same entry (also see above), as
+ consuming applications generally do not expect this and are unlikely to show all values in that
+ case.</para>
</listitem>
</varlistentry>
<term><varname>DOCUMENTATION=</varname></term>
<listitem>
<para>A documentation URL with further information about the topic of the log message. Tools such
- as <command>journalctl</command> will include a hyperlink to an URL specified this way in their
- output. Should be a <literal>http://</literal>, <literal>https://</literal>,
+ as <command>journalctl</command> will include a hyperlink to a URL specified this way in their
+ output. Should be an <literal>http://</literal>, <literal>https://</literal>,
<literal>file:/</literal>, <literal>man:</literal> or <literal>info:</literal> URL.</para>
</listitem>
</varlistentry>
<para>The numeric thread ID (TID) the log message originates from.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><varname>UNIT=</varname></term>
+ <term><varname>USER_UNIT=</varname></term>
+ <listitem>
+ <para>The name of a unit. Used by the system and user managers when logging about specific
+ units.</para>
+
+ <para>When <option>--unit=<replaceable>name</replaceable></option> or
+ <option>--user-unit=<replaceable>name</replaceable></option> are used with
+ <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, a
+ match pattern that includes <literal>UNIT=<replaceable>name</replaceable>.service</literal> or
+ <literal>USER_UNIT=<replaceable>name</replaceable>.service</literal> will be generated.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<varlistentry>
<term><varname>_STREAM_ID=</varname></term>
<listitem>
- <para>Only applies to <literal>_TRANSPORT=stdout</literal> records: specifies a randomized 128bit ID assigned
+ <para>Only applies to <literal>_TRANSPORT=stdout</literal> records: specifies a randomized 128-bit ID assigned
to the stream connection when it was first created. This ID is useful to reconstruct individual log streams
from the log records: all log records carrying the same stream ID originate from the same stream.</para>
</listitem>
for details about journal namespaces.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>_RUNTIME_SCOPE=</varname></term>
+
+ <listitem><para>A string field that specifies the runtime scope in which the message was logged. If
+ <literal>initrd</literal>, the log message was processed while the system was running inside the
+ initrd. If <literal>system</literal>, the log message was generated after the system switched
+ execution to the host root filesystem.</para></listitem>
+ </varlistentry>
</variablelist>
</refsect1>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><varname>__SEQNUM=</varname></term>
+ <term><varname>__SEQNUM_ID=</varname></term>
+
+ <listitem><para>The sequence number (and associated sequence number ID) of this journal entry in the
+ journal file it originates from. See
+ <citerefentry><refentrytitle>sd_journal_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for details.</para></listitem>
+ </varlistentry>
</variablelist>
</refsect1>
projects / thirdparty / systemd.git / blobdiff