shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-23 17:34:00 +03:00
Code
293b9aa3eb
systemd-stable/man/systemd.journal-fields.xml

609 lines
25 KiB
XML
Raw Normal View History

man: document special journal fields
2012-04-04 00:31:48 +04:00
<?xml version='1.0'?> <!--*-nxml-*-->
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 16:40:58 +03:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-18 20:47:44 +03:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: document special journal fields
2012-04-04 00:31:48 +04:00
<refentry id="systemd.journal-fields">
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<refentryinfo>
<title>systemd.journal-fields</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd.journal-fields</refentrytitle>
<manvolnum>7</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd.journal-fields</refname>
<refpurpose>Special journal fields</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
man: add reference to journald man page from systemd.journal-fields(7) We had none so far. Which is weird.
2019-11-27 23:29:32 +03:00
<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>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
<refsect1>
<title>User Journal Fields</title>
<para>User fields are fields that are directly passed from clients
and stored in the journal.</para>
<variablelist class='journal-directives'>
<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
man: typo fixes
2015-07-26 00:15:05 +03:00
not supposed to be parsed for metadata.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>MESSAGE_ID=</varname></term>
<listitem>
tree-wide: drop all references to "journalctl --new-id128" Let's advertise "systemd-id128 new" instead.
2018-10-02 17:43:54 +03:00
<para>A 128-bit message identifier ID for recognizing certain message types, if this is desirable. This
should contain a 128-bit ID formatted as a lower-case hexadecimal string, without any separating dashes or
suchlike. This is recommended to be a UUID-compatible ID, but this is not enforced, and formatted
differently. Developers can generate a new ID for this purpose with <command>systemd-id128 new</command>.
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PRIORITY=</varname></term>
<listitem>
<para>A priority value between 0 (<literal>emerg</literal>)
and 7 (<literal>debug</literal>) formatted as a decimal
string. This field is compatible with syslog's priority
concept.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>CODE_FILE=</varname></term>
<term><varname>CODE_LINE=</varname></term>
<term><varname>CODE_FUNC=</varname></term>
<listitem>
<para>The code location generating this message, if known.
Contains the source filename, the line number and the
function name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ERRNO=</varname></term>
<listitem>
<para>The low-level Unix error number causing this entry, if
any. Contains the numeric value of
<citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
formatted as a decimal string.</para>
</listitem>
</varlistentry>
man: document INVOCATION_ID and USER_INVOCATION_ID journal fields
2019-12-12 07:50:10 +03:00
<varlistentry>
<term><varname>INVOCATION_ID=</varname></term>
<term><varname>USER_INVOCATION_ID=</varname></term>
<listitem>
<para>A randomized, unique 128-bit ID identifying each runtime cycle of the unit. This is different from
<varname>_SYSTEMD_INVOCATION_ID</varname> in that it is only used for messages coming from systemd code
(e.g. logs from the system/user manager or from forked processes performing systemd-related setup).</para>
</listitem>
</varlistentry>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term><varname>SYSLOG_FACILITY=</varname></term>
<term><varname>SYSLOG_IDENTIFIER=</varname></term>
<term><varname>SYSLOG_PID=</varname></term>
journal: store the original timestamp as SYSLOG_TIMESTAMP= This is useful if someone wants to recreate the original syslog datagram. We already include timestamp information as _SOURCE_REALTIME_TIMESTAMP=, and in normal use that timestamp, converted back to the form used by syslog (Mth dd HH:MM:SS) would usually give the value. But there are various circumstances where this might not be true. Most obviously, if the datagram is sent a bit later after being prepared, the time is rounded to the nearest second, and it might be off. This is especially bad around New Year when the syslog timestamp wraps around. Then the same timezone and locale need to be used to recreate the original timestamp. In the end doing this reliably is complicated, and it seems much easier to just unconditionally include the original timestamp. If the original timestamp cannot be located, we store the full log line. This way, it should be always possible to recreate the original input. Example: MESSAGE=x SYSLOG_TIMESTAMP=Sep 15 15:07:58 SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y _PID=3318 _SOURCE_REALTIME_TIMESTAMP=1530743976393553 Fixes #2398.
2018-07-05 01:17:55 +03:00
<term><varname>SYSLOG_TIMESTAMP=</varname></term>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<listitem>
journal: store the original timestamp as SYSLOG_TIMESTAMP= This is useful if someone wants to recreate the original syslog datagram. We already include timestamp information as _SOURCE_REALTIME_TIMESTAMP=, and in normal use that timestamp, converted back to the form used by syslog (Mth dd HH:MM:SS) would usually give the value. But there are various circumstances where this might not be true. Most obviously, if the datagram is sent a bit later after being prepared, the time is rounded to the nearest second, and it might be off. This is especially bad around New Year when the syslog timestamp wraps around. Then the same timezone and locale need to be used to recreate the original timestamp. In the end doing this reliably is complicated, and it seems much easier to just unconditionally include the original timestamp. If the original timestamp cannot be located, we store the full log line. This way, it should be always possible to recreate the original input. Example: MESSAGE=x SYSLOG_TIMESTAMP=Sep 15 15:07:58 SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y _PID=3318 _SOURCE_REALTIME_TIMESTAMP=1530743976393553 Fixes #2398.
2018-07-05 01:17:55 +03:00
<para>Syslog compatibility fields containing the facility (formatted as
decimal string), the identifier string (i.e. "tag"), the client PID, and
the timestamp as specified in the original datagram. (Note that the tag is
usually derived from glibc's
<varname>program_invocation_short_name</varname> variable, see
man: fix a bunch of links All hail linkchecker!
2015-03-14 05:22:39 +03:00
<citerefentry project='die-net'><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para>
man: note that journal does not validate syslog fields
2019-05-14 11:45:08 +03:00
<para>Note that the journal service does not validate the values of any structured
journal fields whose name is not prefixed with an underscore, and this includes any
syslog related fields such as these. Hence, applications that supply a facility, PID,
or log level are expected to do so properly formatted, i.e. as numeric integers formatted
as decimal strings.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
journal: store the original syslog input as SYSLOG_RAW= This allows the original stream to be recreated and/or verified. The new field is written if any stripping was done or if the input message contained embeded NULs. $ printf '<13>Sep 15 15:07:58 HOST: x\0y' | nc -w1 -u -U /run/systemd/journal/dev-log $ journalctl -o json-pretty ... { ... "MESSAGE" : "x", "SYSLOG_RAW" : [ 60, 49, 51, 62, 83, 101, 112, 32, 49, 53, 32, 49, 53, 58, 48, 55, 58, 53, 56, 32, 72, 79, 83, 84, 58, 32, 120, 0, 121 ] } $ journalctl -o export ... | cat -v ... MESSAGE=x SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y This mostly fixes #4863.
2018-06-08 14:52:22 +03:00
</varlistentry>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
journal: store the original syslog input as SYSLOG_RAW= This allows the original stream to be recreated and/or verified. The new field is written if any stripping was done or if the input message contained embeded NULs. $ printf '<13>Sep 15 15:07:58 HOST: x\0y' | nc -w1 -u -U /run/systemd/journal/dev-log $ journalctl -o json-pretty ... { ... "MESSAGE" : "x", "SYSLOG_RAW" : [ 60, 49, 51, 62, 83, 101, 112, 32, 49, 53, 32, 49, 53, 58, 48, 55, 58, 53, 56, 32, 72, 79, 83, 84, 58, 32, 120, 0, 121 ] } $ journalctl -o export ... | cat -v ... MESSAGE=x SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y This mostly fixes #4863.
2018-06-08 14:52:22 +03:00
<varlistentry>
<term><varname>SYSLOG_RAW=</varname></term>
<listitem>
<para>The original contents of the syslog line as received in the syslog
datagram. This field is only included if the <varname>MESSAGE=</varname>
journal: store the original timestamp as SYSLOG_TIMESTAMP= This is useful if someone wants to recreate the original syslog datagram. We already include timestamp information as _SOURCE_REALTIME_TIMESTAMP=, and in normal use that timestamp, converted back to the form used by syslog (Mth dd HH:MM:SS) would usually give the value. But there are various circumstances where this might not be true. Most obviously, if the datagram is sent a bit later after being prepared, the time is rounded to the nearest second, and it might be off. This is especially bad around New Year when the syslog timestamp wraps around. Then the same timezone and locale need to be used to recreate the original timestamp. In the end doing this reliably is complicated, and it seems much easier to just unconditionally include the original timestamp. If the original timestamp cannot be located, we store the full log line. This way, it should be always possible to recreate the original input. Example: MESSAGE=x SYSLOG_TIMESTAMP=Sep 15 15:07:58 SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y _PID=3318 _SOURCE_REALTIME_TIMESTAMP=1530743976393553 Fixes #2398.
2018-07-05 01:17:55 +03:00
field was modified compared to the original payload or the timestamp could
not be located properly and is not included in
man: remove unintentionally repetitive words
2021-11-11 12:01:19 +03:00
<varname>SYSLOG_TIMESTAMP=</varname>. Message truncation occurs when
journal: store the original timestamp as SYSLOG_TIMESTAMP= This is useful if someone wants to recreate the original syslog datagram. We already include timestamp information as _SOURCE_REALTIME_TIMESTAMP=, and in normal use that timestamp, converted back to the form used by syslog (Mth dd HH:MM:SS) would usually give the value. But there are various circumstances where this might not be true. Most obviously, if the datagram is sent a bit later after being prepared, the time is rounded to the nearest second, and it might be off. This is especially bad around New Year when the syslog timestamp wraps around. Then the same timezone and locale need to be used to recreate the original timestamp. In the end doing this reliably is complicated, and it seems much easier to just unconditionally include the original timestamp. If the original timestamp cannot be located, we store the full log line. This way, it should be always possible to recreate the original input. Example: MESSAGE=x SYSLOG_TIMESTAMP=Sep 15 15:07:58 SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y _PID=3318 _SOURCE_REALTIME_TIMESTAMP=1530743976393553 Fixes #2398.
2018-07-05 01:17:55 +03:00
the message contains leading or trailing whitespace (trailing and leading
journal: store the original syslog input as SYSLOG_RAW= This allows the original stream to be recreated and/or verified. The new field is written if any stripping was done or if the input message contained embeded NULs. $ printf '<13>Sep 15 15:07:58 HOST: x\0y' | nc -w1 -u -U /run/systemd/journal/dev-log $ journalctl -o json-pretty ... { ... "MESSAGE" : "x", "SYSLOG_RAW" : [ 60, 49, 51, 62, 83, 101, 112, 32, 49, 53, 32, 49, 53, 58, 48, 55, 58, 53, 56, 32, 72, 79, 83, 84, 58, 32, 120, 0, 121 ] } $ journalctl -o export ... | cat -v ... MESSAGE=x SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y This mostly fixes #4863.
2018-06-08 14:52:22 +03:00
whitespace is stripped), or it contains an embedded
<constant>NUL</constant> byte (the <constant>NUL</constant> byte and
anything after it is not included). Thus, the original syslog line is
either stored as <varname>SYSLOG_RAW=</varname> or it can be recreated
journal: store the original timestamp as SYSLOG_TIMESTAMP= This is useful if someone wants to recreate the original syslog datagram. We already include timestamp information as _SOURCE_REALTIME_TIMESTAMP=, and in normal use that timestamp, converted back to the form used by syslog (Mth dd HH:MM:SS) would usually give the value. But there are various circumstances where this might not be true. Most obviously, if the datagram is sent a bit later after being prepared, the time is rounded to the nearest second, and it might be off. This is especially bad around New Year when the syslog timestamp wraps around. Then the same timezone and locale need to be used to recreate the original timestamp. In the end doing this reliably is complicated, and it seems much easier to just unconditionally include the original timestamp. If the original timestamp cannot be located, we store the full log line. This way, it should be always possible to recreate the original input. Example: MESSAGE=x SYSLOG_TIMESTAMP=Sep 15 15:07:58 SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y _PID=3318 _SOURCE_REALTIME_TIMESTAMP=1530743976393553 Fixes #2398.
2018-07-05 01:17:55 +03:00
based on the stored priority and facility, timestamp, identifier, and the
message payload in <varname>MESSAGE=</varname>.
</para>
journal: store the original syslog input as SYSLOG_RAW= This allows the original stream to be recreated and/or verified. The new field is written if any stripping was done or if the input message contained embeded NULs. $ printf '<13>Sep 15 15:07:58 HOST: x\0y' | nc -w1 -u -U /run/systemd/journal/dev-log $ journalctl -o json-pretty ... { ... "MESSAGE" : "x", "SYSLOG_RAW" : [ 60, 49, 51, 62, 83, 101, 112, 32, 49, 53, 32, 49, 53, 58, 48, 55, 58, 53, 56, 32, 72, 79, 83, 84, 58, 32, 120, 0, 121 ] } $ journalctl -o export ... | cat -v ... MESSAGE=x SYSLOG_RAW ^]^@^@^@^@^@^@^@<13>Sep 15 15:07:58 HOST: x^@y This mostly fixes #4863.
2018-06-08 14:52:22 +03:00
</listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
man: briefly document the DOCUMENTATION= structure log field
2020-05-25 20:39:50 +03:00
<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
man: describe UNIT=/USER_UNIT= Fixes 17538.
2022-03-04 18:26:12 +03:00
output. Should be an <literal>http://</literal>, <literal>https://</literal>,
man: briefly document the DOCUMENTATION= structure log field
2020-05-25 20:39:50 +03:00
<literal>file:/</literal>, <literal>man:</literal> or <literal>info:</literal> URL.</para>
</listitem>
</varlistentry>
log: include TID= field in structred log output It always was the intention to expose this as trusted field _TID=, i.e. automatically determine it from journald via some SCM_xyz field or so, but this is never happened, and it's unlikely this will be added anytime soon to the kernel either, hence let's just generate this sender side, even if it means it's untrusted.
2020-09-29 14:07:07 +03:00
<varlistentry>
<term><varname>TID=</varname></term>
<listitem>
<para>The numeric thread ID (TID) the log message originates from.</para>
</listitem>
</varlistentry>
man: describe UNIT=/USER_UNIT= Fixes 17538.
2022-03-04 18:26:12 +03:00
<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>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</variablelist>
</refsect1>
<refsect1>
<title>Trusted Journal Fields</title>
<para>Fields prefixed with an underscore are trusted fields, i.e.
fields that are implicitly added by the journal and cannot be
altered by client code.</para>
<variablelist class='journal-directives'>
<varlistentry>
<term><varname>_PID=</varname></term>
<term><varname>_UID=</varname></term>
<term><varname>_GID=</varname></term>
<listitem>
<para>The process, user, and group ID of the process the
journal entry originates from formatted as a decimal
man: systemd.journal-fields: Note about originator PID (#5724)
2017-04-24 17:19:53 +03:00
string. Note that entries obtained via <literal>stdout</literal> or
<literal>stderr</literal> of forked processes will contain credentials valid for a parent
process (that initiated the connection to <command>systemd-journald</command>).</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_COMM=</varname></term>
<term><varname>_EXE=</varname></term>
<term><varname>_CMDLINE=</varname></term>
<listitem>
<para>The name, the executable path, and the command line of
the process the journal entry originates from.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_CAP_EFFECTIVE=</varname></term>
<listitem>
<para>The effective
<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
of the process the journal entry originates from.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_AUDIT_SESSION=</varname></term>
<term><varname>_AUDIT_LOGINUID=</varname></term>
<listitem>
<para>The session and login UID of the process the journal
entry originates from, as maintained by the kernel audit
subsystem.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_SYSTEMD_CGROUP=</varname></term>
man: de-emphasize journal field _SYSTEMD_SESSION See previous commit message.
2017-09-17 16:51:49 +03:00
<term><varname>_SYSTEMD_SLICE=</varname></term>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<term><varname>_SYSTEMD_UNIT=</varname></term>
<term><varname>_SYSTEMD_USER_UNIT=</varname></term>
journalctl: Make journalctl --user-unit= match on _SYSTEMD_USER_SLICE journalctl --unit= already did this, and allows you to tail all the logs for a certain slice easily. It seemed only natural to make --user-unit behave in a similar way. The _SYSTEMD_USER_SLICE field was not documented as being added by journald, so I have added that to the documentation too. Furthermore, I have documented the existing behaviour of --unit= and the new behaviour of --user-unit= The behaviour was actually not documented before, so I am also OK with removing the match for the --unit= command instead. The user would then have to manually provide _SYSTEMD_SLICE= filter to journalctl in both cases. Both options work for me.
2019-08-12 20:36:56 +03:00
<term><varname>_SYSTEMD_USER_SLICE=</varname></term>
man: de-emphasize journal field _SYSTEMD_SESSION See previous commit message.
2017-09-17 16:51:49 +03:00
<term><varname>_SYSTEMD_SESSION=</varname></term>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<term><varname>_SYSTEMD_OWNER_UID=</varname></term>
<listitem>
man: assorted small fixes This is almost all of #17177.
2020-09-29 13:31:27 +03:00
<para>The control group path in the systemd hierarchy, the systemd slice unit name, the systemd
unit name, the unit name in the systemd user manager (if any), the systemd session ID (if any), and
the owner UID of the systemd user unit or systemd session (if any) of the process the journal entry
originates from.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_SELINUX_CONTEXT=</varname></term>
<listitem>
<para>The SELinux security context (label) of the process
the journal entry originates from.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
<listitem>
<para>The earliest trusted timestamp of the message, if any
is known that is different from the reception time of the
journal. This is the time in microseconds since the epoch
UTC, formatted as a decimal string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_BOOT_ID=</varname></term>
<listitem>
<para>The kernel boot ID for the boot the message was
generated in, formatted as a 128-bit hexadecimal
string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_MACHINE_ID=</varname></term>
<listitem>
<para>The machine ID of the originating host, as available
in
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>
man: systemd.journal-fields: document _SYSTEMD_INVOCATION_ID (#5316) #4067 added documentation to systemd.exec(5), but not systemd.journal-fields(7).
2017-02-12 08:27:58 +03:00
<varlistentry>
<term><varname>_SYSTEMD_INVOCATION_ID=</varname></term>
<listitem>
<para>The invocation ID for the runtime cycle of the unit
the message was generated in, as available to processes
of the unit in <varname>$INVOCATION_ID</varname> (see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para>
</listitem>
</varlistentry>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term><varname>_HOSTNAME=</varname></term>
<listitem>
<para>The name of the originating host.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_TRANSPORT=</varname></term>
<listitem>
<para>How the entry was received by the journal service.
Valid transports are:
</para>
<variablelist>
man: systemd.journal-fields: add info about _TRANSPORT=audit
2015-10-03 05:38:06 +03:00
<varlistentry>
<term>
<option>audit</option>
</term>
<listitem>
<para>for those read from the kernel audit subsystem
</para>
</listitem>
</varlistentry>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term>
<option>driver</option>
</term>
<listitem>
<para>for internally generated messages
man: describe OBJECT_PID=
2013-07-03 07:35:20 +04:00
</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>syslog</option>
</term>
<listitem>
<para>for those received via the local syslog socket
with the syslog protocol
man: document COREDUMP_UNIT and COREDUMP_USER_UNIT Also fix formatting for kernel related fields, enabling them to show up in the directives index.
2013-02-07 09:50:37 +04:00
</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>journal</option>
</term>
<listitem>
<para>for those received via the native journal
protocol
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>stdout</option>
</term>
<listitem>
<para>for those read from a service's standard output
or error output
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>kernel</option>
</term>
<listitem>
<para>for those read from the kernel
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
journald: make maximum size of stream log lines configurable and bump it to 48K (#6838) This adds a new setting LineMax= to journald.conf, and sets it by default to 48K. When we convert stream-based stdout/stderr logging into record-based log entries, read up to the specified amount of bytes before forcing a line-break. This also makes three related changes: - When a NUL byte is read we'll not recognize this as alternative line break, instead of silently dropping everything after it. (see #4863) - The reason for a line-break is now encoded in the log record, if it wasn't a plain newline. Specifically, we distuingish "nul", "line-max" and "eof", for line breaks due to NUL byte, due to the maximum line length as configured with LineMax= or due to end of stream. This data is stored in the new implicit _LINE_BREAK= field. It's not synthesized for plain \n line breaks. - A randomized 128bit ID is assigned to each log stream. With these three changes in place it's (mostly) possible to reconstruct the original byte streams from log data, as (most) of the context of the conversion from the byte stream to log records is saved now. (So, the only bits we still drop are empty lines. Which might be something to look into in a future change, and which is outside of the scope of this work) Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=86465 See: #4863 Replaces: #4875
2017-09-22 11:22:24 +03:00
<varlistentry>
<term><varname>_STREAM_ID=</varname></term>
<listitem>
man: fix _STREAM_ID, _LINE_BREAK descriptions Pointed out by Дилян Палаузов (https://github.com/dilyanpalauzov). Fixes #7870.
2018-01-20 02:15:06 +03:00
<para>Only applies to <literal>_TRANSPORT=stdout</literal> records: specifies a randomized 128bit ID assigned
journald: make maximum size of stream log lines configurable and bump it to 48K (#6838) This adds a new setting LineMax= to journald.conf, and sets it by default to 48K. When we convert stream-based stdout/stderr logging into record-based log entries, read up to the specified amount of bytes before forcing a line-break. This also makes three related changes: - When a NUL byte is read we'll not recognize this as alternative line break, instead of silently dropping everything after it. (see #4863) - The reason for a line-break is now encoded in the log record, if it wasn't a plain newline. Specifically, we distuingish "nul", "line-max" and "eof", for line breaks due to NUL byte, due to the maximum line length as configured with LineMax= or due to end of stream. This data is stored in the new implicit _LINE_BREAK= field. It's not synthesized for plain \n line breaks. - A randomized 128bit ID is assigned to each log stream. With these three changes in place it's (mostly) possible to reconstruct the original byte streams from log data, as (most) of the context of the conversion from the byte stream to log records is saved now. (So, the only bits we still drop are empty lines. Which might be something to look into in a future change, and which is outside of the scope of this work) Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=86465 See: #4863 Replaces: #4875
2017-09-22 11:22:24 +03:00
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>
</varlistentry>
<varlistentry>
<term><varname>_LINE_BREAK=</varname></term>
<listitem>
man: document the new _LINE_BREAK= type
2020-05-13 01:09:43 +03:00
<para>Only applies to <literal>_TRANSPORT=stdout</literal> records: indicates that the log message
in the standard output/error stream was not terminated with a normal newline character
(<literal>\n</literal>, i.e. ASCII 10). Specifically, when set this field is one of
man: set constant tag to NUL or NULL
2020-11-12 10:58:00 +03:00
<option>nul</option> (in case the line was terminated by a <constant>NUL</constant> byte), <option>line-max</option> (in
man: document the new _LINE_BREAK= type
2020-05-13 01:09:43 +03:00
case the maximum log line length was reached, as configured with <varname>LineMax=</varname> in
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>),
<option>eof</option> (if this was the last log record of a stream and the stream ended without a
final newline character), or <option>pid-change</option> (if the process which generated the log
output changed in the middle of a line). Note that this record is not generated when a normal
newline character was used for marking the log line end.</para>
journald: make maximum size of stream log lines configurable and bump it to 48K (#6838) This adds a new setting LineMax= to journald.conf, and sets it by default to 48K. When we convert stream-based stdout/stderr logging into record-based log entries, read up to the specified amount of bytes before forcing a line-break. This also makes three related changes: - When a NUL byte is read we'll not recognize this as alternative line break, instead of silently dropping everything after it. (see #4863) - The reason for a line-break is now encoded in the log record, if it wasn't a plain newline. Specifically, we distuingish "nul", "line-max" and "eof", for line breaks due to NUL byte, due to the maximum line length as configured with LineMax= or due to end of stream. This data is stored in the new implicit _LINE_BREAK= field. It's not synthesized for plain \n line breaks. - A randomized 128bit ID is assigned to each log stream. With these three changes in place it's (mostly) possible to reconstruct the original byte streams from log data, as (most) of the context of the conversion from the byte stream to log records is saved now. (So, the only bits we still drop are empty lines. Which might be something to look into in a future change, and which is outside of the scope of this work) Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=86465 See: #4863 Replaces: #4875
2017-09-22 11:22:24 +03:00
</listitem>
</varlistentry>
man: document new _NAMESPACE= journal field
2019-11-27 23:29:47 +03:00
<varlistentry>
<term><varname>_NAMESPACE=</varname></term>
<listitem><para>If this file was written by a <command>systemd-journald</command> instance managing a
journal namespace that is not the default, this field contains the namespace identifier. See
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
for details about journal namespaces.</para>
</listitem>
</varlistentry>
journal: Add new _INITRD field The _INITRD field is a boolean field (0 or 1) that specifies whether a message was processed by systemd-journald in the initrd or not.
2022-05-17 15:57:54 +03:00
<varlistentry>
journal: rename special journal field _SYSTEM_CONTEXT= → _RUNTIME_SCOPE= Previously the field "_SYSTEM_CONTEXT" knew he values "initrd" + "main". Let's change this to "_RUNTIME_SCOPE" and "initrd" + "system". Why? The sysext logic has a very similar concept of "scopes", declaring whether a sysext image is intended for the initrd or the main system. Let's thus use the same naming for both. sysext's extension-release files hence know SYSEXT_SCOPE=initrd|system, and the journal messages know _RUNTIME_SCOPE=initrd|system, which makes this reasonably systematic. Follow-up for: cae8edd93ca2ef90c41cb9b6322b6908d12947b5 (This is not an API break, since no version with this commit has ever been released.)
2022-08-25 18:32:28 +03:00
<term><varname>_RUNTIME_SCOPE=</varname></term>
journal: Add new _INITRD field The _INITRD field is a boolean field (0 or 1) that specifies whether a message was processed by systemd-journald in the initrd or not.
2022-05-17 15:57:54 +03:00
journal: rename special journal field _SYSTEM_CONTEXT= → _RUNTIME_SCOPE= Previously the field "_SYSTEM_CONTEXT" knew he values "initrd" + "main". Let's change this to "_RUNTIME_SCOPE" and "initrd" + "system". Why? The sysext logic has a very similar concept of "scopes", declaring whether a sysext image is intended for the initrd or the main system. Let's thus use the same naming for both. sysext's extension-release files hence know SYSEXT_SCOPE=initrd|system, and the journal messages know _RUNTIME_SCOPE=initrd|system, which makes this reasonably systematic. Follow-up for: cae8edd93ca2ef90c41cb9b6322b6908d12947b5 (This is not an API break, since no version with this commit has ever been released.)
2022-08-25 18:32:28 +03:00
<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
tree-wide: also settle on "initrd" instead of "initial RAM disk" With this the concept is now called the same way everywhere except where historical info is relevant or where the other names are API.
2022-09-23 16:10:06 +03:00
initrd. If <literal>system</literal>, the log message was generated after the system switched
execution to the host root filesystem.</para></listitem>
journal: Add new _INITRD field The _INITRD field is a boolean field (0 or 1) that specifies whether a message was processed by systemd-journald in the initrd or not.
2022-05-17 15:57:54 +03:00
</varlistentry>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</variablelist>
</refsect1>
<refsect1>
<title>Kernel Journal Fields</title>
<para>Kernel fields are fields that are used by messages
originating in the kernel and stored in the journal.</para>
<variablelist class='journal-directives'>
<varlistentry>
<term><varname>_KERNEL_DEVICE=</varname></term>
<listitem>
man: assorted small fixes This is almost all of #17177.
2020-09-29 13:31:27 +03:00
<para>The kernel device name. If the entry is associated to a block device, contains the major and
minor numbers of the device node, separated by <literal>:</literal> and prefixed by
<literal>b</literal>. Similarly for character devices, but prefixed by <literal>c</literal>. For
network devices, this is the interface index prefixed by <literal>n</literal>. For all other
devices, this is the subsystem name prefixed by <literal>+</literal>, followed by
<literal>:</literal>, followed by the kernel device name.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_KERNEL_SUBSYSTEM=</varname></term>
<listitem>
<para>The kernel subsystem name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_UDEV_SYSNAME=</varname></term>
<listitem>
<para>The kernel device name as it shows up in the device
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
tree below <filename>/sys/</filename>.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_UDEV_DEVNODE=</varname></term>
<listitem>
<para>The device node path of this device in
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
<filename>/dev/</filename>.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>_UDEV_DEVLINK=</varname></term>
<listitem>
<para>Additional symlink names pointing to the device node
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
in <filename>/dev/</filename>. This field is frequently set
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
more than once per entry.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Fields to log on behalf of a different program</title>
<para>Fields in this section are used by programs to specify that
they are logging on behalf of another program or unit.
</para>
<para>Fields used by the <command>systemd-coredump</command>
coredump kernel helper:
</para>
<variablelist class='journal-directives'>
<varlistentry>
<term><varname>COREDUMP_UNIT=</varname></term>
<term><varname>COREDUMP_USER_UNIT=</varname></term>
<listitem>
<para>Used to annotate messages containing coredumps from
system and session units. See
<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
</listitem>
</varlistentry>
</variablelist>
treewide: Correct typos and spell plural of bus consistent
2015-05-11 14:49:29 +03:00
<para>Privileged programs (currently UID 0) may attach
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varname>OBJECT_PID=</varname> to a message. This will instruct
<command>systemd-journald</command> to attach additional fields on
behalf of the caller:</para>
<variablelist class='journal-directives'>
<varlistentry>
<term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
<listitem>
<para>PID of the program that this message pertains to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>OBJECT_UID=</varname></term>
<term><varname>OBJECT_GID=</varname></term>
<term><varname>OBJECT_COMM=</varname></term>
<term><varname>OBJECT_EXE=</varname></term>
<term><varname>OBJECT_CMDLINE=</varname></term>
<term><varname>OBJECT_AUDIT_SESSION=</varname></term>
<term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
<term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
<term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
<term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
<term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
<term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
<listitem>
<para>These are additional fields added automatically by
<command>systemd-journald</command>. Their meaning is the
same as
<varname>_UID=</varname>,
<varname>_GID=</varname>,
<varname>_COMM=</varname>,
<varname>_EXE=</varname>,
<varname>_CMDLINE=</varname>,
<varname>_AUDIT_SESSION=</varname>,
<varname>_AUDIT_LOGINUID=</varname>,
<varname>_SYSTEMD_CGROUP=</varname>,
<varname>_SYSTEMD_SESSION=</varname>,
<varname>_SYSTEMD_UNIT=</varname>,
<varname>_SYSTEMD_USER_UNIT=</varname>, and
<varname>_SYSTEMD_OWNER_UID=</varname>
as described above, except that the process identified by
<replaceable>PID</replaceable> is described, instead of the
process which logged the message.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Address Fields</title>
<para>During serialization into external formats, such as the
man+docs: adjust links to the new page
2022-01-12 13:32:53 +03:00
<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
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
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
structured log entries via calls such as
<citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
They may also not be used as matches for
tree-wide: fixes for assorted grammar and spelling issues Fixes #16363. Also includes some changes where I generalized the pattern.
2020-07-06 11:49:59 +03:00
<citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<variablelist class='journal-directives'>
<varlistentry>
<term><varname>__CURSOR=</varname></term>
<listitem>
<para>The cursor for the entry. A cursor is an opaque text
string that uniquely describes the position of an entry in
the journal and is portable across machines, platforms and
journal files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>__REALTIME_TIMESTAMP=</varname></term>
<listitem>
<para>The wallclock time
(<constant>CLOCK_REALTIME</constant>) at the point in time
the entry was received by the journal, in microseconds since
the epoch UTC, formatted as a decimal string. This has
different properties from
<literal>_SOURCE_REALTIME_TIMESTAMP=</literal>, as it is
usually a bit later but more likely to be monotonic.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
<listitem>
<para>The monotonic time
(<constant>CLOCK_MONOTONIC</constant>) at the point in time
the entry was received by the journal in microseconds,
formatted as a decimal string. To be useful as an address
for the entry, this should be combined with the boot ID in
<literal>_BOOT_ID=</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
man: add reference to journald man page from systemd.journal-fields(7) We had none so far. Which is weird.
2019-11-27 23:29:32 +03:00
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>
man: document special journal fields
2012-04-04 00:31:48 +04:00
</refentry>
Copy Permalink