"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>
<title>Address Fields</title>
<para>During serialization into external formats, such as the
- <ulink
- url="https://www.freedesktop.org/wiki/Software/systemd/export">Journal
- Export Format</ulink> or the <ulink
- url="https://www.freedesktop.org/wiki/Software/systemd/json">Journal
- JSON Format</ulink>, the addresses of journal entries are
+ <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink>
+ or the
+ <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format">Journal JSON Format</ulink>,
+ the addresses of journal entries are
serialized into fields prefixed with double underscores. Note that
these are not proper fields when stored in the journal but for
addressing metadata of entries. They cannot be written as part of
</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