man: add self-contained example of notify protocol

[thirdparty/systemd.git] / docs / JOURNAL_NATIVE_PROTOCOL.md

---
title: Native Journal Protocol
category: Interfaces
layout: default
SPDX-License-Identifier: LGPL-2.1-or-later
---

# Native Journal Protocol

`systemd-journald.service` accepts log data via various protocols:

* Classic RFC3164 BSD syslog via the `/dev/log` socket
* STDOUT/STDERR of programs via `StandardOutput=journal` + `StandardError=journal` in service files (both of which are default settings)
* Kernel log messages via the `/dev/kmsg` device node
* Audit records via the kernel's audit subsystem
* Structured log messages via `journald`'s native protocol

The latter is what this document is about: if you are developing a program and
want to pass structured log data to `journald`, it's the Journal's native
protocol that you want to use. The systemd project provides the
[`sd_journal_print(3)`](https://www.freedesktop.org/software/systemd/man/sd_journal_print.html)
API that implements the client side of this protocol. This document explains
what this interface does behind the scenes, in case you'd like to implement a
client for it yourself, without linking to `libsystemd` — for example because
you work in a programming language other than C or otherwise want to avoid the
dependency.

## Basics

The native protocol of `journald` is spoken on the
`/run/systemd/journal/socket` `AF_UNIX`/`SOCK_DGRAM` socket on which
`systemd-journald.service` listens. Each datagram sent to this socket
encapsulates one journal entry that shall be written. Since datagrams are
subject to a size limit and we want to allow large journal entries, datagrams
sent over this socket may come in one of two formats:

* A datagram with the literal journal entry data as payload, without
  any file descriptors attached.

* A datagram with an empty payload, but with a single
  [`memfd`](https://man7.org/linux/man-pages/man2/memfd_create.2.html)
  file descriptor that contains the literal journal entry data.

Other combinations are not permitted, i.e. datagrams with both payload and file
descriptors, or datagrams with neither, or more than one file descriptor. Such
datagrams are ignored. The `memfd` file descriptor should be fully sealed. The
binary format in the datagram payload and in the `memfd` memory is
identical. Typically a client would attempt to first send the data as datagram
payload, but if this fails with an `EMSGSIZE` error it would immediately retry
via the `memfd` logic.

A client probably should bump up the `SO_SNDBUF` socket option of its `AF_UNIX`
socket towards `journald` in order to delay blocking I/O as much as possible.

## Data Format

Each datagram should consist of a number of environment-like key/value
assignments. Unlike environment variable assignments the value may contain NUL
bytes however, as well as any other binary data. Keys may not include the `=`
or newline characters (or any other control characters or non-ASCII characters)
and may not be empty.

Serialization into the datagram payload or `memfd` is straightforward: each
key/value pair is serialized via one of two methods:

* The first method inserts a `=` character between key and value, and suffixes
the result with `\n` (i.e. the newline character, ASCII code 10). Example: a
key `FOO` with a value `BAR` is serialized `F`, `O`, `O`, `=`, `B`, `A`, `R`,
`\n`.

* The second method should be used if the value of a field contains a `\n`
byte. In this case, the key name is serialized as is, followed by a `\n`
character, followed by a (non-aligned) little-endian unsigned 64-bit integer
encoding the size of the value, followed by the literal value data, followed by
`\n`. Example: a key `FOO` with a value `BAR` may be serialized using this
second method as: `F`, `O`, `O`, `\n`, `\003`, `\000`, `\000`, `\000`, `\000`,
`\000`, `\000`, `\000`, `B`, `A`, `R`, `\n`.

If the value of a key/value pair contains a newline character (`\n`), it *must*
be serialized using the second method. If it does not, either method is
permitted. However, it is generally recommended to use the first method if
possible for all key/value pairs where applicable since the generated datagrams
are easily recognized and understood by the human eye this way, without any
manual binary decoding — which improves the debugging experience a lot, in
particular with tools such as `strace` that can show datagram content as text
dump. After all, log messages are highly relevant for debugging programs, hence
optimizing log traffic for readability without special tools is generally
desirable.

Note that keys that begin with `_` have special semantics in `journald`: they
are *trusted* and implicitly appended by `journald` on the receiving
side. Clients should not send them — if they do anyway, they will be ignored.

The most important key/value pair to send is `MESSAGE=`, as that contains the
actual log message text. Other relevant keys a client should send in most cases
are `PRIORITY=`, `CODE_FILE=`, `CODE_LINE=`, `CODE_FUNC=`, `ERRNO=`. It's
recommended to generate these fields implicitly on the client side. For further
information see the [relevant documentation of these
fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html).

The order in which the fields are serialized within one datagram is undefined
and may be freely chosen by the client. The server side might or might not
retain or reorder it when writing it to the Journal.

Some programs might generate multi-line log messages (e.g. a stack unwinder
generating log output about a stack trace, with one line for each stack
frame). It's highly recommended to send these as a single datagram, using a
single `MESSAGE=` field with embedded newline characters between the lines (the
second serialization method described above must hence be used for this
field). If possible do not split up individual events into multiple Journal
events that might then be processed and written into the Journal as separate
entries. The Journal toolchain is capable of handling multi-line log entries
just fine, and it's generally preferred to have a single set of metadata fields
associated with each multi-line message.

Note that the same keys may be used multiple times within the same datagram,
with different values. The Journal supports this and will write such entries to
disk without complaining. This is useful for associating a single log entry
with multiple suitable objects of the same type at once. This should only be
used for specific Journal fields however, where this is expected. Do not use
this for Journal fields where this is not expected and where code reasonably
assumes per-event uniqueness of the keys. In most cases code that consumes and
displays log entries is likely to ignore such non-unique fields or only
consider the first of the specified values. Specifically, if a Journal entry
contains multiple `MESSAGE=` fields, likely only the first one is
displayed. Note that a well-written logging client library thus will not use a
plain dictionary for accepting structured log metadata, but rather a data
structure that allows non-unique keys, for example an array, or a dictionary
that optionally maps to a set of values instead of a single value.

## Example Datagram

Here's an encoded message, with various common fields, all encoded according to
the first serialization method, with the exception of one, where the value
contains a newline character, and thus the second method is needed to be used.

```
PRIORITY=3\n
SYSLOG_FACILITY=3\n
CODE_FILE=src/foobar.c\n
CODE_LINE=77\n
BINARY_BLOB\n
\004\000\000\000\000\000\000\000xx\nx\n
CODE_FUNC=some_func\n
SYSLOG_IDENTIFIER=footool\n
MESSAGE=Something happened.\n
```

(Lines are broken here after each `\n` to make things more readable. C-style
backslash escaping is used.)

## Automatic Protocol Upgrading

It might be wise to automatically upgrade to logging via the Journal's native
protocol in clients that previously used the BSD syslog protocol. Behaviour in
this case should be pretty obvious: try connecting a socket to
`/run/systemd/journal/socket` first (on success use the native Journal
protocol), and if that fails fall back to `/dev/log` (and use the BSD syslog
protocol).

Programs normally logging to STDERR might also choose to upgrade to native
Journal logging in case they are invoked via systemd's service logic, where
STDOUT and STDERR are going to the Journal anyway. By preferring the native
protocol over STDERR-based logging, structured metadata can be passed along,
including priority information and more — which is not available on STDERR
based logging. If a program wants to detect automatically whether its STDERR is
connected to the Journal's stream transport, look for the `$JOURNAL_STREAM`
environment variable. The systemd service logic sets this variable to a
colon-separated pair of device and inode number (formatted in decimal ASCII) of
the STDERR file descriptor. If the `.st_dev` and `.st_ino` fields of the
`struct stat` data returned by `fstat(STDERR_FILENO, …)` match these values a
program can be sure its STDERR is connected to the Journal, and may then opt to
upgrade to the native Journal protocol via an `AF_UNIX` socket of its own, and
cease to use STDERR.

Why bother with this environment variable check? A service program invoked by
systemd might employ shell-style I/O redirection on invoked subprograms, and
those should likely not upgrade to the native Journal protocol, but instead
continue to use the redirected file descriptors passed to them. Thus, by
comparing the device and inode number of the actual STDERR file descriptor with
the one the service manager passed, one can make sure that no I/O redirection
took place for the current program.

## Alternative Implementations

If you are looking for alternative implementations of this protocol (besides
systemd's own in `sd_journal_print()`), consider
[GLib's](https://gitlab.gnome.org/GNOME/glib/-/blob/main/glib/gmessages.c) or
[`dbus-broker`'s](https://github.com/bus1/dbus-broker/blob/main/src/util/log.c).

And that's already all there is to it.