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 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemd.journal-fields">
27 <title>systemd.journal-fields</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd.journal-fields</refentrytitle>
42 <manvolnum>7</manvolnum>
46 <refname>systemd.journal-fields</refname>
47 <refpurpose>Special journal fields</refpurpose>
51 <title>Description</title>
53 <para>Entries in the journal resemble an environment
54 block in their syntax, however with fields that can
55 include binary data. Primarily, fields are formatted
56 UTF-8 text strings, and binary formatting is used only
57 where formatting as UTF-8 text strings makes little
58 sense. New fields may freely be defined by
59 applications, but a few fields have special
60 meaning. All fields with special meanings are
61 optional. In some cases fields may appear more than
62 once per entry.</para>
66 <title>User Journal Fields</title>
68 <para>User fields are fields that are directly passed
69 from clients and stored in the journal.</para>
71 <variablelist class='journal-directives'>
73 <term><varname>MESSAGE=</varname></term>
75 <para>The human-readable
76 message string for this
77 entry. This is supposed to be
78 the primary text shown to the
79 user. It is usually not
80 translated (but might be in
81 some cases), and is not
82 supposed to be parsed for meta
88 <term><varname>MESSAGE_ID=</varname></term>
90 <para>A 128-bit message
91 identifier ID for recognizing
92 certain message types, if this
93 is desirable. This should
94 contain a 128-bit ID formatted
95 as a lower-case hexadecimal
96 string, without any separating
97 dashes or suchlike. This is
99 UUID-compatible ID, but this is not
100 enforced, and formatted
101 differently. Developers can
102 generate a new ID for this
103 purpose with <command>journalctl
104 <option>--new-id</option></command>.
110 <term><varname>PRIORITY=</varname></term>
112 <para>A priority value between
113 0 (<literal>emerg</literal>)
115 (<literal>debug</literal>)
116 formatted as a decimal
117 string. This field is
118 compatible with syslog's
119 priority concept.</para>
124 <term><varname>CODE_FILE=</varname></term>
125 <term><varname>CODE_LINE=</varname></term>
126 <term><varname>CODE_FUNC=</varname></term>
128 <para>The code location
129 generating this message, if
130 known. Contains the source
131 filename, the line number and
132 the function name.</para>
137 <term><varname>ERRNO=</varname></term>
139 <para>The low-level Unix error
140 number causing this entry, if
141 any. Contains the numeric
143 <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
144 formatted as a decimal
150 <term><varname>SYSLOG_FACILITY=</varname></term>
151 <term><varname>SYSLOG_IDENTIFIER=</varname></term>
152 <term><varname>SYSLOG_PID=</varname></term>
154 <para>Syslog compatibility
155 fields containing the facility
156 (formatted as decimal string),
157 the identifier string
158 (i.e. "tag"), and the client
167 <title>Trusted Journal Fields</title>
169 <para>Fields prefixed with an underscore are trusted
170 fields, i.e. fields that are implicitly added by the
171 journal and cannot be altered by client code.</para>
173 <variablelist class='journal-directives'>
175 <term><varname>_PID=</varname></term>
176 <term><varname>_UID=</varname></term>
177 <term><varname>_GID=</varname></term>
179 <para>The process, user and
180 group ID of the process the
181 journal entry originates from
182 formatted as a decimal
188 <term><varname>_COMM=</varname></term>
189 <term><varname>_EXE=</varname></term>
190 <term><varname>_CMDLINE=</varname></term>
192 <para>The name, the executable
193 path and the command line of
194 the process the journal entry
195 originates from.</para>
200 <term><varname>_AUDIT_SESSION=</varname></term>
201 <term><varname>_AUDIT_LOGINUID=</varname></term>
203 <para>The session and login
204 UID of the process the journal
205 entry originates from, as
206 maintained by the kernel audit
212 <term><varname>_SYSTEMD_CGROUP=</varname></term>
213 <term><varname>_SYSTEMD_SESSION=</varname></term>
214 <term><varname>_SYSTEMD_UNIT=</varname></term>
215 <term><varname>_SYSTEMD_USER_UNIT=</varname></term>
216 <term><varname>_SYSTEMD_OWNER_UID=</varname></term>
219 <para>The control group path in
220 the systemd hierarchy, the
221 systemd session ID (if any),
222 the systemd unit name (if any),
223 the systemd user session unit name (if any)
224 and the owner UID of the
225 systemd session (if any) of
226 the process the journal entry
227 originates from.</para>
232 <term><varname>_SELINUX_CONTEXT=</varname></term>
234 <para>The SELinux security
235 context of the process the
236 journal entry originates
242 <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
244 <para>The earliest trusted
245 timestamp of the message, if
246 any is known that is different
247 from the reception time of the
248 journal. This is the time in
249 microseconds since the epoch UTC,
250 formatted as a decimal
256 <term><varname>_BOOT_ID=</varname></term>
258 <para>The kernel boot ID for
259 the boot the message was
260 generated in, formatted as
261 a 128-bit hexadecimal
267 <term><varname>_MACHINE_ID=</varname></term>
269 <para>The machine ID of the
270 originating host, as available
272 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
277 <term><varname>_HOSTNAME=</varname></term>
279 <para>The name of the
280 originating host.</para>
285 <term><varname>_TRANSPORT=</varname></term>
287 <para>How the entry was
288 received by the journal
289 service. Valid transports are:
294 <option>driver</option>
307 <option>syslog</option>
321 <option>journal</option>
334 <option>stdout</option>
348 <option>kernel</option>
364 <title>Kernel Journal Fields</title>
366 <para>Kernel fields are fields that are used by
367 messages originating in the kernel and stored in the
370 <variablelist class='journal-directives'>
372 <term><varname>_KERNEL_DEVICE=</varname></term>
374 <para>The kernel device
375 name. If the entry is
376 associated to a block device,
377 the major and minor of the
378 device node, separated by <literal>:</literal>
379 and prefixed by <literal>b</literal>. Similar
380 for character devices, but
381 prefixed by <literal>c</literal>. For network
382 devices the interface index,
383 prefixed by <literal>n</literal>. For all other
384 devices <literal>+</literal> followed by the
385 subsystem name, followed by
386 <literal>:</literal>, followed by the kernel
391 <term><varname>_KERNEL_SUBSYSTEM=</varname></term>
393 <para>The kernel subsystem name.</para>
397 <term><varname>_UDEV_SYSNAME=</varname></term>
399 <para>The kernel device name
400 as it shows up in the device
402 <filename>/sys</filename>.</para>
406 <term><varname>_UDEV_DEVNODE=</varname></term>
408 <para>The device node path of
410 <filename>/dev</filename>.</para>
414 <term><varname>_UDEV_DEVLINK=</varname></term>
416 <para>Additional symlink names
417 pointing to the device node in
418 <filename>/dev</filename>. This
419 field is frequently set more
420 than once per entry.</para>
427 <title>Fields to log on behalf of a different program</title>
429 <para>Fields in this section are used by programs
430 to specify that they are logging on behalf of another
434 <para>Fields used by the <command>systemd-coredump</command>
435 coredump kernel helper:
438 <variablelist class='journal-directives'>
440 <term><varname>COREDUMP_UNIT=</varname></term>
441 <term><varname>COREDUMP_USER_UNIT=</varname></term>
443 <para>Used to annotate
444 messages containing coredumps from
445 system and session units.
447 <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
453 <para>Priviledged programs (currently UID 0) may
454 attach <varname>OBJECT_PID=</varname> to a
455 message. This will instruct
456 <command>systemd-journald</command> to attach
457 additional fields on behalf of caller:</para>
459 <variablelist class='journal-directives'>
461 <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
463 <para>PID of the program that this
470 <term><varname>OBJECT_UID=</varname></term>
471 <term><varname>OBJECT_GID=</varname></term>
472 <term><varname>OBJECT_COMM=</varname></term>
473 <term><varname>OBJECT_EXE=</varname></term>
474 <term><varname>OBJECT_CMDLINE=</varname></term>
475 <term><varname>OBJECT_AUDIT_SESSION=</varname></term>
476 <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
477 <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
478 <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
479 <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
480 <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
481 <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
483 <para>Additional fields added automatically
484 by <command>systemd-journald</command>.
485 Their meaning is the same as
486 <varname>_UID=</varname>,
487 <varname>_GID=</varname>,
488 <varname>_COMM=</varname>,
489 <varname>_EXE=</varname>,
490 <varname>_CMDLINE=</varname>,
491 <varname>_AUDIT_SESSION=</varname>,
492 <varname>_AUDIT_LOGINUID=</varname>,
493 <varname>_SYSTEMD_CGROUP=</varname>,
494 <varname>_SYSTEMD_SESSION=</varname>,
495 <varname>_SYSTEMD_UNIT=</varname>,
496 <varname>_SYSTEMD_USER_UNIT=</varname>, and
497 <varname>_SYSTEMD_OWNER_UID=</varname>
498 described above, except that
499 process <replaceable>PID</replaceable>
500 is described, instead of the process
501 which logged the message.</para>
510 <title>Address Fields</title>
512 <para>During serialization into external formats, such
514 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
515 Export Format</ulink> or the <ulink
516 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
517 JSON Format</ulink>, the addresses of journal entries
518 are serialized into fields prefixed with double
519 underscores. Note that these aren't proper fields when
520 stored in the journal but for addressing meta data of
521 entries. They cannot be written as part of structured
522 log entries via calls such as
523 <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
524 may also not be used as matches for
525 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
527 <variablelist class='journal-directives'>
529 <term><varname>__CURSOR=</varname></term>
531 <para>The cursor for the
532 entry. A cursor is an opaque
533 text string that uniquely
534 describes the position of an
535 entry in the journal and is
536 portable across machines,
537 platforms and journal files.
543 <term><varname>__REALTIME_TIMESTAMP=</varname></term>
545 <para>The wallclock time
546 (<constant>CLOCK_REALTIME</constant>)
547 at the point in time the entry
548 was received by the journal,
549 in microseconds since the epoch
550 UTC, formatted as a decimal
551 string. This has different
553 <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,
554 as it is usually a bit later
555 but more likely to be monotonic.
561 <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
563 <para>The monotonic time
564 (<constant>CLOCK_MONOTONIC</constant>)
565 at the point in time the entry
566 was received by the journal in
567 microseconds, formatted as a decimal
568 string. To be useful as an
569 address for the entry, this
570 should be combined with with the
571 boot ID in <literal>_BOOT_ID=</literal>.
579 <title>See Also</title>
581 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
582 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
583 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
584 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
585 <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
586 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>