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 128bit message
91 identifier ID for recognizing
92 certain message types, if this
93 is desirable. This should
94 contain a 128bit id formatted
95 as lower-case hexadecimal
96 string, without any separating
97 dashes or suchlike. This is
98 recommended to be a UUID
99 compatible ID, but this is not
100 enforced, and formatted
101 differently. Developers can
102 generate a new ID for this
105 --new-id</command>.</para>
110 <term><varname>PRIORITY=</varname></term>
112 <para>A priority value between
113 0 (<literal>emerg</literal>)
115 (<literal>debug</literal>)
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 file name, 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>
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
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_OWNER_UID=</varname></term>
218 <para>The control group path in
219 the systemd hierarchy, the
220 systemd session ID (if any),
221 the systemd unit name (if any)
222 and the owner UID of the
223 systemd session (if any) of
224 the process the journal entry
225 originates from.</para>
230 <term><varname>_SELINUX_CONTEXT=</varname></term>
232 <para>The SELinux security
233 context of the process the
234 journal entry originates
240 <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
242 <para>The earliest trusted
243 timestamp of the message, if
244 any is known that is different
245 from the reception time of the
246 journal. This is the time in
247 usec since the epoch UTC
254 <term><varname>_BOOT_ID=</varname></term>
256 <para>The kernel boot ID for
257 the boot the message was
258 generated in, formatted as
265 <term><varname>_MACHINE_ID=</varname></term>
267 <para>The machine ID of the
268 originating host, as available
270 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
275 <term><varname>_HOSTNAME=</varname></term>
277 <para>The name of the
278 originating host.</para>
283 <term><varname>_TRANSPORT=</varname></term>
285 <para>How the entry was
286 received by the journal
288 <literal>driver</literal>,
289 <literal>syslog</literal>,
290 <literal>journal</literal>,
291 <literal>stdout</literal>,
292 <literal>kernel</literal> for
293 internally generated messages,
294 for those received via the
295 local syslog socket with the
296 syslog protocol, for those
297 received via the native
298 journal protocol, for the
299 those read from a services'
300 standard output or error
301 output, or for those read
302 from the kernel, respectively.
310 <title>Kernel Journal Fields</title>
312 <para>Kernel fields are fields that are used by
313 messages originating in the kernel and stored in the
318 <term>_KERNEL_DEVICE=</term>
320 <para>The kernel device
321 name. If the entry is
322 associated to a block device,
323 the major and minor of the
324 device node, separated by ':'
325 and prefixed by 'b'. Similar
326 for character devices, but
327 prefixed by 'c'. For network
328 devices the interface index,
329 prefixed by 'n'. For all other
330 devices '+' followed by the
331 subsystem name, followed by
332 ':', followed by the kernel
337 <term>_KERNEL_SUBSYSTEM=</term>
339 <para>The kernel subsystem name.</para>
343 <term>_UDEV_SYSNAME=</term>
345 <para>The kernel device name
346 as it shows up in the device
348 <filename>/sys</filename>.</para>
352 <term>_UDEV_DEVNODE=</term>
354 <para>The device node path of
356 <filename>/dev</filename>.</para>
360 <term>_UDEV_DEVLINK=</term>
362 <para>Additional symlink names
363 pointing to the device node in
364 <filename>/dev</filename>. This
365 field is frequently set more
366 than once per entry.</para>
373 <title>Address Fields</title>
375 <para>During serialization into external formats, such
377 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
378 Export Format</ulink> or the <ulink
379 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
380 JSON Format</ulink>, the addresses of journal entries
381 are serialized into fields prefixed with double
382 underscores. Note that these aren't proper fields when
383 stored in the journal, but addressing meta data of
384 entries. They cannot be written as part of structured
385 log entries via calls such as
386 <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
387 may also not be used as matches for
388 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
390 <variablelist class='journal-directives'>
392 <term><varname>__CURSOR=</varname></term>
394 <para>The cursor for the
395 entry. A cursor is an opaque
396 text string that uniquely
397 describes the position of an
398 entry in the journal and is
399 portable across machines,
400 platforms and journal
406 <term><varname>__REALTIME_TIMESTAMP=</varname></term>
408 <para>The wallclock time
409 (CLOCK_REALTIME) at the point
410 in time the entry was received
411 by the journal, in usec since
412 the epoch UTC formatted as
413 decimal string. This has
414 different properties from
415 <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>
416 as it is usually a bit later
417 but more likely to be
423 <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
425 <para>The monotonic time
426 (CLOCK_MONOTONIC) at the point
427 in time the entry was received
428 by the journal in usec
430 string. To be useful as an
431 address for the entry this
432 should be combined with with
434 <literal>_BOOT_ID=</literal>.</para>
441 <title>See Also</title>
443 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
444 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
445 <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
446 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>