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