Struct JournalLog

pub struct JournalLog { /* private fields */ }

A systemd journal logger.

Journal access

Standard fields

The journald logger always sets the following standard journal fields:

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

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

Additionally it also adds the following non-standard fields:

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

Log levels and Priorities

log::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 logger also adds all structures key-values (see log::Record::key_values) from each log record as journal fields, and also supports global extra fields via Self::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 upstream’s journal_field_valid for the precise validation rules.

This logger 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 logger 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).

Later on, the logger simply ignores any errors when sending log records to journald, simply because the log interface does not expose faillible operations.

Implementations

impl JournalLog

pub fn new() -> Result<Self>

Create a journal log instance with a default syslog identifier.

pub fn empty() -> Result<Self>

Create an empty journal log instance, with no extra fields and no syslog identifier.

See Self::with_syslog_identifier and Self::with_extra_fields to set either. It’s recommended to at least set the syslog identifier.

pub fn install(self) -> Result<(), SetLoggerError>

Install this logger globally.

See log::set_boxed_logger.

pub fn add_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 logger.

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 JournalLog.

It is not recommended that name is any of the standard fields already added by this logger (see JournalLog); 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 shouw 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]>,

Set extra fields to be added to every log entry.

Remove all previously added fields.

See Self::add_extra_field for details.

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

Set the given syslog identifier for this logger.

The logger writes this string in the SYSLOG_IDENTIFIER field, which can be filtered for with journalctl -t.

Use current_exe_identifier() to obtain the standard identifier for the current executable.

pub fn journal_send(&self, record: &Record<'_>) -> Result<()>

Send a single log record to the journal.

Extract all fields (standard and custom) from record (see [JournalLog]), append all extra_fields` given to this logger, and send the result to journald.

Trait Implementations

impl Log for JournalLog

The Log interface for JournalLog.

fn enabled(&self, _metadata: &Metadata<'_>) -> bool

Whether this logger is enabled.

Always returns true.

fn log(&self, record: &Record<'_>)

Send the given record to the systemd journal.

Errors

Ignore any errors which occur when sending record to journald because we cannot reasonably handle them at this place.

See JournalLog::journal_send for a function which returns any error which might have occurred while sending the record to the journal.

fn flush(&self)

Flush log records.

A no-op for journal logging.