chiark / gitweb /
shutdown: don't complain if we cannot lock memory, to make container shutdowns clean
[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                 ASCII strings, and binary formatting is used only
57                 where formatting as ASCII makes little sense. New
58                 fields may be freely defined by applications, but a
59                 few fields have special meaning. All fields with
60                 special meaning are optional.</para>
61         </refsect1>
62
63         <refsect1>
64                 <title>User Journal Fields</title>
65
66                 <para>User fields are fields that are directly passed
67                 from clients and stored in the journal.</para>
68
69                 <variablelist>
70                         <varlistentry>
71                                 <term>MESSAGE=</term>
72                                 <listitem>
73                                         <para>The human readable
74                                         message string for this
75                                         entry. This is supposed to be
76                                         the primary text shown to the
77                                         user. It is not translated,
78                                         and is not supposed to be
79                                         parsed for meta data.</para>
80                                 </listitem>
81                         </varlistentry>
82
83                         <varlistentry>
84                                 <term>MESSAGE_ID=</term>
85                                 <listitem>
86                                         <para>A 128bit message
87                                         identifier ID for recognizing
88                                         certain message types, if this
89                                         is desirable. This should
90                                         contain a 128bit id formatted
91                                         as lower-case hexadecimal
92                                         string, without any separating
93                                         dashes or suchlike. This is
94                                         recommended to be a UUID
95                                         compatible ID, but this is not
96                                         enforced, and formatted
97                                         differently. Developers can
98                                         generate a new ID for this
99                                         purpose with
100                                         <command>journalctl
101                                         --new-id</command>.</para>
102                                 </listitem>
103                         </varlistentry>
104
105                         <varlistentry>
106                                 <term>PRIORITY=</term>
107                                 <listitem>
108                                         <para>A priority value between
109                                         0 (<literal>emerg</literal>)
110                                         and 7
111                                         (<literal>debug</literal>)
112                                         formatted as decimal
113                                         string. This field is
114                                         compatible with syslog's
115                                         priority concept.</para>
116                                 </listitem>
117                         </varlistentry>
118
119                         <varlistentry>
120                                 <term>CODE_FILE=</term>
121                                 <term>CODE_LINE=</term>
122                                 <term>CODE_FUNC=</term>
123                                 <listitem>
124                                         <para>The code location
125                                         generating this message, if
126                                         known. Contains the source
127                                         file name, the line number and
128                                         the function name.</para>
129                                 </listitem>
130                         </varlistentry>
131
132                         <varlistentry>
133                                 <term>SYSLOG_FACILITY=</term>
134                                 <term>SYSLOG_IDENTIFIER=</term>
135                                 <term>SYSLOG_PID=</term>
136                                 <listitem>
137                                         <para>Syslog compatibility
138                                         fields containing the facility
139                                         (formatted as decimal string),
140                                         the identifier string
141                                         (i.e. "tag"), and the client
142                                         PID.</para>
143                                 </listitem>
144
145                         </varlistentry>
146                 </variablelist>
147         </refsect1>
148
149         <refsect1>
150                 <title>Trusted Journal Fields</title>
151
152                 <para>Fields prefixed with an underscore are trusted
153                 fields, i.e. fields that are implicitly added by the
154                 journal and cannot be altered by client code.</para>
155
156                 <variablelist>
157                         <varlistentry>
158                                 <term>_PID=</term>
159                                 <term>_UID=</term>
160                                 <term>_GID=</term>
161                                 <listitem>
162                                         <para>The process, user and
163                                         group ID of the process the
164                                         journal entry originates from
165                                         formatted as decimal
166                                         string.</para>
167                                 </listitem>
168                         </varlistentry>
169
170                         <varlistentry>
171                                 <term>_COMM=</term>
172                                 <term>_EXE=</term>
173                                 <term>_CMDLINE=</term>
174                                 <listitem>
175                                         <para>The name, the executable
176                                         path and the command line of
177                                         the process the journal entry
178                                         originates from.</para>
179                                 </listitem>
180                         </varlistentry>
181
182                         <varlistentry>
183                                 <term>_AUDIT_SESSION=</term>
184                                 <term>_AUDIT_LOGINUID=</term>
185                                 <listitem>
186                                         <para>The session and login
187                                         UID of the process the journal
188                                         entry originates from, as
189                                         maintained by the kernel audit
190                                         subsystem.</para>
191                                 </listitem>
192                         </varlistentry>
193
194                         <varlistentry>
195                                 <term>_SYSTEMD_CGROUP=</term>
196                                 <term>_SYSTEMD_SESSION=</term>
197                                 <term>_SYSTEMD_UNIT=</term>
198                                 <term>_SYSTEMD_OWNER_UID=</term>
199
200                                 <listitem>
201                                         <para>The contol group path in
202                                         the systemd hierarchy, the
203                                         systemd session ID (if any),
204                                         the systemd unit name (if any)
205                                         and the owner UID of the
206                                         systemd session (if any) of
207                                         the process the journal entry
208                                         originates from.</para>
209                                 </listitem>
210                         </varlistentry>
211
212                         <varlistentry>
213                                 <term>_SELINUX_CONTEXT=</term>
214                                 <listitem>
215                                         <para>The SELinux security
216                                         context of the process the
217                                         journal entry originates
218                                         from.</para>
219                                 </listitem>
220                         </varlistentry>
221
222                         <varlistentry>
223                                 <term>_SOURCE_REALTIME_TIMESTAMP=</term>
224                                 <listitem>
225                                         <para>The earliest trusted
226                                         timestamp of the message, if
227                                         any is known that is different
228                                         from the reception time of the
229                                         journal. This is the time in
230                                         usec since the epoch UTC
231                                         formatted as decimal
232                                         string.</para>
233                                 </listitem>
234                         </varlistentry>
235
236                         <varlistentry>
237                                 <term>_BOOT_ID=</term>
238                                 <listitem>
239                                         <para>The kernel boot ID for
240                                         the boot the message was
241                                         generated in, formatted as
242                                         128bit hexadecimal
243                                         string.</para>
244                                 </listitem>
245                         </varlistentry>
246
247                         <varlistentry>
248                                 <term>_MACHINE_ID=</term>
249                                 <listitem>
250                                         <para>The machine ID of the
251                                         originating host, as available
252                                         in
253                                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
254                                 </listitem>
255                         </varlistentry>
256
257                         <varlistentry>
258                                 <term>_HOSTNAME=</term>
259                                 <listitem>
260                                         <para>The name of the
261                                         originating host.</para>
262                                 </listitem>
263                         </varlistentry>
264
265                         <varlistentry>
266                                 <term>_TRANSPORT=</term>
267                                 <listitem>
268                                         <para>How the entry was
269                                         received by the journal
270                                         service. One of
271                                         <literal>driver</literal>,
272                                         <literal>syslog</literal>,
273                                         <literal>journal</literal>,
274                                         <literal>stdout</literal>,
275                                         <literal>kernel</literal> for
276                                         internally generated messages,
277                                         for those received via the
278                                         local syslog socket with the
279                                         syslog protocol, for those
280                                         received via the native
281                                         journal protocol, for the
282                                         those read from a services'
283                                         standard output or error
284                                         output, resp. for those read
285                                         from the kernel.
286                                         </para>
287                                 </listitem>
288                         </varlistentry>
289                 </variablelist>
290         </refsect1>
291
292         <refsect1>
293                 <title>Address Fields</title>
294
295                 <para>During serialization into external formats the
296                 addresses of journal entries are serialized into
297                 fields prefixed with double underscores. Note that
298                 these aren't proper fields when stored in the journal,
299                 but addressing meta data of entries.</para>
300
301                 <variablelist>
302                         <varlistentry>
303                                 <term>__CURSOR=</term>
304                                 <listitem>
305                                         <para>The cursor for the
306                                         entry. A cursor is an opaque
307                                         text string that uniquely
308                                         describes the position of an
309                                         entry in the journal and is
310                                         portable across machines,
311                                         platforms and journal
312                                         files.</para>
313                                 </listitem>
314                         </varlistentry>
315
316                         <varlistentry>
317                                 <term>__REALTIME_TIMESTAMP=</term>
318                                 <listitem>
319                                         <para>The wallclock time
320                                         (CLOCK_REALTIME) at the point
321                                         in time the entry was received
322                                         by the journal, in usec since
323                                         the epoch UTC formatted as
324                                         decimal string. This has
325                                         different properties from
326                                         <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>
327                                         as it is usually a bit later
328                                         but more likely to be
329                                         monotonic.</para>
330                                 </listitem>
331                         </varlistentry>
332
333                         <varlistentry>
334                                 <term>__MONOTONIC_TIMESTAMP=</term>
335                                 <listitem>
336                                         <para>The monotonic time
337                                         (CLOCK_MONOTONIC) at the point
338                                         in time the entry was received
339                                         by the journal in usec
340                                         formatted as decimal
341                                         string. To be useful as an
342                                         address for the entry this
343                                         should be combined with with
344                                         boot ID in
345                                         <literal>_BOOT_ID=</literal>.</para>
346                                 </listitem>
347                         </varlistentry>
348                 </variablelist>
349         </refsect1>
350
351         <refsect1>
352                   <title>See Also</title>
353                   <para>
354                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
355                           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
356                           <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
357                   </para>
358         </refsect1>
359
360 </refentry>