chiark / gitweb /
build-sys: make PolicyKit support compile-time optional (was runtime-optional already)
[elogind.git] / man / systemd.journal-fields.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="systemd.journal-fields">
25
26         <refentryinfo>
27                 <title>systemd.journal-fields</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>systemd.journal-fields</refentrytitle>
42                 <manvolnum>7</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>systemd.journal-fields</refname>
47                 <refpurpose>Special journal fields</refpurpose>
48         </refnamediv>
49
50         <refsect1>
51                 <title>Description</title>
52
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>
63         </refsect1>
64
65         <refsect1>
66                 <title>User Journal Fields</title>
67
68                 <para>User fields are fields that are directly passed
69                 from clients and stored in the journal.</para>
70
71                 <variablelist class='journal-directives'>
72                         <varlistentry>
73                                 <term><varname>MESSAGE=</varname></term>
74                                 <listitem>
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
83                                         data.</para>
84                                 </listitem>
85                         </varlistentry>
86
87                         <varlistentry>
88                                 <term><varname>MESSAGE_ID=</varname></term>
89                                 <listitem>
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
103                                         purpose with
104                                         <command>journalctl
105                                         --new-id</command>.</para>
106                                 </listitem>
107                         </varlistentry>
108
109                         <varlistentry>
110                                 <term><varname>PRIORITY=</varname></term>
111                                 <listitem>
112                                         <para>A priority value between
113                                         0 (<literal>emerg</literal>)
114                                         and 7
115                                         (<literal>debug</literal>)
116                                         formatted as decimal
117                                         string. This field is
118                                         compatible with syslog's
119                                         priority concept.</para>
120                                 </listitem>
121                         </varlistentry>
122
123                         <varlistentry>
124                                 <term><varname>CODE_FILE=</varname></term>
125                                 <term><varname>CODE_LINE=</varname></term>
126                                 <term><varname>CODE_FUNC=</varname></term>
127                                 <listitem>
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>
133                                 </listitem>
134                         </varlistentry>
135
136                         <varlistentry>
137                                 <term><varname>ERRNO=</varname></term>
138                                 <listitem>
139                                         <para>The low-level Unix error
140                                         number causing this entry, if
141                                         any. Contains the numeric
142                                         value of
143                                         <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
144                                         formatted as decimal
145                                         string.</para>
146                                 </listitem>
147                         </varlistentry>
148
149                         <varlistentry>
150                                 <term><varname>SYSLOG_FACILITY=</varname></term>
151                                 <term><varname>SYSLOG_IDENTIFIER=</varname></term>
152                                 <term><varname>SYSLOG_PID=</varname></term>
153                                 <listitem>
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.</para>
160                                 </listitem>
161
162                         </varlistentry>
163                 </variablelist>
164         </refsect1>
165
166         <refsect1>
167                 <title>Trusted Journal Fields</title>
168
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>
172
173                 <variablelist class='journal-directives'>
174                         <varlistentry>
175                                 <term><varname>_PID=</varname></term>
176                                 <term><varname>_UID=</varname></term>
177                                 <term><varname>_GID=</varname></term>
178                                 <listitem>
179                                         <para>The process, user and
180                                         group ID of the process the
181                                         journal entry originates from
182                                         formatted as decimal
183                                         string.</para>
184                                 </listitem>
185                         </varlistentry>
186
187                         <varlistentry>
188                                 <term><varname>_COMM=</varname></term>
189                                 <term><varname>_EXE=</varname></term>
190                                 <term><varname>_CMDLINE=</varname></term>
191                                 <listitem>
192                                         <para>The name, the executable
193                                         path and the command line of
194                                         the process the journal entry
195                                         originates from.</para>
196                                 </listitem>
197                         </varlistentry>
198
199                         <varlistentry>
200                                 <term><varname>_AUDIT_SESSION=</varname></term>
201                                 <term><varname>_AUDIT_LOGINUID=</varname></term>
202                                 <listitem>
203                                         <para>The session and login
204                                         UID of the process the journal
205                                         entry originates from, as
206                                         maintained by the kernel audit
207                                         subsystem.</para>
208                                 </listitem>
209                         </varlistentry>
210
211                         <varlistentry>
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>
217
218                                 <listitem>
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>
228                                 </listitem>
229                         </varlistentry>
230
231                         <varlistentry>
232                                 <term><varname>_SELINUX_CONTEXT=</varname></term>
233                                 <listitem>
234                                         <para>The SELinux security
235                                         context of the process the
236                                         journal entry originates
237                                         from.</para>
238                                 </listitem>
239                         </varlistentry>
240
241                         <varlistentry>
242                                 <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
243                                 <listitem>
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                                         usec since the epoch UTC
250                                         formatted as decimal
251                                         string.</para>
252                                 </listitem>
253                         </varlistentry>
254
255                         <varlistentry>
256                                 <term><varname>_BOOT_ID=</varname></term>
257                                 <listitem>
258                                         <para>The kernel boot ID for
259                                         the boot the message was
260                                         generated in, formatted as
261                                         128bit hexadecimal
262                                         string.</para>
263                                 </listitem>
264                         </varlistentry>
265
266                         <varlistentry>
267                                 <term><varname>_MACHINE_ID=</varname></term>
268                                 <listitem>
269                                         <para>The machine ID of the
270                                         originating host, as available
271                                         in
272                                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
273                                 </listitem>
274                         </varlistentry>
275
276                         <varlistentry>
277                                 <term><varname>_HOSTNAME=</varname></term>
278                                 <listitem>
279                                         <para>The name of the
280                                         originating host.</para>
281                                 </listitem>
282                         </varlistentry>
283
284                         <varlistentry>
285                                 <term><varname>_TRANSPORT=</varname></term>
286                                 <listitem>
287                                         <para>How the entry was
288                                         received by the journal
289                                         service. One of
290                                         <literal>driver</literal>,
291                                         <literal>syslog</literal>,
292                                         <literal>journal</literal>,
293                                         <literal>stdout</literal>,
294                                         <literal>kernel</literal> for
295                                         internally generated messages,
296                                         for those received via the
297                                         local syslog socket with the
298                                         syslog protocol, for those
299                                         received via the native
300                                         journal protocol, for the
301                                         those read from a services'
302                                         standard output or error
303                                         output, or for those read
304                                         from the kernel, respectively.
305                                         </para>
306                                 </listitem>
307                         </varlistentry>
308                 </variablelist>
309         </refsect1>
310
311         <refsect1>
312                 <title>Kernel Journal Fields</title>
313
314                 <para>Kernel fields are fields that are used by
315                 messages originating in the kernel and stored in the
316                 journal.</para>
317
318                 <variablelist class='journal-directives'>
319                         <varlistentry>
320                                 <term><varname>_KERNEL_DEVICE=</varname></term>
321                                 <listitem>
322                                         <para>The kernel device
323                                         name. If the entry is
324                                         associated to a block device,
325                                         the major and minor of the
326                                         device node, separated by ':'
327                                         and prefixed by 'b'. Similar
328                                         for character devices, but
329                                         prefixed by 'c'. For network
330                                         devices the interface index,
331                                         prefixed by 'n'. For all other
332                                         devices '+' followed by the
333                                         subsystem name, followed by
334                                         ':', followed by the kernel
335                                         device name.</para>
336                                 </listitem>
337                         </varlistentry>
338                         <varlistentry>
339                                 <term><varname>_KERNEL_SUBSYSTEM=</varname></term>
340                                 <listitem>
341                                         <para>The kernel subsystem name.</para>
342                                 </listitem>
343                         </varlistentry>
344                         <varlistentry>
345                                 <term><varname>_UDEV_SYSNAME=</varname></term>
346                                 <listitem>
347                                         <para>The kernel device name
348                                         as it shows up in the device
349                                         tree below
350                                         <filename>/sys</filename>.</para>
351                                 </listitem>
352                         </varlistentry>
353                         <varlistentry>
354                                 <term><varname>_UDEV_DEVNODE=</varname></term>
355                                 <listitem>
356                                         <para>The device node path of
357                                         this device in
358                                         <filename>/dev</filename>.</para>
359                                 </listitem>
360                         </varlistentry>
361                         <varlistentry>
362                                 <term><varname>_UDEV_DEVLINK=</varname></term>
363                                 <listitem>
364                                         <para>Additional symlink names
365                                         pointing to the device node in
366                                         <filename>/dev</filename>. This
367                                         field is frequently set more
368                                         than once per entry.</para>
369                                 </listitem>
370                         </varlistentry>
371                 </variablelist>
372         </refsect1>
373
374         <refsect1>
375                 <title>Special Journal Fields</title>
376
377                 <para>Fields used by the <command>systemd-coredump</command>
378                 coredump kernel helper.
379                 </para>
380
381                 <variablelist class='journal-directives'>
382                         <varlistentry>
383                                 <term><varname>COREDUMP_UNIT=</varname></term>
384                                 <term><varname>COREDUMP_USER_UNIT=</varname></term>
385                                 <listitem>
386                                         <para>Used to annotate
387                                         messages containing coredumps from
388                                         system and session units.
389                                         See
390                                         <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
391                                         </para>
392                                 </listitem>
393                         </varlistentry>
394                 </variablelist>
395         </refsect1>
396
397         <refsect1>
398                 <title>Address Fields</title>
399
400                 <para>During serialization into external formats, such
401                 as the <ulink
402                 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
403                 Export Format</ulink> or the <ulink
404                 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
405                 JSON Format</ulink>, the addresses of journal entries
406                 are serialized into fields prefixed with double
407                 underscores. Note that these aren't proper fields when
408                 stored in the journal, but addressing meta data of
409                 entries. They cannot be written as part of structured
410                 log entries via calls such as
411                 <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
412                 may also not be used as matches for
413                 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
414
415                 <variablelist class='journal-directives'>
416                         <varlistentry>
417                                 <term><varname>__CURSOR=</varname></term>
418                                 <listitem>
419                                         <para>The cursor for the
420                                         entry. A cursor is an opaque
421                                         text string that uniquely
422                                         describes the position of an
423                                         entry in the journal and is
424                                         portable across machines,
425                                         platforms and journal
426                                         files.</para>
427                                 </listitem>
428                         </varlistentry>
429
430                         <varlistentry>
431                                 <term><varname>__REALTIME_TIMESTAMP=</varname></term>
432                                 <listitem>
433                                         <para>The wallclock time
434                                         (CLOCK_REALTIME) at the point
435                                         in time the entry was received
436                                         by the journal, in usec since
437                                         the epoch UTC formatted as
438                                         decimal string. This has
439                                         different properties from
440                                         <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>
441                                         as it is usually a bit later
442                                         but more likely to be
443                                         monotonic.</para>
444                                 </listitem>
445                         </varlistentry>
446
447                         <varlistentry>
448                                 <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
449                                 <listitem>
450                                         <para>The monotonic time
451                                         (CLOCK_MONOTONIC) at the point
452                                         in time the entry was received
453                                         by the journal in usec
454                                         formatted as decimal
455                                         string. To be useful as an
456                                         address for the entry this
457                                         should be combined with with
458                                         boot ID in
459                                         <literal>_BOOT_ID=</literal>.</para>
460                                 </listitem>
461                         </varlistentry>
462                 </variablelist>
463         </refsect1>
464
465         <refsect1>
466                   <title>See Also</title>
467                   <para>
468                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
469                           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
470                           <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
471                           <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
472                           <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
473                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
474                   </para>
475         </refsect1>
476
477 </refentry>