<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="systemd.journal-fields">

<refentryinfo>

<title>systemd.journal-fields</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>systemd.journal-fields</refentrytitle>

<manvolnum>7</manvolnum>

</refmeta>

<refnamediv>

<refname>systemd.journal-fields</refname>

<refpurpose>Special journal fields</refpurpose>

</refnamediv>

<refsect1>

<title>Description</title>

<para>Entries in the journal resemble an environment

block in their syntax, however with fields that can

include binary data. Primarily, fields are formatted

UTF-8 text strings, and binary formatting is used only

where formatting as UTF-8 text strings makes little

sense. New fields may freely be defined by

applications, but a few fields have special

meaning. All fields with special meanings are

optional. In some cases fields may appear more than

once per entry.</para>

</refsect1>

<refsect1>

<title>User Journal Fields</title>

<para>User fields are fields that are directly passed

from clients and stored in the journal.</para>

<variablelist class='journal-directives'>

<varlistentry>

<term><varname>MESSAGE=</varname></term>

<listitem>

<para>The human-readable

message string for this

entry. This is supposed to be

the primary text shown to the

user. It is usually not

translated (but might be in

some cases), and is not

supposed to be parsed for meta

data.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>MESSAGE_ID=</varname></term>

<listitem>

<para>A 128-bit message

identifier ID for recognizing

certain message types, if this

is desirable. This should

contain a 128-bit ID formatted

as a lower-case hexadecimal

string, without any separating

dashes or suchlike. This is

recommended to be a

UUID-compatible ID, but this is not

enforced, and formatted

differently. Developers can

generate a new ID for this

purpose with <command>journalctl

<option>--new-id</option></command>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>PRIORITY=</varname></term>

<listitem>

<para>A priority value between

0 (<literal>emerg</literal>)

and 7

(<literal>debug</literal>)

formatted as a decimal

string. This field is

compatible with syslog's

priority concept.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>CODE_FILE=</varname></term>

<term><varname>CODE_LINE=</varname></term>

<term><varname>CODE_FUNC=</varname></term>

<listitem>

<para>The code location

generating this message, if

known. Contains the source

filename, the line number and

the function name.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>ERRNO=</varname></term>

<listitem>

<para>The low-level Unix error

number causing this entry, if

any. Contains the numeric

value of

<citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>

formatted as a decimal

string.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>SYSLOG_FACILITY=</varname></term>

<term><varname>SYSLOG_IDENTIFIER=</varname></term>

<term><varname>SYSLOG_PID=</varname></term>

<listitem>

<para>Syslog compatibility

fields containing the facility

(formatted as decimal string),

the identifier string

(i.e. "tag"), and the client

PID.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Trusted Journal Fields</title>

<para>Fields prefixed with an underscore are trusted

fields, i.e. fields that are implicitly added by the

journal and cannot be altered by client code.</para>

<variablelist class='journal-directives'>

<varlistentry>

<term><varname>_PID=</varname></term>

<term><varname>_UID=</varname></term>

<term><varname>_GID=</varname></term>

<listitem>

<para>The process, user and

group ID of the process the

journal entry originates from

formatted as a decimal

string.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_COMM=</varname></term>

<term><varname>_EXE=</varname></term>

<term><varname>_CMDLINE=</varname></term>

<listitem>

<para>The name, the executable

path and the command line of

the process the journal entry

originates from.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_CAP_EFFECTIVE=</varname></term>

<listitem>

<para>The effective <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> of

the process the journal entry

originates from.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_AUDIT_SESSION=</varname></term>

<term><varname>_AUDIT_LOGINUID=</varname></term>

<listitem>

<para>The session and login

UID of the process the journal

entry originates from, as

maintained by the kernel audit

subsystem.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_SYSTEMD_CGROUP=</varname></term>

<term><varname>_SYSTEMD_SESSION=</varname></term>

<term><varname>_SYSTEMD_UNIT=</varname></term>

<term><varname>_SYSTEMD_USER_UNIT=</varname></term>

<term><varname>_SYSTEMD_OWNER_UID=</varname></term>

<term><varname>_SYSTEMD_SLICE=</varname></term>

<listitem>

<para>The control group path

in the systemd hierarchy, the

systemd session ID (if any),

the systemd unit name (if

any), the systemd user session

unit name (if any), the owner

UID of the systemd session (if

any) and the systemd slice

unit of the process the

journal entry originates

from.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_SELINUX_CONTEXT=</varname></term>

<listitem>

<para>The SELinux security

context of the process the

journal entry originates

from.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term>

<listitem>

<para>The earliest trusted

timestamp of the message, if

any is known that is different

from the reception time of the

journal. This is the time in

microseconds since the epoch UTC,

formatted as a decimal

string.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_BOOT_ID=</varname></term>

<listitem>

<para>The kernel boot ID for

the boot the message was

generated in, formatted as

a 128-bit hexadecimal

string.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_MACHINE_ID=</varname></term>

<listitem>

<para>The machine ID of the

originating host, as available

in

<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_HOSTNAME=</varname></term>

<listitem>

<para>The name of the

originating host.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_TRANSPORT=</varname></term>

<listitem>

<para>How the entry was

received by the journal

service. Valid transports are:

</para>

<variablelist>

<varlistentry>

<term>

<option>driver</option>

</term>

<listitem>

<para>for

internally

generated

messages

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<option>syslog</option>

</term>

<listitem>

<para>for those

received via the

local syslog

socket with the

syslog protocol

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<option>journal</option>

