Struct Journald 

pub struct Journald { /* private fields */ }

Available on Unix only.

A systemd journal appender.

Journal access

Standard fields

The journald appender always sets the following standard journal fields:

• PRIORITY: The log level mapped to a priority (see below).
• MESSAGE: The formatted log message (see Record::payload()).
• SYSLOG_PID: The PID of the running process (see std::process::id()).
• CODE_FILE: The filename the log message originates from (see Record::file(), only if present).
• CODE_LINE: The line number the log message originates from (see Record::line(), only if present).

It also sets SYSLOG_IDENTIFIER if non-empty (see Journald::with_syslog_identifier).

Additionally, it also adds the following non-standard fields:

• TARGET: The target of the log record (see Record::target()).
• CODE_MODULE: The module path of the log record (see Record::module_path(), only if present).

Log levels and Priorities

Level gets mapped to journal (syslog) priorities as follows:

• Level::Error → 3 (err)
• Level::Warn → 4 (warning)
• Level::Info → 5 (notice)
• Level::Debug → 6 (info)
• Level::Trace → 7 (debug)

Higher priorities (crit, alert, and emerg) are not used.

Custom fields and structured record fields

In addition to these fields the appender also adds all structures key-values from each log record as journal fields, and also supports global extra fields via Journald::with_extra_fields.

Journald allows only ASCII uppercase letters, ASCII digits, and the underscore in field names, and limits field names to 64 bytes. See journal_field_valid for the precise validation rules.

This appender mangles the keys of additional key-values on records and names of custom fields according to the following rules, to turn them into valid journal fields:

• If the key is entirely empty, use EMPTY.
• Transform the entire value to ASCII uppercase.
• Replace all invalid characters with underscore.
• If the key starts with an underscore or digit, which is not permitted, prepend ESCAPED_.
• Cap the result to 64 bytes.

Errors

The appender tries to connect to journald when constructed, to provide early on feedback if journald is not available (e.g. in containers where the journald socket is not mounted into the container).

Implementations

impl Journald

pub fn new() -> Result<Self, Error>

Construct a journald appender

Fails if the journald socket couldn’t be opened.

pub fn with_extra_field<K: AsRef<str>, V: AsRef<[u8]>>( self, name: K, value: V, ) -> Self

Add an extra field to be added to every log entry.

name is the name of a custom field, and value its value. Fields are appended to every log entry, in order they were added to the appender.

Restrictions on field names

name should be a valid journal file name, i.e. it must only contain ASCII uppercase alphanumeric characters and the underscore, and must start with an ASCII uppercase letter.

Invalid keys in extra_fields are escaped according to the rules documented in Journald.

It is not recommended that name is any of the standard fields already added by this appender (see Journald); though journald supports multiple values for a field, journald clients may not handle unexpected multi-value fields properly and perhaps only show the first value. Specifically, even journalctl will only show the first MESSAGE value of journal entries.

Restrictions on values

There are no restrictions on the value.

pub fn with_extra_fields<I, K, V>(self, extra_fields: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: AsRef<str>, V: AsRef<[u8]>,

Add extra fields to be added to every log entry.

See Self::with_extra_field for details.

pub fn with_syslog_identifier(self, identifier: String) -> Self

Set the syslog identifier for this appender.

The syslog identifier comes from the classic syslog interface (openlog() and syslog()) and tags log entries with a given identifier. Systemd exposes it in the SYSLOG_IDENTIFIER journal field, and allows filtering log messages by syslog identifier with journalctl -t. Unlike the unit (journalctl -u) this field is not trusted, i.e. applications can set it freely, and use it e.g. to further categorize log entries emitted under the same systemd unit or in the same process. It also allows to filter for log entries of processes not started in their own unit.

See Journal Fields and journalctl for more information.

Defaults to the file name of the executable of the current process, if any.

pub fn syslog_identifier(&self) -> &str

Return the syslog identifier in use.

Trait Implementations

impl Append for Journald

fn append( &self, record: &Record<'_>, diags: &[Box<dyn Diagnostic>], ) -> Result<(), Error>

Extract all fields (standard and custom) from record, append all extra_fields given to this appender, and send the result to journald.

fn flush(&self) -> Result<(), Error>

Flush any buffered records.

fn exit(&self) -> Result<(), Error>

Perform any cleanup work before the program exits.

impl Debug for Journald

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.