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