1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"systemd.journal-fields">
12 <title>systemd.journal-fields
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>systemd.journal-fields
</refentrytitle>
18 <manvolnum>7</manvolnum>
22 <refname>systemd.journal-fields
</refname>
23 <refpurpose>Special journal fields
</refpurpose>
27 <title>Description
</title>
29 <para>Entries in the journal resemble an environment block in
30 their syntax but with fields that can include binary data.
31 Primarily, fields are formatted UTF-
8 text strings, and binary
32 formatting is used only where formatting as UTF-
8 text strings
33 makes little sense. New fields may freely be defined by
34 applications, but a few fields have special meaning. All fields
35 with special meanings are optional. In some cases, fields may
36 appear more than once per entry.
</para>
40 <title>User Journal Fields
</title>
42 <para>User fields are fields that are directly passed from clients
43 and stored in the journal.
</para>
45 <variablelist class='journal-directives'
>
47 <term><varname>MESSAGE=
</varname></term>
49 <para>The human-readable message string for this entry. This
50 is supposed to be the primary text shown to the user. It is
51 usually not translated (but might be in some cases), and is
52 not supposed to be parsed for metadata.
</para>
57 <term><varname>MESSAGE_ID=
</varname></term>
59 <para>A
128-bit message identifier ID for recognizing certain message types, if this is desirable. This
60 should contain a
128-bit ID formatted as a lower-case hexadecimal string, without any separating dashes or
61 suchlike. This is recommended to be a UUID-compatible ID, but this is not enforced, and formatted
62 differently. Developers can generate a new ID for this purpose with
<command>systemd-id128 new
</command>.
68 <term><varname>PRIORITY=
</varname></term>
70 <para>A priority value between
0 (
<literal>emerg
</literal>)
71 and
7 (
<literal>debug
</literal>) formatted as a decimal
72 string. This field is compatible with syslog's priority
78 <term><varname>CODE_FILE=
</varname></term>
79 <term><varname>CODE_LINE=
</varname></term>
80 <term><varname>CODE_FUNC=
</varname></term>
82 <para>The code location generating this message, if known.
83 Contains the source filename, the line number and the
89 <term><varname>ERRNO=
</varname></term>
91 <para>The low-level Unix error number causing this entry, if
92 any. Contains the numeric value of
93 <citerefentry project='man-pages'
><refentrytitle>errno
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
94 formatted as a decimal string.
</para>
99 <term><varname>SYSLOG_FACILITY=
</varname></term>
100 <term><varname>SYSLOG_IDENTIFIER=
</varname></term>
101 <term><varname>SYSLOG_PID=
</varname></term>
102 <term><varname>SYSLOG_TIMESTAMP=
</varname></term>
104 <para>Syslog compatibility fields containing the facility (formatted as
105 decimal string), the identifier string (i.e.
"tag"), the client PID, and
106 the timestamp as specified in the original datagram. (Note that the tag is
107 usually derived from glibc's
108 <varname>program_invocation_short_name
</varname> variable, see
109 <citerefentry project='die-net'
><refentrytitle>program_invocation_short_name
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)
</para>
114 <term><varname>SYSLOG_RAW=
</varname></term>
116 <para>The original contents of the syslog line as received in the syslog
117 datagram. This field is only included if the
<varname>MESSAGE=
</varname>
118 field was modified compared to the original payload or the timestamp could
119 not be located properly and is not included in
120 <varname>SYSLOG_TIMESTAMP=
</varname>. Message truncation occurs when when
121 the message contains leading or trailing whitespace (trailing and leading
122 whitespace is stripped), or it contains an embedded
123 <constant>NUL
</constant> byte (the
<constant>NUL
</constant> byte and
124 anything after it is not included). Thus, the original syslog line is
125 either stored as
<varname>SYSLOG_RAW=
</varname> or it can be recreated
126 based on the stored priority and facility, timestamp, identifier, and the
127 message payload in
<varname>MESSAGE=
</varname>.
135 <title>Trusted Journal Fields
</title>
137 <para>Fields prefixed with an underscore are trusted fields, i.e.
138 fields that are implicitly added by the journal and cannot be
139 altered by client code.
</para>
141 <variablelist class='journal-directives'
>
143 <term><varname>_PID=
</varname></term>
144 <term><varname>_UID=
</varname></term>
145 <term><varname>_GID=
</varname></term>
147 <para>The process, user, and group ID of the process the
148 journal entry originates from formatted as a decimal
149 string. Note that entries obtained via
<literal>stdout
</literal> or
150 <literal>stderr
</literal> of forked processes will contain credentials valid for a parent
151 process (that initiated the connection to
<command>systemd-journald
</command>).
</para>
156 <term><varname>_COMM=
</varname></term>
157 <term><varname>_EXE=
</varname></term>
158 <term><varname>_CMDLINE=
</varname></term>
160 <para>The name, the executable path, and the command line of
161 the process the journal entry originates from.
</para>
166 <term><varname>_CAP_EFFECTIVE=
</varname></term>
169 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
170 of the process the journal entry originates from.
</para>
175 <term><varname>_AUDIT_SESSION=
</varname></term>
176 <term><varname>_AUDIT_LOGINUID=
</varname></term>
178 <para>The session and login UID of the process the journal
179 entry originates from, as maintained by the kernel audit
185 <term><varname>_SYSTEMD_CGROUP=
</varname></term>
186 <term><varname>_SYSTEMD_SLICE=
</varname></term>
187 <term><varname>_SYSTEMD_UNIT=
</varname></term>
188 <term><varname>_SYSTEMD_USER_UNIT=
</varname></term>
189 <term><varname>_SYSTEMD_SESSION=
</varname></term>
190 <term><varname>_SYSTEMD_OWNER_UID=
</varname></term>
193 <para>The control group path in the systemd hierarchy, the
194 the systemd slice unit name, the systemd unit name, the
195 unit name in the systemd user manager (if any), the systemd
196 session ID (if any), and the owner UID of the systemd user
197 unit or systemd session (if any) of the process the journal
198 entry originates from.
</para>
203 <term><varname>_SELINUX_CONTEXT=
</varname></term>
205 <para>The SELinux security context (label) of the process
206 the journal entry originates from.
</para>
211 <term><varname>_SOURCE_REALTIME_TIMESTAMP=
</varname></term>
213 <para>The earliest trusted timestamp of the message, if any
214 is known that is different from the reception time of the
215 journal. This is the time in microseconds since the epoch
216 UTC, formatted as a decimal string.
</para>
221 <term><varname>_BOOT_ID=
</varname></term>
223 <para>The kernel boot ID for the boot the message was
224 generated in, formatted as a
128-bit hexadecimal
230 <term><varname>_MACHINE_ID=
</varname></term>
232 <para>The machine ID of the originating host, as available
234 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
239 <term><varname>_SYSTEMD_INVOCATION_ID=
</varname></term>
241 <para>The invocation ID for the runtime cycle of the unit
242 the message was generated in, as available to processes
243 of the unit in
<varname>$INVOCATION_ID
</varname> (see
244 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
</para>
249 <term><varname>_HOSTNAME=
</varname></term>
251 <para>The name of the originating host.
</para>
256 <term><varname>_TRANSPORT=
</varname></term>
258 <para>How the entry was received by the journal service.
259 Valid transports are:
264 <option>audit
</option>
267 <para>for those read from the kernel audit subsystem
274 <option>driver
</option>
277 <para>for internally generated messages
284 <option>syslog
</option>
287 <para>for those received via the local syslog socket
288 with the syslog protocol
295 <option>journal
</option>
298 <para>for those received via the native journal
306 <option>stdout
</option>
309 <para>for those read from a service's standard output
317 <option>kernel
</option>
320 <para>for those read from the kernel
328 <term><varname>_STREAM_ID=
</varname></term>
330 <para>Only applies to
<literal>_TRANSPORT=stdout
</literal> records: specifies a randomized
128bit ID assigned
331 to the stream connection when it was first created. This ID is useful to reconstruct individual log streams
332 from the log records: all log records carrying the same stream ID originate from the same stream.
</para>
336 <term><varname>_LINE_BREAK=
</varname></term>
338 <para>Only applies to
<literal>_TRANSPORT=stdout
</literal> records: indicates that the log message in the
339 standard output/error stream was not terminated with a normal newline character (
<literal>\n
</literal>,
340 i.e. ASCII
10). Specifically, when set this field is one of
<option>nul
</option> (in case the line was
341 terminated by a NUL byte),
<option>line-max
</option> (in case the maximum log line length was reached, as
342 configured with
<varname>LineMax=
</varname> in
343 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>) or
344 <option>eof
</option> (if this was the last log record of a stream and the stream ended without a final
345 newline character). Note that this record is not generated when a normal newline character was used for
346 marking the log line end.
</para>
353 <title>Kernel Journal Fields
</title>
355 <para>Kernel fields are fields that are used by messages
356 originating in the kernel and stored in the journal.
</para>
358 <variablelist class='journal-directives'
>
360 <term><varname>_KERNEL_DEVICE=
</varname></term>
362 <para>The kernel device name. If the entry is associated to
363 a block device, the major and minor of the device node,
364 separated by
<literal>:
</literal> and prefixed by
365 <literal>b
</literal>. Similar for character devices but
366 prefixed by
<literal>c
</literal>. For network devices, this
367 is the interface index prefixed by
<literal>n
</literal>. For
368 all other devices, this is the subsystem name prefixed by
369 <literal>+
</literal>, followed by
<literal>:
</literal>,
370 followed by the kernel device name.
</para>
374 <term><varname>_KERNEL_SUBSYSTEM=
</varname></term>
376 <para>The kernel subsystem name.
</para>
380 <term><varname>_UDEV_SYSNAME=
</varname></term>
382 <para>The kernel device name as it shows up in the device
383 tree below
<filename>/sys
</filename>.
</para>
387 <term><varname>_UDEV_DEVNODE=
</varname></term>
389 <para>The device node path of this device in
390 <filename>/dev
</filename>.
</para>
394 <term><varname>_UDEV_DEVLINK=
</varname></term>
396 <para>Additional symlink names pointing to the device node
397 in
<filename>/dev
</filename>. This field is frequently set
398 more than once per entry.
</para>
405 <title>Fields to log on behalf of a different program
</title>
407 <para>Fields in this section are used by programs to specify that
408 they are logging on behalf of another program or unit.
411 <para>Fields used by the
<command>systemd-coredump
</command>
412 coredump kernel helper:
415 <variablelist class='journal-directives'
>
417 <term><varname>COREDUMP_UNIT=
</varname></term>
418 <term><varname>COREDUMP_USER_UNIT=
</varname></term>
420 <para>Used to annotate messages containing coredumps from
421 system and session units. See
422 <citerefentry><refentrytitle>coredumpctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
428 <para>Privileged programs (currently UID
0) may attach
429 <varname>OBJECT_PID=
</varname> to a message. This will instruct
430 <command>systemd-journald
</command> to attach additional fields on
431 behalf of the caller:
</para>
433 <variablelist class='journal-directives'
>
435 <term><varname>OBJECT_PID=
<replaceable>PID
</replaceable></varname></term>
437 <para>PID of the program that this message pertains to.
443 <term><varname>OBJECT_UID=
</varname></term>
444 <term><varname>OBJECT_GID=
</varname></term>
445 <term><varname>OBJECT_COMM=
</varname></term>
446 <term><varname>OBJECT_EXE=
</varname></term>
447 <term><varname>OBJECT_CMDLINE=
</varname></term>
448 <term><varname>OBJECT_AUDIT_SESSION=
</varname></term>
449 <term><varname>OBJECT_AUDIT_LOGINUID=
</varname></term>
450 <term><varname>OBJECT_SYSTEMD_CGROUP=
</varname></term>
451 <term><varname>OBJECT_SYSTEMD_SESSION=
</varname></term>
452 <term><varname>OBJECT_SYSTEMD_OWNER_UID=
</varname></term>
453 <term><varname>OBJECT_SYSTEMD_UNIT=
</varname></term>
454 <term><varname>OBJECT_SYSTEMD_USER_UNIT=
</varname></term>
456 <para>These are additional fields added automatically by
457 <command>systemd-journald
</command>. Their meaning is the
459 <varname>_UID=
</varname>,
460 <varname>_GID=
</varname>,
461 <varname>_COMM=
</varname>,
462 <varname>_EXE=
</varname>,
463 <varname>_CMDLINE=
</varname>,
464 <varname>_AUDIT_SESSION=
</varname>,
465 <varname>_AUDIT_LOGINUID=
</varname>,
466 <varname>_SYSTEMD_CGROUP=
</varname>,
467 <varname>_SYSTEMD_SESSION=
</varname>,
468 <varname>_SYSTEMD_UNIT=
</varname>,
469 <varname>_SYSTEMD_USER_UNIT=
</varname>, and
470 <varname>_SYSTEMD_OWNER_UID=
</varname>
471 as described above, except that the process identified by
472 <replaceable>PID
</replaceable> is described, instead of the
473 process which logged the message.
</para>
481 <title>Address Fields
</title>
483 <para>During serialization into external formats, such as the
485 url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal
486 Export Format
</ulink> or the
<ulink
487 url=
"https://www.freedesktop.org/wiki/Software/systemd/json">Journal
488 JSON Format
</ulink>, the addresses of journal entries are
489 serialized into fields prefixed with double underscores. Note that
490 these are not proper fields when stored in the journal but for
491 addressing metadata of entries. They cannot be written as part of
492 structured log entries via calls such as
493 <citerefentry><refentrytitle>sd_journal_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
494 They may also not be used as matches for
495 <citerefentry><refentrytitle>sd_journal_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
497 <variablelist class='journal-directives'
>
499 <term><varname>__CURSOR=
</varname></term>
501 <para>The cursor for the entry. A cursor is an opaque text
502 string that uniquely describes the position of an entry in
503 the journal and is portable across machines, platforms and
510 <term><varname>__REALTIME_TIMESTAMP=
</varname></term>
512 <para>The wallclock time
513 (
<constant>CLOCK_REALTIME
</constant>) at the point in time
514 the entry was received by the journal, in microseconds since
515 the epoch UTC, formatted as a decimal string. This has
516 different properties from
517 <literal>_SOURCE_REALTIME_TIMESTAMP=
</literal>, as it is
518 usually a bit later but more likely to be monotonic.
524 <term><varname>__MONOTONIC_TIMESTAMP=
</varname></term>
526 <para>The monotonic time
527 (
<constant>CLOCK_MONOTONIC
</constant>) at the point in time
528 the entry was received by the journal in microseconds,
529 formatted as a decimal string. To be useful as an address
530 for the entry, this should be combined with the boot ID in
531 <literal>_BOOT_ID=
</literal>.
539 <title>See Also
</title>
541 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
542 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
543 <citerefentry><refentrytitle>journald.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
544 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
545 <citerefentry><refentrytitle>coredumpctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
546 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>