chiark / gitweb /
service: add FailureAction= option
[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 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>
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 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
98                                         recommended to be a
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>.
105                                         </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 a 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                                         filename, 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 a 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. (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>
163                                 </listitem>
164
165                         </varlistentry>
166                 </variablelist>
167         </refsect1>
168
169         <refsect1>
170                 <title>Trusted Journal Fields</title>
171
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>
175
176                 <variablelist class='journal-directives'>
177                         <varlistentry>
178                                 <term><varname>_PID=</varname></term>
179                                 <term><varname>_UID=</varname></term>
180                                 <term><varname>_GID=</varname></term>
181                                 <listitem>
182                                         <para>The process, user, and
183                                         group ID of the process the
184                                         journal entry originates from
185                                         formatted as a decimal
186                                         string.</para>
187                                 </listitem>
188                         </varlistentry>
189
190                         <varlistentry>
191                                 <term><varname>_COMM=</varname></term>
192                                 <term><varname>_EXE=</varname></term>
193                                 <term><varname>_CMDLINE=</varname></term>
194                                 <listitem>
195                                         <para>The name, the executable
196                                         path, and the command line of
197                                         the process the journal entry
198                                         originates from.</para>
199                                 </listitem>
200                         </varlistentry>
201
202                         <varlistentry>
203                                 <term><varname>_CAP_EFFECTIVE=</varname></term>
204                                 <listitem>
205                                         <para>The effective <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> of
206                                         the process the journal entry
207                                         originates from.</para>
208                                 </listitem>
209                         </varlistentry>
210
211                         <varlistentry>
212                                 <term><varname>_AUDIT_SESSION=</varname></term>
213                                 <term><varname>_AUDIT_LOGINUID=</varname></term>
214                                 <listitem>
215                                         <para>The session and login
216                                         UID of the process the journal
217                                         entry originates from, as
218                                         maintained by the kernel audit
219                                         subsystem.</para>
220                                 </listitem>
221                         </varlistentry>
222
223                         <varlistentry>
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>
230
231                                 <listitem>
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
242                                         from.</para>
243                                 </listitem>
244                         </varlistentry>
245
246                         <varlistentry>
247                                 <term><varname>_SELINUX_CONTEXT=</varname></term>
248                                 <listitem>
249                                         <para>The SELinux security
250                                         context (label) of the process
251                                         the journal entry originates
252                                         from.</para>
253                                 </listitem>
254                         </varlistentry>
255
256                         <varlistentry>
257                                 <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
258                                 <listitem>
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
266                                         string.</para>
267                                 </listitem>
268                         </varlistentry>
269
270                         <varlistentry>
271                                 <term><varname>_BOOT_ID=</varname></term>
272                                 <listitem>
273                                         <para>The kernel boot ID for
274                                         the boot the message was
275                                         generated in, formatted as
276                                         a 128-bit hexadecimal
277                                         string.</para>
278                                 </listitem>
279                         </varlistentry>
280
281                         <varlistentry>
282                                 <term><varname>_MACHINE_ID=</varname></term>
283                                 <listitem>
284                                         <para>The machine ID of the
285                                         originating host, as available
286                                         in
287                                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
288                                 </listitem>
289                         </varlistentry>
290
291                         <varlistentry>
292                                 <term><varname>_HOSTNAME=</varname></term>
293                                 <listitem>
294                                         <para>The name of the
295                                         originating host.</para>
296                                 </listitem>
297                         </varlistentry>
298
299                         <varlistentry>
300                                 <term><varname>_TRANSPORT=</varname></term>
301                                 <listitem>
302                                         <para>How the entry was
303                                         received by the journal
304                                         service. Valid transports are:
305                                         </para>
306                                         <variablelist>
307                                                 <varlistentry>
308                                                         <term>
309                                                                 <option>driver</option>
310                                                         </term>
311                                                         <listitem>
312                                                                 <para>for
313                                                                 internally
314                                                                 generated
315                                                                 messages
316                                                                 </para>
317                                                         </listitem>
318                                                 </varlistentry>
319
320                                                 <varlistentry>
321                                                         <term>
322                                                                 <option>syslog</option>
323                                                         </term>
324                                                         <listitem>
325                                                                 <para>for those
326                                                                 received via the
327                                                                 local syslog
328                                                                 socket with the
329                                                                 syslog protocol
330                                                                 </para>
331                                                         </listitem>
332                                                 </varlistentry>
333
334                                                 <varlistentry>
335                                                         <term>
336                                                                 <option>journal</option>
337                                                         </term>
338                                                         <listitem>
339                                                                 <para>for those
340                                                                 received via the
341                                                                 native journal
342                                                                 protocol
343                                                                 </para>
344                                                         </listitem>
345                                                 </varlistentry>
346
347                                                 <varlistentry>
348                                                         <term>
349                                                                 <option>stdout</option>
350                                                         </term>
351                                                         <listitem>
352                                                                 <para>for those
353                                                                 read from a
354                                                                 service's
355                                                                 standard output
356                                                                 or error output
357                                                                 </para>
358                                                         </listitem>
359                                                 </varlistentry>
360
361                                                 <varlistentry>
362                                                         <term>
363                                                                 <option>kernel</option>
364                                                         </term>
365                                                         <listitem>
366                                                                 <para>for those
367                                                                 read from the
368                                                                 kernel
369                                                                 </para>
370                                                         </listitem>
371                                                 </varlistentry>
372                                         </variablelist>
373                                 </listitem>
374                         </varlistentry>
375                 </variablelist>
376         </refsect1>
377
378         <refsect1>
379                 <title>Kernel Journal Fields</title>
380
381                 <para>Kernel fields are fields that are used by
382                 messages originating in the kernel and stored in the
383                 journal.</para>
384
385                 <variablelist class='journal-directives'>
386                         <varlistentry>
387                                 <term><varname>_KERNEL_DEVICE=</varname></term>
388                                 <listitem>
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
402                                         device name.</para>
403                                 </listitem>
404                         </varlistentry>
405                         <varlistentry>
406                                 <term><varname>_KERNEL_SUBSYSTEM=</varname></term>
407                                 <listitem>
408                                         <para>The kernel subsystem name.</para>
409                                 </listitem>
410                         </varlistentry>
411                         <varlistentry>
412                                 <term><varname>_UDEV_SYSNAME=</varname></term>
413                                 <listitem>
414                                         <para>The kernel device name
415                                         as it shows up in the device
416                                         tree below
417                                         <filename>/sys</filename>.</para>
418                                 </listitem>
419                         </varlistentry>
420                         <varlistentry>
421                                 <term><varname>_UDEV_DEVNODE=</varname></term>
422                                 <listitem>
423                                         <para>The device node path of
424                                         this device in
425                                         <filename>/dev</filename>.</para>
426                                 </listitem>
427                         </varlistentry>
428                         <varlistentry>
429                                 <term><varname>_UDEV_DEVLINK=</varname></term>
430                                 <listitem>
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>
436                                 </listitem>
437                         </varlistentry>
438                 </variablelist>
439         </refsect1>
440
441         <refsect1>
442                 <title>Fields to log on behalf of a different program</title>
443
444                 <para>Fields in this section are used by programs
445                 to specify that they are logging on behalf of another
446                 program or unit.
447                 </para>
448
449                 <para>Fields used by the <command>systemd-coredump</command>
450                 coredump kernel helper:
451                 </para>
452
453                 <variablelist class='journal-directives'>
454                         <varlistentry>
455                                 <term><varname>COREDUMP_UNIT=</varname></term>
456                                 <term><varname>COREDUMP_USER_UNIT=</varname></term>
457                                 <listitem>
458                                         <para>Used to annotate
459                                         messages containing coredumps from
460                                         system and session units.
461                                         See
462                                         <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
463                                         </para>
464                                 </listitem>
465                         </varlistentry>
466                 </variablelist>
467
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>
473
474                 <variablelist class='journal-directives'>
475                         <varlistentry>
476                                 <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
477                                 <listitem>
478                                         <para>PID of the program that this
479                                         message pertains to.
480                                         </para>
481                                 </listitem>
482                         </varlistentry>
483
484                         <varlistentry>
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>
497                                 <listitem>
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>
517                                 </listitem>
518                         </varlistentry>
519                 </variablelist>
520
521
522         </refsect1>
523
524         <refsect1>
525                 <title>Address Fields</title>
526
527                 <para>During serialization into external formats, such
528                 as the <ulink
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>
541
542                 <variablelist class='journal-directives'>
543                         <varlistentry>
544                                 <term><varname>__CURSOR=</varname></term>
545                                 <listitem>
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.
553                                         </para>
554                                 </listitem>
555                         </varlistentry>
556
557                         <varlistentry>
558                                 <term><varname>__REALTIME_TIMESTAMP=</varname></term>
559                                 <listitem>
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
567                                         properties from
568                                         <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,
569                                         as it is usually a bit later
570                                         but more likely to be monotonic.
571                                         </para>
572                                 </listitem>
573                         </varlistentry>
574
575                         <varlistentry>
576                                 <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
577                                 <listitem>
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 with the
586                                         boot ID in <literal>_BOOT_ID=</literal>.
587                                         </para>
588                                 </listitem>
589                         </varlistentry>
590                 </variablelist>
591         </refsect1>
592
593         <refsect1>
594                   <title>See Also</title>
595                   <para>
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>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
601                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
602                   </para>
603         </refsect1>
604
605 </refentry>