man/systemd.journal-fields.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="systemd.journal-fields">
   7
   8   <refentryinfo>
   9     <title>systemd.journal-fields</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd.journal-fields</refentrytitle>
  15     <manvolnum>7</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd.journal-fields</refname>
  20     <refpurpose>Special journal fields</refpurpose>
  21   </refnamediv>
  22
  23   <refsect1>
  24     <title>Description</title>
  25
  26     <para>Entries in the journal resemble an environment block in
  27     their syntax but with fields that can include binary data.
  28     Primarily, fields are formatted UTF-8 text strings, and binary
  29     formatting is used only where formatting as UTF-8 text strings
  30     makes little sense. New fields may freely be defined by
  31     applications, but a few fields have special meaning. All fields
  32     with special meanings are optional. In some cases, fields may
  33     appear more than once per entry.</para>
  34   </refsect1>
  35
  36   <refsect1>
  37     <title>User Journal Fields</title>
  38
  39     <para>User fields are fields that are directly passed from clients
  40     and stored in the journal.</para>
  41
  42     <variablelist class='journal-directives'>
  43       <varlistentry>
  44         <term><varname>MESSAGE=</varname></term>
  45         <listitem>
  46           <para>The human-readable message string for this entry. This
  47           is supposed to be the primary text shown to the user. It is
  48           usually not translated (but might be in some cases), and is
  49           not supposed to be parsed for metadata.</para>
  50         </listitem>
  51       </varlistentry>
  52
  53       <varlistentry>
  54         <term><varname>MESSAGE_ID=</varname></term>
  55         <listitem>
  56           <para>A 128-bit message identifier ID for recognizing certain message types, if this is desirable. This
  57           should contain a 128-bit ID formatted as a lower-case hexadecimal string, without any separating dashes or
  58           suchlike. This is recommended to be a UUID-compatible ID, but this is not enforced, and formatted
  59           differently. Developers can generate a new ID for this purpose with <command>systemd-id128 new</command>.
  60           </para>
  61         </listitem>
  62       </varlistentry>
  63
  64       <varlistentry>
  65         <term><varname>PRIORITY=</varname></term>
  66         <listitem>
  67           <para>A priority value between 0 (<literal>emerg</literal>)
  68           and 7 (<literal>debug</literal>) formatted as a decimal
  69           string. This field is compatible with syslog's priority
  70           concept.</para>
  71         </listitem>
  72       </varlistentry>
  73
  74       <varlistentry>
  75         <term><varname>CODE_FILE=</varname></term>
  76         <term><varname>CODE_LINE=</varname></term>
  77         <term><varname>CODE_FUNC=</varname></term>
  78         <listitem>
  79           <para>The code location generating this message, if known.
  80           Contains the source filename, the line number and the
  81           function name.</para>
  82         </listitem>
  83       </varlistentry>
  84
  85       <varlistentry>
  86         <term><varname>ERRNO=</varname></term>
  87         <listitem>
  88           <para>The low-level Unix error number causing this entry, if
  89           any. Contains the numeric value of
  90           <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  91           formatted as a decimal string.</para>
  92         </listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term><varname>SYSLOG_FACILITY=</varname></term>
  97         <term><varname>SYSLOG_IDENTIFIER=</varname></term>
  98         <term><varname>SYSLOG_PID=</varname></term>
  99         <term><varname>SYSLOG_TIMESTAMP=</varname></term>
 100         <listitem>
 101           <para>Syslog compatibility fields containing the facility (formatted as
 102           decimal string), the identifier string (i.e.  "tag"), the client PID, and
 103           the timestamp as specified in the original datagram. (Note that the tag is
 104           usually derived from glibc's
 105           <varname>program_invocation_short_name</varname> variable, see
 106           <citerefentry project='die-net'><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para>
 107         </listitem>
 108       </varlistentry>
 109
 110       <varlistentry>
 111         <term><varname>SYSLOG_RAW=</varname></term>
 112         <listitem>
 113           <para>The original contents of the syslog line as received in the syslog
 114           datagram. This field is only included if the <varname>MESSAGE=</varname>
 115           field was modified compared to the original payload or the timestamp could
 116           not be located properly and is not included in
 117           <varname>SYSLOG_TIMESTAMP=</varname>. Message truncation occurs when when
 118           the message contains leading or trailing whitespace (trailing and leading
 119           whitespace is stripped), or it contains an embedded
 120           <constant>NUL</constant> byte (the <constant>NUL</constant> byte and
 121           anything after it is not included). Thus, the original syslog line is
 122           either stored as <varname>SYSLOG_RAW=</varname> or it can be recreated
 123           based on the stored priority and facility, timestamp, identifier, and the
 124           message payload in <varname>MESSAGE=</varname>.
 125           </para>
 126         </listitem>
 127       </varlistentry>
 128     </variablelist>
 129   </refsect1>
 130
 131   <refsect1>
 132     <title>Trusted Journal Fields</title>
 133
 134     <para>Fields prefixed with an underscore are trusted fields, i.e.
 135     fields that are implicitly added by the journal and cannot be
 136     altered by client code.</para>
 137
 138     <variablelist class='journal-directives'>
 139       <varlistentry>
 140         <term><varname>_PID=</varname></term>
 141         <term><varname>_UID=</varname></term>
 142         <term><varname>_GID=</varname></term>
 143         <listitem>
 144           <para>The process, user, and group ID of the process the
 145           journal entry originates from formatted as a decimal
 146           string. Note that entries obtained via <literal>stdout</literal> or
 147           <literal>stderr</literal> of forked processes will contain credentials valid for a parent
 148           process (that initiated the connection to <command>systemd-journald</command>).</para>
 149         </listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><varname>_COMM=</varname></term>
 154         <term><varname>_EXE=</varname></term>
 155         <term><varname>_CMDLINE=</varname></term>
 156         <listitem>
 157           <para>The name, the executable path, and the command line of
 158           the process the journal entry originates from.</para>
 159         </listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><varname>_CAP_EFFECTIVE=</varname></term>
 164         <listitem>
 165           <para>The effective
 166           <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 167           of the process the journal entry originates from.</para>
 168         </listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term><varname>_AUDIT_SESSION=</varname></term>
 173         <term><varname>_AUDIT_LOGINUID=</varname></term>
 174         <listitem>
 175           <para>The session and login UID of the process the journal
 176           entry originates from, as maintained by the kernel audit
 177           subsystem.</para>
 178         </listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><varname>_SYSTEMD_CGROUP=</varname></term>
 183         <term><varname>_SYSTEMD_SLICE=</varname></term>
 184         <term><varname>_SYSTEMD_UNIT=</varname></term>
 185         <term><varname>_SYSTEMD_USER_UNIT=</varname></term>
 186         <term><varname>_SYSTEMD_SESSION=</varname></term>
 187         <term><varname>_SYSTEMD_OWNER_UID=</varname></term>
 188
 189         <listitem>
 190           <para>The control group path in the systemd hierarchy, the
 191           the systemd slice unit name, the systemd unit name, the
 192           unit name in the systemd user manager (if any), the systemd
 193           session ID (if any), and the owner UID of the systemd user
 194           unit or systemd session (if any) of the process the journal
 195           entry originates from.</para>
 196         </listitem>
 197       </varlistentry>
 198
 199       <varlistentry>
 200         <term><varname>_SELINUX_CONTEXT=</varname></term>
 201         <listitem>
 202           <para>The SELinux security context (label) of the process
 203           the journal entry originates from.</para>
 204         </listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
 209         <listitem>
 210           <para>The earliest trusted timestamp of the message, if any
 211           is known that is different from the reception time of the
 212           journal. This is the time in microseconds since the epoch
 213           UTC, formatted as a decimal string.</para>
 214         </listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><varname>_BOOT_ID=</varname></term>
 219         <listitem>
 220           <para>The kernel boot ID for the boot the message was
 221           generated in, formatted as a 128-bit hexadecimal
 222           string.</para>
 223         </listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><varname>_MACHINE_ID=</varname></term>
 228         <listitem>
 229           <para>The machine ID of the originating host, as available
 230           in
 231           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 232         </listitem>
 233       </varlistentry>
 234
 235       <varlistentry>
 236         <term><varname>_SYSTEMD_INVOCATION_ID=</varname></term>
 237         <listitem>
 238           <para>The invocation ID for the runtime cycle of the unit
 239           the message was generated in, as available to processes
 240           of the unit in <varname>$INVOCATION_ID</varname> (see
 241           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para>
 242         </listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term><varname>_HOSTNAME=</varname></term>
 247         <listitem>
 248           <para>The name of the originating host.</para>
 249         </listitem>
 250       </varlistentry>
 251
 252       <varlistentry>
 253         <term><varname>_TRANSPORT=</varname></term>
 254         <listitem>
 255           <para>How the entry was received by the journal service.
 256           Valid transports are:
 257           </para>
 258           <variablelist>
 259             <varlistentry>
 260               <term>
 261                 <option>audit</option>
 262               </term>
 263               <listitem>
 264                 <para>for those read from the kernel audit subsystem
 265                 </para>
 266               </listitem>
 267             </varlistentry>
 268
 269             <varlistentry>
 270               <term>
 271                 <option>driver</option>
 272               </term>
 273               <listitem>
 274                 <para>for internally generated messages
 275                 </para>
 276               </listitem>
 277             </varlistentry>
 278
 279             <varlistentry>
 280               <term>
 281                 <option>syslog</option>
 282               </term>
 283               <listitem>
 284                 <para>for those received via the local syslog socket
 285                 with the syslog protocol
 286                 </para>
 287               </listitem>
 288             </varlistentry>
 289
 290             <varlistentry>
 291               <term>
 292                 <option>journal</option>
 293               </term>
 294               <listitem>
 295                 <para>for those received via the native journal
 296                 protocol
 297                 </para>
 298               </listitem>
 299             </varlistentry>
 300
 301             <varlistentry>
 302               <term>
 303                 <option>stdout</option>
 304               </term>
 305               <listitem>
 306                 <para>for those read from a service's standard output
 307                 or error output
 308                 </para>
 309               </listitem>
 310             </varlistentry>
 311
 312             <varlistentry>
 313               <term>
 314                 <option>kernel</option>
 315               </term>
 316               <listitem>
 317                 <para>for those read from the kernel
 318                 </para>
 319               </listitem>
 320             </varlistentry>
 321           </variablelist>
 322         </listitem>
 323       </varlistentry>
 324       <varlistentry>
 325         <term><varname>_STREAM_ID=</varname></term>
 326         <listitem>
 327           <para>Only applies to <literal>_TRANSPORT=stdout</literal> records: specifies a randomized 128bit ID assigned
 328           to the stream connection when it was first created. This ID is useful to reconstruct individual log streams
 329           from the log records: all log records carrying the same stream ID originate from the same stream.</para>
 330         </listitem>
 331       </varlistentry>
 332       <varlistentry>
 333         <term><varname>_LINE_BREAK=</varname></term>
 334         <listitem>
 335           <para>Only applies to <literal>_TRANSPORT=stdout</literal> records: indicates that the log message in the
 336           standard output/error stream was not terminated with a normal newline character (<literal>\n</literal>,
 337           i.e. ASCII 10). Specifically, when set this field is one of <option>nul</option> (in case the line was
 338           terminated by a NUL byte), <option>line-max</option> (in case the maximum log line length was reached, as
 339           configured with <varname>LineMax=</varname> in
 340           <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) or
 341           <option>eof</option> (if this was the last log record of a stream and the stream ended without a final
 342           newline character). Note that this record is not generated when a normal newline character was used for
 343           marking the log line end.</para>
 344         </listitem>
 345       </varlistentry>
 346     </variablelist>
 347   </refsect1>
 348
 349   <refsect1>
 350     <title>Kernel Journal Fields</title>
 351
 352     <para>Kernel fields are fields that are used by messages
 353     originating in the kernel and stored in the journal.</para>
 354
 355     <variablelist class='journal-directives'>
 356       <varlistentry>
 357         <term><varname>_KERNEL_DEVICE=</varname></term>
 358         <listitem>
 359           <para>The kernel device name. If the entry is associated to
 360           a block device, the major and minor of the device node,
 361           separated by <literal>:</literal> and prefixed by
 362           <literal>b</literal>. Similar for character devices but
 363           prefixed by <literal>c</literal>. For network devices, this
 364           is the interface index prefixed by <literal>n</literal>. For
 365           all other devices, this is the subsystem name prefixed by
 366           <literal>+</literal>, followed by <literal>:</literal>,
 367           followed by the kernel device name.</para>
 368         </listitem>
 369       </varlistentry>
 370       <varlistentry>
 371         <term><varname>_KERNEL_SUBSYSTEM=</varname></term>
 372         <listitem>
 373           <para>The kernel subsystem name.</para>
 374         </listitem>
 375       </varlistentry>
 376       <varlistentry>
 377         <term><varname>_UDEV_SYSNAME=</varname></term>
 378         <listitem>
 379           <para>The kernel device name as it shows up in the device
 380           tree below <filename>/sys</filename>.</para>
 381         </listitem>
 382       </varlistentry>
 383       <varlistentry>
 384         <term><varname>_UDEV_DEVNODE=</varname></term>
 385         <listitem>
 386           <para>The device node path of this device in
 387           <filename>/dev</filename>.</para>
 388         </listitem>
 389       </varlistentry>
 390       <varlistentry>
 391         <term><varname>_UDEV_DEVLINK=</varname></term>
 392         <listitem>
 393           <para>Additional symlink names pointing to the device node
 394           in <filename>/dev</filename>. This field is frequently set
 395           more than once per entry.</para>
 396         </listitem>
 397       </varlistentry>
 398     </variablelist>
 399   </refsect1>
 400
 401   <refsect1>
 402     <title>Fields to log on behalf of a different program</title>
 403
 404     <para>Fields in this section are used by programs to specify that
 405     they are logging on behalf of another program or unit.
 406     </para>
 407
 408     <para>Fields used by the <command>systemd-coredump</command>
 409     coredump kernel helper:
 410     </para>
 411
 412     <variablelist class='journal-directives'>
 413       <varlistentry>
 414         <term><varname>COREDUMP_UNIT=</varname></term>
 415         <term><varname>COREDUMP_USER_UNIT=</varname></term>
 416         <listitem>
 417           <para>Used to annotate messages containing coredumps from
 418           system and session units. See
 419           <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 420           </para>
 421         </listitem>
 422       </varlistentry>
 423     </variablelist>
 424
 425     <para>Privileged programs (currently UID 0) may attach
 426     <varname>OBJECT_PID=</varname> to a message. This will instruct
 427     <command>systemd-journald</command> to attach additional fields on
 428     behalf of the caller:</para>
 429
 430     <variablelist class='journal-directives'>
 431       <varlistentry>
 432         <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
 433         <listitem>
 434           <para>PID of the program that this message pertains to.
 435           </para>
 436         </listitem>
 437       </varlistentry>
 438
 439       <varlistentry>
 440         <term><varname>OBJECT_UID=</varname></term>
 441         <term><varname>OBJECT_GID=</varname></term>
 442         <term><varname>OBJECT_COMM=</varname></term>
 443         <term><varname>OBJECT_EXE=</varname></term>
 444         <term><varname>OBJECT_CMDLINE=</varname></term>
 445         <term><varname>OBJECT_AUDIT_SESSION=</varname></term>
 446         <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
 447         <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
 448         <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
 449         <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
 450         <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
 451         <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
 452         <listitem>
 453           <para>These are additional fields added automatically by
 454           <command>systemd-journald</command>. Their meaning is the
 455           same as
 456           <varname>_UID=</varname>,
 457           <varname>_GID=</varname>,
 458           <varname>_COMM=</varname>,
 459           <varname>_EXE=</varname>,
 460           <varname>_CMDLINE=</varname>,
 461           <varname>_AUDIT_SESSION=</varname>,
 462           <varname>_AUDIT_LOGINUID=</varname>,
 463           <varname>_SYSTEMD_CGROUP=</varname>,
 464           <varname>_SYSTEMD_SESSION=</varname>,
 465           <varname>_SYSTEMD_UNIT=</varname>,
 466           <varname>_SYSTEMD_USER_UNIT=</varname>, and
 467           <varname>_SYSTEMD_OWNER_UID=</varname>
 468           as described above, except that the process identified by
 469           <replaceable>PID</replaceable> is described, instead of the
 470           process which logged the message.</para>
 471         </listitem>
 472       </varlistentry>
 473     </variablelist>
 474
 475   </refsect1>
 476
 477   <refsect1>
 478     <title>Address Fields</title>
 479
 480     <para>During serialization into external formats, such as the
 481     <ulink
 482     url="https://www.freedesktop.org/wiki/Software/systemd/export">Journal
 483     Export Format</ulink> or the <ulink
 484     url="https://www.freedesktop.org/wiki/Software/systemd/json">Journal
 485     JSON Format</ulink>, the addresses of journal entries are
 486     serialized into fields prefixed with double underscores. Note that
 487     these are not proper fields when stored in the journal but for
 488     addressing metadata of entries. They cannot be written as part of
 489     structured log entries via calls such as
 490     <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 491     They may also not be used as matches for
 492     <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
 493
 494     <variablelist class='journal-directives'>
 495       <varlistentry>
 496         <term><varname>__CURSOR=</varname></term>
 497         <listitem>
 498           <para>The cursor for the entry. A cursor is an opaque text
 499           string that uniquely describes the position of an entry in
 500           the journal and is portable across machines, platforms and
 501           journal files.
 502           </para>
 503         </listitem>
 504       </varlistentry>
 505
 506       <varlistentry>
 507         <term><varname>__REALTIME_TIMESTAMP=</varname></term>
 508         <listitem>
 509           <para>The wallclock time
 510           (<constant>CLOCK_REALTIME</constant>) at the point in time
 511           the entry was received by the journal, in microseconds since
 512           the epoch UTC, formatted as a decimal string. This has
 513           different properties from
 514           <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>, as it is
 515           usually a bit later but more likely to be monotonic.
 516           </para>
 517         </listitem>
 518       </varlistentry>
 519
 520       <varlistentry>
 521         <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
 522         <listitem>
 523           <para>The monotonic time
 524           (<constant>CLOCK_MONOTONIC</constant>) at the point in time
 525           the entry was received by the journal in microseconds,
 526           formatted as a decimal string. To be useful as an address
 527           for the entry, this should be combined with the boot ID in
 528           <literal>_BOOT_ID=</literal>.
 529           </para>
 530         </listitem>
 531       </varlistentry>
 532     </variablelist>
 533   </refsect1>
 534
 535   <refsect1>
 536       <title>See Also</title>
 537       <para>
 538         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 539         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 540         <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 541         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 542         <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 543         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 544       </para>
 545   </refsect1>
 546
 547 </refentry>