</term>

<listitem>

<para>for those

received via the

native journal

protocol

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<option>stdout</option>

</term>

<listitem>

<para>for those

read from a

service's

standard output

or error output

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<option>kernel</option>

</term>

<listitem>

<para>for those

read from the

kernel

</para>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Kernel Journal Fields</title>

<para>Kernel fields are fields that are used by

messages originating in the kernel and stored in the

journal.</para>

<variablelist class='journal-directives'>

<varlistentry>

<term><varname>_KERNEL_DEVICE=</varname></term>

<listitem>

<para>The kernel device

name. If the entry is

associated to a block device,

the major and minor of the

device node, separated by <literal>:</literal>

and prefixed by <literal>b</literal>. Similar

for character devices, but

prefixed by <literal>c</literal>. For network

devices the interface index,

prefixed by <literal>n</literal>. For all other

devices <literal>+</literal> followed by the

subsystem name, followed by

<literal>:</literal>, followed by the kernel

device name.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_KERNEL_SUBSYSTEM=</varname></term>

<listitem>

<para>The kernel subsystem name.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_UDEV_SYSNAME=</varname></term>

<listitem>

<para>The kernel device name

as it shows up in the device

tree below

<filename>/sys</filename>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_UDEV_DEVNODE=</varname></term>

<listitem>

<para>The device node path of

this device in

<filename>/dev</filename>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>_UDEV_DEVLINK=</varname></term>

<listitem>

<para>Additional symlink names

pointing to the device node in

<filename>/dev</filename>. This

field is frequently set more

than once per entry.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Fields to log on behalf of a different program</title>

<para>Fields in this section are used by programs

to specify that they are logging on behalf of another

program or unit.

</para>

<para>Fields used by the <command>systemd-coredump</command>

coredump kernel helper:

</para>

<variablelist class='journal-directives'>

<varlistentry>

<term><varname>COREDUMP_UNIT=</varname></term>

<term><varname>COREDUMP_USER_UNIT=</varname></term>

<listitem>

<para>Used to annotate

messages containing coredumps from

system and session units.

See

<citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.

</para>

</listitem>

</varlistentry>

</variablelist>

<para>Priviledged programs (currently UID 0) may

attach <varname>OBJECT_PID=</varname> to a

message. This will instruct

<command>systemd-journald</command> to attach

additional fields on behalf of the caller:</para>

<variablelist class='journal-directives'>

<varlistentry>

<term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term>

<listitem>

<para>PID of the program that this

message pertains to.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>OBJECT_UID=</varname></term>

<term><varname>OBJECT_GID=</varname></term>

<term><varname>OBJECT_COMM=</varname></term>

<term><varname>OBJECT_EXE=</varname></term>

<term><varname>OBJECT_CMDLINE=</varname></term>

<term><varname>OBJECT_AUDIT_SESSION=</varname></term>

<term><varname>OBJECT_AUDIT_LOGINUID=</varname></term>

<term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term>

<term><varname>OBJECT_SYSTEMD_SESSION=</varname></term>

<term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term>

<term><varname>OBJECT_SYSTEMD_UNIT=</varname></term>

<term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term>

<listitem>

<para>These are additional fields added automatically

by <command>systemd-journald</command>.

Their meaning is the same as

<varname>_UID=</varname>,

<varname>_GID=</varname>,

<varname>_COMM=</varname>,

<varname>_EXE=</varname>,

<varname>_CMDLINE=</varname>,

<varname>_AUDIT_SESSION=</varname>,

<varname>_AUDIT_LOGINUID=</varname>,

<varname>_SYSTEMD_CGROUP=</varname>,

<varname>_SYSTEMD_SESSION=</varname>,

<varname>_SYSTEMD_UNIT=</varname>,

<varname>_SYSTEMD_USER_UNIT=</varname>, and

<varname>_SYSTEMD_OWNER_UID=</varname>

as described above, except that the

process identified by <replaceable>PID</replaceable>

is described, instead of the process

which logged the message.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Address Fields</title>

<para>During serialization into external formats, such

as the <ulink

url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal

Export Format</ulink> or the <ulink

url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal

JSON Format</ulink>, the addresses of journal entries

are serialized into fields prefixed with double

underscores. Note that these are not proper fields when

stored in the journal but for addressing meta data of

entries. They cannot be written as part of structured

log entries via calls such as

<citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They

may also not be used as matches for

<citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>

<variablelist class='journal-directives'>

<varlistentry>

<term><varname>__CURSOR=</varname></term>

<listitem>

<para>The cursor for the

entry. A cursor is an opaque

text string that uniquely

describes the position of an

entry in the journal and is

portable across machines,

platforms and journal files.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>__REALTIME_TIMESTAMP=</varname></term>

<listitem>

<para>The wallclock time

(<constant>CLOCK_REALTIME</constant>)

at the point in time the entry

was received by the journal,

in microseconds since the epoch

UTC, formatted as a decimal

string. This has different

properties from

<literal>_SOURCE_REALTIME_TIMESTAMP=</literal>,

as it is usually a bit later

but more likely to be monotonic.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>__MONOTONIC_TIMESTAMP=</varname></term>

<listitem>

<para>The monotonic time

(<constant>CLOCK_MONOTONIC</constant>)

at the point in time the entry

was received by the journal in

microseconds, formatted as a decimal

string. To be useful as an

address for the entry, this

should be combined with with the

boot ID in <literal>_BOOT_ID=</literal>.

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd-coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>