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