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 but 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 128-bit message
  91                                         identifier ID for recognizing
  92                                         certain message types, if this
  93                                         is desirable. This should
  94                                         contain a 128-bit ID formatted
  95                                         as a lower-case hexadecimal
  96                                         string, without any separating
  97                                         dashes or suchlike. This is
  98                                         recommended to be a
  99                                         UUID-compatible ID, but this is not
 100                                         enforced, and formatted
 101                                         differently. Developers can
 102                                         generate a new ID for this
 103                                         purpose with <command>journalctl
 104                                         <option>--new-id</option></command>.
 105                                         </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 a 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                                         filename, 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 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 144                                         formatted as a 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. (Note that the tag is
 160                                         usually derived from glibc's
 161                                         <varname>program_invocation_short_name</varname>
 162                                         variable, see <citerefentry><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para>
 163                                 </listitem>
 164
 165                         </varlistentry>
 166                 </variablelist>
 167         </refsect1>
 168
 169         <refsect1>
 170                 <title>Trusted Journal Fields</title>
 171
 172                 <para>Fields prefixed with an underscore are trusted
 173                 fields, i.e. fields that are implicitly added by the
 174                 journal and cannot be altered by client code.</para>
 175
 176                 <variablelist class='journal-directives'>
 177                         <varlistentry>
 178                                 <term><varname>_PID=</varname></term>
 179                                 <term><varname>_UID=</varname></term>
 180                                 <term><varname>_GID=</varname></term>
 181                                 <listitem>
 182                                         <para>The process, user, and
 183                                         group ID of the process the
 184                                         journal entry originates from
 185                                         formatted as a decimal
 186                                         string.</para>
 187                                 </listitem>
 188                         </varlistentry>
 189
 190                         <varlistentry>
 191                                 <term><varname>_COMM=</varname></term>
 192                                 <term><varname>_EXE=</varname></term>
 193                                 <term><varname>_CMDLINE=</varname></term>
 194                                 <listitem>
 195                                         <para>The name, the executable
 196                                         path, and the command line of
 197                                         the process the journal entry
 198                                         originates from.</para>
 199                                 </listitem>
 200                         </varlistentry>
 201
 202                         <varlistentry>
 203                                 <term><varname>_CAP_EFFECTIVE=</varname></term>
 204                                 <listitem>
 205                                         <para>The effective <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> of
 206                                         the process the journal entry
 207                                         originates from.</para>
 208                                 </listitem>
 209                         </varlistentry>
 210
 211                         <varlistentry>
 212                                 <term><varname>_AUDIT_SESSION=</varname></term>
 213                                 <term><varname>_AUDIT_LOGINUID=</varname></term>
 214                                 <listitem>
 215                                         <para>The session and login
 216                                         UID of the process the journal
 217                                         entry originates from, as
 218                                         maintained by the kernel audit
 219                                         subsystem.</para>
 220                                 </listitem>
 221                         </varlistentry>
 222
 223                         <varlistentry>
 224                                 <term><varname>_SYSTEMD_CGROUP=</varname></term>
 225                                 <term><varname>_SYSTEMD_SESSION=</varname></term>
 226                                 <term><varname>_SYSTEMD_UNIT=</varname></term>
 227                                 <term><varname>_SYSTEMD_USER_UNIT=</varname></term>
 228                                 <term><varname>_SYSTEMD_OWNER_UID=</varname></term>
 229                                 <term><varname>_SYSTEMD_SLICE=</varname></term>
 230
 231                                 <listitem>
 232                                         <para>The control group path
 233                                         in the systemd hierarchy, the
 234                                         systemd session ID (if any),
 235                                         the systemd unit name (if
 236                                         any), the systemd user session
 237                                         unit name (if any), the owner
 238                                         UID of the systemd session (if
 239                                         any) and the systemd slice
 240                                         unit of the process the
 241                                         journal entry originates
 242                                         from.</para>
 243                                 </listitem>
 244                         </varlistentry>
 245
 246                         <varlistentry>
 247                                 <term><varname>_SELINUX_CONTEXT=</varname></term>
 248                                 <listitem>
 249                                         <para>The SELinux security
 250                                         context (label) of the process
 251                                         the journal entry originates
 252                                         from.</para>
 253                                 </listitem>
 254                         </varlistentry>
 255
 256                         <varlistentry>
 257                                 <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>
 258                                 <listitem>
 259                                         <para>The earliest trusted
 260                                         timestamp of the message, if
 261                                         any is known that is different
 262                                         from the reception time of the
 263                                         journal. This is the time in
 264                                         microseconds since the epoch UTC,
 265                                         formatted as a decimal
 266                                         string.</para>
 267                                 </listitem>
 268                         </varlistentry>
 269
 270                         <varlistentry>
 271                                 <term><varname>_BOOT_ID=</varname></term>
 272                                 <listitem>
 273                                         <para>The kernel boot ID for
 274                                         the boot the message was
 275                                         generated in, formatted as
 276                                         a 128-bit hexadecimal
 277                                         string.</para>
 278                                 </listitem>
 279                         </varlistentry>
 280
 281                         <varlistentry>
 282                                 <term><varname>_MACHINE_ID=</varname></term>
 283                                 <listitem>
 284                                         <para>The machine ID of the
 285                                         originating host, as available
 286                                         in
 287                                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 288                                 </listitem>
 289                         </varlistentry>
 290
 291                         <varlistentry>
 292                                 <term><varname>_HOSTNAME=</varname></term>
 293                                 <listitem>
 294                                         <para>The name of the
 295                                         originating host.</para>
 296                                 </listitem>
 297                         </varlistentry>
 298
 299                         <varlistentry>
 300                                 <term><varname>_TRANSPORT=</varname></term>
 301                                 <listitem>
 302                                         <para>How the entry was
 303                                         received by the journal
 304                                         service. Valid transports are:
 305                                         </para>
 306                                         <variablelist>
 307                                                 <varlistentry>
 308                                                         <term>
 309                                                                 <option>driver</option>
 310                                                         </term>
 311                                                         <listitem>
 312                                                                 <para>for
 313                                                                 internally
 314                                                                 generated
 315                                                                 messages
 316                                                                 </para>
 317                                                         </listitem>
 318                                                 </varlistentry>
 319
 320                                                 <varlistentry>
 321                                                         <term>
 322                                                                 <option>syslog</option>
 323                                                         </term>
 324                                                         <listitem>
 325                                                                 <para>for those
 326                                                                 received via the
 327                                                                 local syslog
 328                                                                 socket with the
 329                                                                 syslog protocol
 330                                                                 </para>
 331                                                         </listitem>
 332                                                 </varlistentry>
 333
 334                                                 <varlistentry>
 335                                                         <term>
 336                                                                 <option>journal</option>
 337                                                         </term>
 338                                                         <listitem>
 339                                                                 <para>for those
 340                                                                 received via the
 341                                                                 native journal
 342                                                                 protocol
 343                                                                 </para>
 344                                                         </listitem>
 345                                                 </varlistentry>
 346
 347                                                 <varlistentry>
 348                                                         <term>
 349                                                                 <option>stdout</option>
 350                                                         </term>
 351                                                         <listitem>
 352                                                                 <para>for those
 353                                                                 read from a
 354                                                                 service's
 355                                                                 standard output
 356                                                                 or error output
 357                                                                 </para>
 358                                                         </listitem>
 359                                                 </varlistentry>
 360
 361                                                 <varlistentry>
 362                                                         <term>
 363                                                                 <option>kernel</option>
 364                                                         </term>
 365                                                         <listitem>
 366                                                                 <para>for those
 367                                                                 read from the
 368                                                                 kernel
 369                                                                 </para>
 370                                                         </listitem>
 371                                                 </varlistentry>
 372                                         </variablelist>
 373                                 </listitem>
 374                         </varlistentry>
 375                 </variablelist>
 376         </refsect1>
 377
 378         <refsect1>
 379                 <title>Kernel Journal Fields</title>
 380
 381                 <para>Kernel fields are fields that are used by
 382                 messages originating in the kernel and stored in the
 383                 journal.</para>
 384
 385                 <variablelist class='journal-directives'>
 386                         <varlistentry>
 387                                 <term><varname>_KERNEL_DEVICE=</varname></term>
 388                                 <listitem>
 389                                         <para>The kernel device
 390                                         name. If the entry is
 391                                         associated to a block device,
 392                                         the major and minor of the
 393                                         device node, separated by <literal>:</literal>
 394                                         and prefixed by <literal>b</literal>. Similar
 395                                         for character devices but
 396                                         prefixed by <literal>c</literal>. For network
 397                                         devices, this is the interface index
 398                                         prefixed by <literal>n</literal>. For all other
 399                                         devices, this is the subsystem name
 400                                         prefixed by <literal>+</literal>, followed by
 401                                         <literal>:</literal>, followed by the kernel
 402                                         device name.</para>
 403                                 </listitem>
 404                         </varlistentry>
 405                         <varlistentry>
 406                                 <term><varname>_KERNEL_SUBSYSTEM=</varname></term>
 407                                 <listitem>
 408                                         <para>The kernel subsystem name.</para>
 409                                 </listitem>
 410                         </varlistentry>
 411                         <varlistentry>
 412                                 <term><varname>_UDEV_SYSNAME=</varname></term>
 413                                 <listitem>
 414                                         <para>The kernel device name
 415                                         as it shows up in the device
 416                                         tree below
 417                                         <filename>/sys</filename>.</para>
 418                                 </listitem>
 419                         </varlistentry>
 420                         <varlistentry>
 421                                 <term><varname>_UDEV_DEVNODE=</varname></term>
 422                                 <listitem>
 423                                         <para>The device node path of
 424                                         this device in
 425                                         <filename>/dev</filename>.</para>
 426                                 </listitem>
 427                         </varlistentry>
 428                         <varlistentry>
 429                                 <term><varname>_UDEV_DEVLINK=</varname></term>
 430                                 <listitem>
 431                                         <para>Additional symlink names
 432                                         pointing to the device node in
 433                                         <filename>/dev</filename>. This
 434                                         field is frequently set more
 435                                         than once per entry.</para>
 436                                 </listitem>
 437                         </varlistentry>
 438                 </variablelist>
 439         </refsect1>
 440
 441         <refsect1>
 442                 <title>Fields to log on behalf of a different program</title>
 443
 444                 <para>Fields in this section are used by programs
 445                 to specify that they are logging on behalf of another
 446                 program or unit.
 447                 </para>
 448
 449                 <para>Fields used by the <command>systemd-coredump</command>
 450                 coredump kernel helper:
 451                 </para>
 452
 453                 <variablelist class='journal-directives'>
 454                         <varlistentry>
 455                                 <term><varname>COREDUMP_UNIT=</varname></term>
 456                                 <term><varname>COREDUMP_USER_UNIT=</varname></term>
 457                                 <listitem>
 458                                         <para>Used to annotate
 459                                         messages containing coredumps from
 460                                         system and session units.
 461                                         See
 462                                         <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 463                                         </para>
 464                                 </listitem>
 465                         </varlistentry>
 466                 </variablelist>
 467
 468                 <para>Priviledged programs (currently UID 0) may
 469                 attach <varname>OBJECT_PID=</varname> to a
 470                 message. This will instruct
 471                 <command>systemd-journald</command> to attach
 472                 additional fields on behalf of the caller:</para>
 473
 474                 <variablelist class='journal-directives'>
 475                         <varlistentry>
 476                                 <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>
 477                                 <listitem>
 478                                         <para>PID of the program that this
 479                                         message pertains to.
 480                                         </para>
 481                                 </listitem>
 482                         </varlistentry>
 483
 484                         <varlistentry>
 485                                 <term><varname>OBJECT_UID=</varname></term>
 486                                 <term><varname>OBJECT_GID=</varname></term>
 487                                 <term><varname>OBJECT_COMM=</varname></term>
 488                                 <term><varname>OBJECT_EXE=</varname></term>
 489                                 <term><varname>OBJECT_CMDLINE=</varname></term>
 490                                 <term><varname>OBJECT_AUDIT_SESSION=</varname></term>
 491                                 <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>
 492                                 <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>
 493                                 <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>
 494                                 <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>
 495                                 <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>
 496                                 <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>
 497                                 <listitem>
 498                                         <para>These are additional fields added automatically
 499                                         by <command>systemd-journald</command>.
 500                                         Their meaning is the same as
 501                                         <varname>_UID=</varname>,
 502                                         <varname>_GID=</varname>,
 503                                         <varname>_COMM=</varname>,
 504                                         <varname>_EXE=</varname>,
 505                                         <varname>_CMDLINE=</varname>,
 506                                         <varname>_AUDIT_SESSION=</varname>,
 507                                         <varname>_AUDIT_LOGINUID=</varname>,
 508                                         <varname>_SYSTEMD_CGROUP=</varname>,
 509                                         <varname>_SYSTEMD_SESSION=</varname>,
 510                                         <varname>_SYSTEMD_UNIT=</varname>,
 511                                         <varname>_SYSTEMD_USER_UNIT=</varname>, and
 512                                         <varname>_SYSTEMD_OWNER_UID=</varname>
 513                                         as described above, except that the
 514                                         process identified by <replaceable>PID</replaceable>
 515                                         is described, instead of the process
 516                                         which logged the message.</para>
 517                                 </listitem>
 518                         </varlistentry>
 519                 </variablelist>
 520
 521
 522         </refsect1>
 523
 524         <refsect1>
 525                 <title>Address Fields</title>
 526
 527                 <para>During serialization into external formats, such
 528                 as the <ulink
 529                 url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 530                 Export Format</ulink> or the <ulink
 531                 url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
 532                 JSON Format</ulink>, the addresses of journal entries
 533                 are serialized into fields prefixed with double
 534                 underscores. Note that these are not proper fields when
 535                 stored in the journal but for addressing metadata of
 536                 entries. They cannot be written as part of structured
 537                 log entries via calls such as
 538                 <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They
 539                 may also not be used as matches for
 540                 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
 541
 542                 <variablelist class='journal-directives'>
 543                         <varlistentry>
 544                                 <term><varname>__CURSOR=</varname></term>
 545                                 <listitem>
 546                                         <para>The cursor for the
 547                                         entry. A cursor is an opaque
 548                                         text string that uniquely
 549                                         describes the position of an
 550                                         entry in the journal and is
 551                                         portable across machines,
 552                                         platforms and journal files.
 553                                         </para>
 554                                 </listitem>
 555                         </varlistentry>
 556
 557                         <varlistentry>
 558                                 <term><varname>__REALTIME_TIMESTAMP=</varname></term>
 559                                 <listitem>
 560                                         <para>The wallclock time
 561                                         (<constant>CLOCK_REALTIME</constant>)
 562                                         at the point in time the entry
 563                                         was received by the journal,
 564                                         in microseconds since the epoch
 565                                         UTC, formatted as a decimal
 566                                         string. This has different
 567                                         properties from
 568                                         <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,
 569                                         as it is usually a bit later
 570                                         but more likely to be monotonic.
 571                                         </para>
 572                                 </listitem>
 573                         </varlistentry>
 574
 575                         <varlistentry>
 576                                 <term><varname>__MONOTONIC_TIMESTAMP=</varname></term>
 577                                 <listitem>
 578                                         <para>The monotonic time
 579                                         (<constant>CLOCK_MONOTONIC</constant>)
 580                                         at the point in time the entry
 581                                         was received by the journal in
 582                                         microseconds, formatted as a decimal
 583                                         string. To be useful as an
 584                                         address for the entry, this
 585                                         should be combined with the
 586                                         boot ID in <literal>_BOOT_ID=</literal>.
 587                                         </para>
 588                                 </listitem>
 589                         </varlistentry>
 590                 </variablelist>
 591         </refsect1>
 592
 593         <refsect1>
 594                   <title>See Also</title>
 595                   <para>
 596                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 597                           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 598                           <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 599                           <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 600                           <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 601                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 602                   </para>
 603         </refsect1>
 604
 605 </refentry>