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 but 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 project='man-pages'><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
159 PID. (Note that the tag is
160 usually derived from glibc's
161 <varname>program_invocation_short_name</varname>
162 variable, see <citerefentry><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para>
170 <title>Trusted Journal Fields</title>
172 <para>Fields prefixed with an underscore are trusted
173 fields, i.e. fields that are implicitly added by the
174 journal and cannot be altered by client code.</para>
176 <variablelist class='journal-directives'>
178 <term><varname>_PID=</varname></term>
179 <term><varname>_UID=</varname></term>
180 <term><varname>_GID=</varname></term>
182 <para>The process, user, and
183 group ID of the process the
184 journal entry originates from
185 formatted as a decimal
191 <term><varname>_COMM=</varname></term>
192 <term><varname>_EXE=</varname></term>
193 <term><varname>_CMDLINE=</varname></term>
195 <para>The name, the executable
196 path, and the command line of
197 the process the journal entry
198 originates from.</para>
203 <term><varname>_CAP_EFFECTIVE=</varname></term>
205 <para>The effective <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> of
206 the process the journal entry
207 originates from.</para>
212 <term><varname>_AUDIT_SESSION=</varname></term>
213 <term><varname>_AUDIT_LOGINUID=</varname></term>
215 <para>The session and login
216 UID of the process the journal
217 entry originates from, as
218 maintained by the kernel audit
224 <term><varname>_SYSTEMD_CGROUP=</varname></term>
225 <term><varname>_SYSTEMD_SESSION=</varname></term>
226 <term><varname>_SYSTEMD_UNIT=</varname></term>
227 <term><varname>_SYSTEMD_USER_UNIT=</varname></term>
228 <term><varname>_SYSTEMD_OWNER_UID=</varname></term>
229 <term><varname>_SYSTEMD_SLICE=</varname></term>
232 <para>The control group path
233 in the systemd hierarchy, the
234 systemd session ID (if any),
235 the systemd unit name (if
236 any), the systemd user session
237 unit name (if any), the owner
238 UID of the systemd session (if
239 any) and the systemd slice
240 unit of the process the
241 journal entry originates
247 <term><varname>_SELINUX_CONTEXT=</varname></term>
249 <para>The SELinux security
250 context (label) of the process
251 the journal entry originates
257 <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
259 <para>The earliest trusted
260 timestamp of the message, if
261 any is known that is different
262 from the reception time of the
263 journal. This is the time in
264 microseconds since the epoch UTC,
265 formatted as a decimal
271 <term><varname>_BOOT_ID=</varname></term>
273 <para>The kernel boot ID for
274 the boot the message was
275 generated in, formatted as
276 a 128-bit hexadecimal
282 <term><varname>_MACHINE_ID=</varname></term>
284 <para>The machine ID of the
285 originating host, as available
287 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
292 <term><varname>_HOSTNAME=</varname></term>
294 <para>The name of the
295 originating host.</para>
300 <term><varname>_TRANSPORT=</varname></term>
302 <para>How the entry was
303 received by the journal
304 service. Valid transports are:
309 <option>driver</option>
322 <option>syslog</option>
336 <option>journal</option>
349 <option>stdout</option>
363 <option>kernel</option>
379 <title>Kernel Journal Fields</title>
381 <para>Kernel fields are fields that are used by
382 messages originating in the kernel and stored in the
385 <variablelist class='journal-directives'>
387 <term><varname>_KERNEL_DEVICE=</varname></term>
389 <para>The kernel device
390 name. If the entry is
391 associated to a block device,
392 the major and minor of the
393 device node, separated by <literal>:</literal>
394 and prefixed by <literal>b</literal>. Similar
395 for character devices but
396 prefixed by <literal>c</literal>. For network
397 devices, this is the interface index
398 prefixed by <literal>n</literal>. For all other
399 devices, this is the subsystem name
400 prefixed by <literal>+</literal>, followed by
401 <literal>:</literal>, followed by the kernel
406 <term><varname>_KERNEL_SUBSYSTEM=</varname></term>
408 <para>The kernel subsystem name.</para>
412 <term><varname>_UDEV_SYSNAME=</varname></term>
414 <para>The kernel device name
415 as it shows up in the device
417 <filename>/sys</filename>.</para>
421 <term><varname>_UDEV_DEVNODE=</varname></term>
423 <para>The device node path of
425 <filename>/dev</filename>.</para>
429 <term><varname>_UDEV_DEVLINK=</varname></term>
431 <para>Additional symlink names
432 pointing to the device node in
433 <filename>/dev</filename>. This
434 field is frequently set more
435 than once per entry.</para>
442 <title>Fields to log on behalf of a different program</title>
444 <para>Fields in this section are used by programs
445 to specify that they are logging on behalf of another
449 <para>Fields used by the <command>systemd-coredump</command>
450 coredump kernel helper:
453 <variablelist class='journal-directives'>
455 <term><varname>COREDUMP_UNIT=</varname></term>
456 <term><varname>COREDUMP_USER_UNIT=</varname></term>
458 <para>Used to annotate
459 messages containing coredumps from
460 system and session units.
462 <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
468 <para>Priviledged programs (currently UID 0) may
469 attach <varname>OBJECT_PID=</varname> to a
470 message. This will instruct
471 <command>systemd-journald</command> to attach
472 additional fields on behalf of the caller:</para>
474 <variablelist class='journal-directives'>
476 <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
478 <para>PID of the program that this
485 <term><varname>OBJECT_UID=</varname></term>
486 <term><varname>OBJECT_GID=</varname></term>
487 <term><varname>OBJECT_COMM=</varname></term>
488 <term><varname>OBJECT_EXE=</varname></term>
489 <term><varname>OBJECT_CMDLINE=</varname></term>
490 <term><varname>OBJECT_AUDIT_SESSION=</varname></term>
491 <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
492 <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
493 <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
494 <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
495 <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
496 <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
498 <para>These are additional fields added automatically
499 by <command>systemd-journald</command>.
500 Their meaning is the same as
501 <varname>_UID=</varname>,
502 <varname>_GID=</varname>,
503 <varname>_COMM=</varname>,
504 <varname>_EXE=</varname>,
505 <varname>_CMDLINE=</varname>,
506 <varname>_AUDIT_SESSION=</varname>,
507 <varname>_AUDIT_LOGINUID=</varname>,
508 <varname>_SYSTEMD_CGROUP=</varname>,
509 <varname>_SYSTEMD_SESSION=</varname>,
510 <varname>_SYSTEMD_UNIT=</varname>,
511 <varname>_SYSTEMD_USER_UNIT=</varname>, and
512 <varname>_SYSTEMD_OWNER_UID=</varname>
513 as described above, except that the
514 process identified by <replaceable>PID</replaceable>
515 is described, instead of the process
516 which logged the message.</para>
525 <title>Address Fields</title>
527 <para>During serialization into external formats, such
529 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
530 Export Format</ulink> or the <ulink
531 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
532 JSON Format</ulink>, the addresses of journal entries
533 are serialized into fields prefixed with double
534 underscores. Note that these are not proper fields when
535 stored in the journal but for addressing metadata of
536 entries. They cannot be written as part of structured
537 log entries via calls such as
538 <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
539 may also not be used as matches for
540 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
542 <variablelist class='journal-directives'>
544 <term><varname>__CURSOR=</varname></term>
546 <para>The cursor for the
547 entry. A cursor is an opaque
548 text string that uniquely
549 describes the position of an
550 entry in the journal and is
551 portable across machines,
552 platforms and journal files.
558 <term><varname>__REALTIME_TIMESTAMP=</varname></term>
560 <para>The wallclock time
561 (<constant>CLOCK_REALTIME</constant>)
562 at the point in time the entry
563 was received by the journal,
564 in microseconds since the epoch
565 UTC, formatted as a decimal
566 string. This has different
568 <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,
569 as it is usually a bit later
570 but more likely to be monotonic.
576 <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
578 <para>The monotonic time
579 (<constant>CLOCK_MONOTONIC</constant>)
580 at the point in time the entry
581 was received by the journal in
582 microseconds, formatted as a decimal
583 string. To be useful as an
584 address for the entry, this
585 should be combined with the
586 boot ID in <literal>_BOOT_ID=</literal>.
594 <title>See Also</title>
596 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
597 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
598 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
599 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
600 <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
601 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>