Journal Message Catalogs

Starting with 196 systemd includes a message catalog system which allows augmentation on display of journal log messages with short explanation texts, keyed off the MESSAGE_ID= field of the entry. Many important log messages generated by systemd itself have message catalog entries. External packages can easily provide catalog data for their own messages.

The message catalog has a number of purposes:


Message catalog source files are simple text files that follow an RFC822 inspired format. To get an understanding of the format here’s an example file, which includes entries for many important messages systemd itself generates. On installation of a package that includes message catalogs all installed message catalog source files get compiled into a binary index, which is then used to look up catalog data.

journalctl’s -x command line parameter may be used to augment on display journal log messages with message catalog data when browsing. journalctl --list-catalog may be used to print a list of all known catalog entries.

To register additional catalog entries, packages may drop (text) catalog files into /usr/lib/systemd/catalog/ with a suffix of .catalog. The files are not accessed directly when needed, but need to be built into a binary index file with journalctl --update-catalog.

Here’s an example how a single catalog entry looks like in the text source format. Multiple of these may be listed one after the other per catalog source file:

-- fc2e22bc6ee647b6b90729ab34a250b1
Subject: Process @COREDUMP_PID@ (@COREDUMP_COMM@) dumped core
Defined-By: systemd
Documentation: man:core(5)

Process @COREDUMP_PID@ (@COREDUMP_COMM@) crashed and dumped core.

This usually indicates a programming error in the crashing program and
should be reported to its vendor as a bug.

The text format of the .catalog files is as follows:

Adding Message Catalog Support to Your Program

Note that the message catalog is only available for messages generated with the MESSAGE_ID= journal meta data field, as this is need to find the right entry for a message. For more information on the MESSAGE_ID= journal entry field see systemd.journal-fields(7).

To add message catalog entries for log messages your application generates, please follow the following guidelines: