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