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 128bit message
  91                                         identifier ID for recognizing
  92                                         certain message types, if this
  93                                         is desirable. This should
  94                                         contain a 128bit id formatted
  95                                         as lower-case hexadecimal
  96                                         string, without any separating
  97                                         dashes or suchlike. This is
  98                                         recommended to be a UUID
  99                                         compatible ID, but this is not
 100                                         enforced, and formatted
 101                                         differently. Developers can
 102                                         generate a new ID for this
 103                                         purpose with
 104                                         <command>journalctl
 105                                         --new-id</command>.</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 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                                         file name, 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 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 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>_AUDIT_SESSION=</varname></term>
 201                                 <term><varname>_AUDIT_LOGINUID=</varname></term>
 202                                 <listitem>
 203                                         <para>The session and login
 204                                         UID of the process the journal
 205                                         entry originates from, as
 206                                         maintained by the kernel audit
 207                                         subsystem.</para>
 208                                 </listitem>
 209                         </varlistentry>
 210
 211                         <varlistentry>
 212                                 <term><varname>_SYSTEMD_CGROUP=</varname></term>
 213                                 <term><varname>_SYSTEMD_SESSION=</varname></term>
 214                                 <term><varname>_SYSTEMD_UNIT=</varname></term>
 215                                 <term><varname>_SYSTEMD_OWNER_UID=</varname></term>
 216
 217                                 <listitem>
 218                                         <para>The contol group path in
 219                                         the systemd hierarchy, the
 220                                         systemd session ID (if any),
 221                                         the systemd unit name (if any)
 222                                         and the owner UID of the
 223                                         systemd session (if any) of
 224                                         the process the journal entry
 225                                         originates from.</para>
 226                                 </listitem>
 227                         </varlistentry>
 228
 229                         <varlistentry>
 230                                 <term><varname>_SELINUX_CONTEXT=</varname></term>
 231                                 <listitem>
 232                                         <para>The SELinux security
 233                                         context of the process the
 234                                         journal entry originates
 235                                         from.</para>
 236                                 </listitem>
 237                         </varlistentry>
 238
 239                         <varlistentry>
 240                                 <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
 241                                 <listitem>
 242                                         <para>The earliest trusted
 243                                         timestamp of the message, if
 244                                         any is known that is different
 245                                         from the reception time of the
 246                                         journal. This is the time in
 247                                         usec since the epoch UTC
 248                                         formatted as decimal
 249                                         string.</para>
 250                                 </listitem>
 251                         </varlistentry>
 252
 253                         <varlistentry>
 254                                 <term><varname>_BOOT_ID=</varname></term>
 255                                 <listitem>
 256                                         <para>The kernel boot ID for
 257                                         the boot the message was
 258                                         generated in, formatted as
 259                                         128bit hexadecimal
 260                                         string.</para>
 261                                 </listitem>
 262                         </varlistentry>
 263
 264                         <varlistentry>
 265                                 <term><varname>_MACHINE_ID=</varname></term>
 266                                 <listitem>
 267                                         <para>The machine ID of the
 268                                         originating host, as available
 269                                         in
 270                                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 271                                 </listitem>
 272                         </varlistentry>
 273
 274                         <varlistentry>
 275                                 <term><varname>_HOSTNAME=</varname></term>
 276                                 <listitem>
 277                                         <para>The name of the
 278                                         originating host.</para>
 279                                 </listitem>
 280                         </varlistentry>
 281
 282                         <varlistentry>
 283                                 <term><varname>_TRANSPORT=</varname></term>
 284                                 <listitem>
 285                                         <para>How the entry was
 286                                         received by the journal
 287                                         service. One of
 288                                         <literal>driver</literal>,
 289                                         <literal>syslog</literal>,
 290                                         <literal>journal</literal>,
 291                                         <literal>stdout</literal>,
 292                                         <literal>kernel</literal> for
 293                                         internally generated messages,
 294                                         for those received via the
 295                                         local syslog socket with the
 296                                         syslog protocol, for those
 297                                         received via the native
 298                                         journal protocol, for the
 299                                         those read from a services'
 300                                         standard output or error
 301                                         output, and for those read
 302                                         from the kernel, resp.
 303                                         </para>
 304                                 </listitem>
 305                         </varlistentry>
 306                 </variablelist>
 307         </refsect1>
 308
 309         <refsect1>
 310                 <title>Kernel Journal Fields</title>
 311
 312                 <para>Kernel fields are fields that are used by
 313                 messages originating in the kernel and stored in the
 314                 journal.</para>
 315
 316                 <variablelist>
 317                         <varlistentry>
 318                                 <term>_KERNEL_DEVICE=</term>
 319                                 <listitem>
 320                                         <para>The kernel device
 321                                         name. If the entry is
 322                                         associated to a block device,
 323                                         the major and minor of the
 324                                         device node, separated by ':'
 325                                         and prefixed by 'b'. Similar
 326                                         for character devices, but
 327                                         prefixed by 'c'. For network
 328                                         devices the interface index,
 329                                         prefixed by 'n'. For all other
 330                                         devices '+' followed by the
 331                                         subsystem name, followed by
 332                                         ':', followed by the kernel
 333                                         device name.</para>
 334                                 </listitem>
 335                         </varlistentry>
 336                         <varlistentry>
 337                                 <term>_KERNEL_SUBSYSTEM=</term>
 338                                 <listitem>
 339                                         <para>The kernel subsystem name.</para>
 340                                 </listitem>
 341                         </varlistentry>
 342                         <varlistentry>
 343                                 <term>_UDEV_SYSNAME=</term>
 344                                 <listitem>
 345                                         <para>The kernel device name
 346                                         as it shows up in the device
 347                                         tree below
 348                                         <filename>/sys</filename>.</para>
 349                                 </listitem>
 350                         </varlistentry>
 351                         <varlistentry>
 352                                 <term>_UDEV_DEVNODE=</term>
 353                                 <listitem>
 354                                         <para>The device node path of
 355                                         this device in
 356                                         <filename>/dev</filename>.</para>
 357                                 </listitem>
 358                         </varlistentry>
 359                         <varlistentry>
 360                                 <term>_UDEV_DEVLINK=</term>
 361                                 <listitem>
 362                                         <para>Additional symlink names
 363                                         pointing to the device node in
 364                                         <filename>/dev</filename>. This
 365                                         field is frequently set more
 366                                         than once per entry.</para>
 367                                 </listitem>
 368                         </varlistentry>
 369                 </variablelist>
 370         </refsect1>
 371
 372         <refsect1>
 373                 <title>Address Fields</title>
 374
 375                 <para>During serialization into external formats the
 376                 addresses of journal entries are serialized into
 377                 fields prefixed with double underscores. Note that
 378                 these aren't proper fields when stored in the journal,
 379                 but addressing meta data of entries. They cannot be
 380                 written as part of structured log entries via calls
 381                 such as
 382                 <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
 383                 may also not be used as matches for
 384                 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
 385
 386                 <variablelist class='journal-directives'>
 387                         <varlistentry>
 388                                 <term><varname>__CURSOR=</varname></term>
 389                                 <listitem>
 390                                         <para>The cursor for the
 391                                         entry. A cursor is an opaque
 392                                         text string that uniquely
 393                                         describes the position of an
 394                                         entry in the journal and is
 395                                         portable across machines,
 396                                         platforms and journal
 397                                         files.</para>
 398                                 </listitem>
 399                         </varlistentry>
 400
 401                         <varlistentry>
 402                                 <term><varname>__REALTIME_TIMESTAMP=</varname></term>
 403                                 <listitem>
 404                                         <para>The wallclock time
 405                                         (CLOCK_REALTIME) at the point
 406                                         in time the entry was received
 407                                         by the journal, in usec since
 408                                         the epoch UTC formatted as
 409                                         decimal string. This has
 410                                         different properties from
 411                                         <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>
 412                                         as it is usually a bit later
 413                                         but more likely to be
 414                                         monotonic.</para>
 415                                 </listitem>
 416                         </varlistentry>
 417
 418                         <varlistentry>
 419                                 <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
 420                                 <listitem>
 421                                         <para>The monotonic time
 422                                         (CLOCK_MONOTONIC) at the point
 423                                         in time the entry was received
 424                                         by the journal in usec
 425                                         formatted as decimal
 426                                         string. To be useful as an
 427                                         address for the entry this
 428                                         should be combined with with
 429                                         boot ID in
 430                                         <literal>_BOOT_ID=</literal>.</para>
 431                                 </listitem>
 432                         </varlistentry>
 433                 </variablelist>
 434         </refsect1>
 435
 436         <refsect1>
 437                   <title>See Also</title>
 438                   <para>
 439                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 440                           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 441                           <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 442                           <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 443                   </para>
 444         </refsect1>
 445
 446 </refentry>