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>