chiark / gitweb /
man: mention --runtime where appropriate
[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 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.</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 a 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>_CAP_EFFECTIVE=</varname></term>
201                                 <listitem>
202                                         <para>The effective <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> of
203                                         the process the journal entry
204                                         originates from.</para>
205                                 </listitem>
206                         </varlistentry>
207
208                         <varlistentry>
209                                 <term><varname>_AUDIT_SESSION=</varname></term>
210                                 <term><varname>_AUDIT_LOGINUID=</varname></term>
211                                 <listitem>
212                                         <para>The session and login
213                                         UID of the process the journal
214                                         entry originates from, as
215                                         maintained by the kernel audit
216                                         subsystem.</para>
217                                 </listitem>
218                         </varlistentry>
219
220                         <varlistentry>
221                                 <term><varname>_SYSTEMD_CGROUP=</varname></term>
222                                 <term><varname>_SYSTEMD_SESSION=</varname></term>
223                                 <term><varname>_SYSTEMD_UNIT=</varname></term>
224                                 <term><varname>_SYSTEMD_USER_UNIT=</varname></term>
225                                 <term><varname>_SYSTEMD_OWNER_UID=</varname></term>
226                                 <term><varname>_SYSTEMD_SLICE=</varname></term>
227
228                                 <listitem>
229                                         <para>The control group path
230                                         in the systemd hierarchy, the
231                                         systemd session ID (if any),
232                                         the systemd unit name (if
233                                         any), the systemd user session
234                                         unit name (if any), the owner
235                                         UID of the systemd session (if
236                                         any) and the systemd slice
237                                         unit of the process the
238                                         journal entry originates
239                                         from.</para>
240                                 </listitem>
241                         </varlistentry>
242
243                         <varlistentry>
244                                 <term><varname>_SELINUX_CONTEXT=</varname></term>
245                                 <listitem>
246                                         <para>The SELinux security
247                                         context of the process the
248                                         journal entry originates
249                                         from.</para>
250                                 </listitem>
251                         </varlistentry>
252
253                         <varlistentry>
254                                 <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
255                                 <listitem>
256                                         <para>The earliest trusted
257                                         timestamp of the message, if
258                                         any is known that is different
259                                         from the reception time of the
260                                         journal. This is the time in
261                                         microseconds since the epoch UTC,
262                                         formatted as a decimal
263                                         string.</para>
264                                 </listitem>
265                         </varlistentry>
266
267                         <varlistentry>
268                                 <term><varname>_BOOT_ID=</varname></term>
269                                 <listitem>
270                                         <para>The kernel boot ID for
271                                         the boot the message was
272                                         generated in, formatted as
273                                         a 128-bit hexadecimal
274                                         string.</para>
275                                 </listitem>
276                         </varlistentry>
277
278                         <varlistentry>
279                                 <term><varname>_MACHINE_ID=</varname></term>
280                                 <listitem>
281                                         <para>The machine ID of the
282                                         originating host, as available
283                                         in
284                                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
285                                 </listitem>
286                         </varlistentry>
287
288                         <varlistentry>
289                                 <term><varname>_HOSTNAME=</varname></term>
290                                 <listitem>
291                                         <para>The name of the
292                                         originating host.</para>
293                                 </listitem>
294                         </varlistentry>
295
296                         <varlistentry>
297                                 <term><varname>_TRANSPORT=</varname></term>
298                                 <listitem>
299                                         <para>How the entry was
300                                         received by the journal
301                                         service. Valid transports are:
302                                         </para>
303                                         <variablelist>
304                                                 <varlistentry>
305                                                         <term>
306                                                                 <option>driver</option>
307                                                         </term>
308                                                         <listitem>
309                                                                 <para>for
310                                                                 internally
311                                                                 generated
312                                                                 messages
313                                                                 </para>
314                                                         </listitem>
315                                                 </varlistentry>
316
317                                                 <varlistentry>
318                                                         <term>
319                                                                 <option>syslog</option>
320                                                         </term>
321                                                         <listitem>
322                                                                 <para>for those
323                                                                 received via the
324                                                                 local syslog
325                                                                 socket with the
326                                                                 syslog protocol
327                                                                 </para>
328                                                         </listitem>
329                                                 </varlistentry>
330
331                                                 <varlistentry>
332                                                         <term>
333                                                                 <option>journal</option>
334                                                         </term>
335                                                         <listitem>
336                                                                 <para>for those
337                                                                 received via the
338                                                                 native journal
339                                                                 protocol
340                                                                 </para>
341                                                         </listitem>
342                                                 </varlistentry>
343
344                                                 <varlistentry>
345                                                         <term>
346                                                                 <option>stdout</option>
347                                                         </term>
348                                                         <listitem>
349                                                                 <para>for those
350                                                                 read from a
351                                                                 service's
352                                                                 standard output
353                                                                 or error output
354                                                                 </para>
355                                                         </listitem>
356                                                 </varlistentry>
357
358                                                 <varlistentry>
359                                                         <term>
360                                                                 <option>kernel</option>
361                                                         </term>
362                                                         <listitem>
363                                                                 <para>for those
364                                                                 read from the
365                                                                 kernel
366                                                                 </para>
367                                                         </listitem>
368                                                 </varlistentry>
369                                         </variablelist>
370                                 </listitem>
371                         </varlistentry>
372                 </variablelist>
373         </refsect1>
374
375         <refsect1>
376                 <title>Kernel Journal Fields</title>
377
378                 <para>Kernel fields are fields that are used by
379                 messages originating in the kernel and stored in the
380                 journal.</para>
381
382                 <variablelist class='journal-directives'>
383                         <varlistentry>
384                                 <term><varname>_KERNEL_DEVICE=</varname></term>
385                                 <listitem>
386                                         <para>The kernel device
387                                         name. If the entry is
388                                         associated to a block device,
389                                         the major and minor of the
390                                         device node, separated by <literal>:</literal>
391                                         and prefixed by <literal>b</literal>. Similar
392                                         for character devices, but
393                                         prefixed by <literal>c</literal>. For network
394                                         devices the interface index,
395                                         prefixed by <literal>n</literal>. For all other
396                                         devices <literal>+</literal> followed by the
397                                         subsystem name, followed by
398                                         <literal>:</literal>, followed by the kernel
399                                         device name.</para>
400                                 </listitem>
401                         </varlistentry>
402                         <varlistentry>
403                                 <term><varname>_KERNEL_SUBSYSTEM=</varname></term>
404                                 <listitem>
405                                         <para>The kernel subsystem name.</para>
406                                 </listitem>
407                         </varlistentry>
408                         <varlistentry>
409                                 <term><varname>_UDEV_SYSNAME=</varname></term>
410                                 <listitem>
411                                         <para>The kernel device name
412                                         as it shows up in the device
413                                         tree below
414                                         <filename>/sys</filename>.</para>
415                                 </listitem>
416                         </varlistentry>
417                         <varlistentry>
418                                 <term><varname>_UDEV_DEVNODE=</varname></term>
419                                 <listitem>
420                                         <para>The device node path of
421                                         this device in
422                                         <filename>/dev</filename>.</para>
423                                 </listitem>
424                         </varlistentry>
425                         <varlistentry>
426                                 <term><varname>_UDEV_DEVLINK=</varname></term>
427                                 <listitem>
428                                         <para>Additional symlink names
429                                         pointing to the device node in
430                                         <filename>/dev</filename>. This
431                                         field is frequently set more
432                                         than once per entry.</para>
433                                 </listitem>
434                         </varlistentry>
435                 </variablelist>
436         </refsect1>
437
438         <refsect1>
439                 <title>Fields to log on behalf of a different program</title>
440
441                 <para>Fields in this section are used by programs
442                 to specify that they are logging on behalf of another
443                 program or unit.
444                 </para>
445
446                 <para>Fields used by the <command>systemd-coredump</command>
447                 coredump kernel helper:
448                 </para>
449
450                 <variablelist class='journal-directives'>
451                         <varlistentry>
452                                 <term><varname>COREDUMP_UNIT=</varname></term>
453                                 <term><varname>COREDUMP_USER_UNIT=</varname></term>
454                                 <listitem>
455                                         <para>Used to annotate
456                                         messages containing coredumps from
457                                         system and session units.
458                                         See
459                                         <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
460                                         </para>
461                                 </listitem>
462                         </varlistentry>
463                 </variablelist>
464
465                 <para>Priviledged programs (currently UID 0) may
466                 attach <varname>OBJECT_PID=</varname> to a
467                 message. This will instruct
468                 <command>systemd-journald</command> to attach
469                 additional fields on behalf of the caller:</para>
470
471                 <variablelist class='journal-directives'>
472                         <varlistentry>
473                                 <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
474                                 <listitem>
475                                         <para>PID of the program that this
476                                         message pertains to.
477                                         </para>
478                                 </listitem>
479                         </varlistentry>
480
481                         <varlistentry>
482                                 <term><varname>OBJECT_UID=</varname></term>
483                                 <term><varname>OBJECT_GID=</varname></term>
484                                 <term><varname>OBJECT_COMM=</varname></term>
485                                 <term><varname>OBJECT_EXE=</varname></term>
486                                 <term><varname>OBJECT_CMDLINE=</varname></term>
487                                 <term><varname>OBJECT_AUDIT_SESSION=</varname></term>
488                                 <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
489                                 <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
490                                 <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
491                                 <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
492                                 <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
493                                 <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
494                                 <listitem>
495                                         <para>These are additional fields added automatically
496                                         by <command>systemd-journald</command>.
497                                         Their meaning is the same as
498                                         <varname>_UID=</varname>,
499                                         <varname>_GID=</varname>,
500                                         <varname>_COMM=</varname>,
501                                         <varname>_EXE=</varname>,
502                                         <varname>_CMDLINE=</varname>,
503                                         <varname>_AUDIT_SESSION=</varname>,
504                                         <varname>_AUDIT_LOGINUID=</varname>,
505                                         <varname>_SYSTEMD_CGROUP=</varname>,
506                                         <varname>_SYSTEMD_SESSION=</varname>,
507                                         <varname>_SYSTEMD_UNIT=</varname>,
508                                         <varname>_SYSTEMD_USER_UNIT=</varname>, and
509                                         <varname>_SYSTEMD_OWNER_UID=</varname>
510                                         as described above, except that the
511                                         process identified by <replaceable>PID</replaceable>
512                                         is described, instead of the process
513                                         which logged the message.</para>
514                                 </listitem>
515                         </varlistentry>
516                 </variablelist>
517
518
519         </refsect1>
520
521         <refsect1>
522                 <title>Address Fields</title>
523
524                 <para>During serialization into external formats, such
525                 as the <ulink
526                 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
527                 Export Format</ulink> or the <ulink
528                 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
529                 JSON Format</ulink>, the addresses of journal entries
530                 are serialized into fields prefixed with double
531                 underscores. Note that these are not proper fields when
532                 stored in the journal but for addressing meta data of
533                 entries. They cannot be written as part of structured
534                 log entries via calls such as
535                 <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
536                 may also not be used as matches for
537                 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
538
539                 <variablelist class='journal-directives'>
540                         <varlistentry>
541                                 <term><varname>__CURSOR=</varname></term>
542                                 <listitem>
543                                         <para>The cursor for the
544                                         entry. A cursor is an opaque
545                                         text string that uniquely
546                                         describes the position of an
547                                         entry in the journal and is
548                                         portable across machines,
549                                         platforms and journal files.
550                                         </para>
551                                 </listitem>
552                         </varlistentry>
553
554                         <varlistentry>
555                                 <term><varname>__REALTIME_TIMESTAMP=</varname></term>
556                                 <listitem>
557                                         <para>The wallclock time
558                                         (<constant>CLOCK_REALTIME</constant>)
559                                         at the point in time the entry
560                                         was received by the journal,
561                                         in microseconds since the epoch
562                                         UTC, formatted as a decimal
563                                         string. This has different
564                                         properties from
565                                         <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,
566                                         as it is usually a bit later
567                                         but more likely to be monotonic.
568                                         </para>
569                                 </listitem>
570                         </varlistentry>
571
572                         <varlistentry>
573                                 <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
574                                 <listitem>
575                                         <para>The monotonic time
576                                         (<constant>CLOCK_MONOTONIC</constant>)
577                                         at the point in time the entry
578                                         was received by the journal in
579                                         microseconds, formatted as a decimal
580                                         string. To be useful as an
581                                         address for the entry, this
582                                         should be combined with with the
583                                         boot ID in <literal>_BOOT_ID=</literal>.
584                                         </para>
585                                 </listitem>
586                         </varlistentry>
587                 </variablelist>
588         </refsect1>
589
590         <refsect1>
591                   <title>See Also</title>
592                   <para>
593                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
594                           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
595                           <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
596                           <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
597                           <citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
598                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
599                   </para>
600         </refsect1>
601
602 </refentry>