Crate logcontrol

Source
Expand description

Types for systemd’s logcontrol interface.

§The log control interface

The log control interface exposes the basic log settings of a service over a specified D-Bus interface under a fixed D-Bus object path. If a systemd service then defines a fixed D-Bus name in its unit file, via the BusName property in the Service section, systemctl can query and update the logging settings over D-Bus.

For instance, systemd-resolved.service specifies a bus name in its unit file:

BusName=org.freedesktop.resolve1

It also exports the log control interface:

$ busctl tree org.freedesktop.resolve1
└─ /org
  └─ /org/freedesktop
    ├─ /org/freedesktop/LogControl1
    […]

Hence, we can use systemctl to query the log level of the service and change it at runtime, e.g. to enable verbose debugging logging for the running service instance:

# systemctl service-log-level systemd-resolved.service
info
# systemctl service-log-level systemd-resolved.service debug
# systemctl service-log-level systemd-resolved.service
debug

This crate provides abstract types to implement and expose this interface.

§Provided types and utilities

The LogControl1 trait implements abstract log control interface in Rust. To add support for a logging framework you need to implement this trait around a struct which can dynamically adapt the logging output as well as the logging level.

To expose an implementation of the log control interface use the methods of the LogControl1 trait to call the corresponding log control methods in the D-Bus callbacks.

In addition to this core trait and related types, this crate also provides some concrete helper functions to implement aspects of the log control interface.

DBUS_OBJ_PATH provides a constant for the DBUs object path the interface must be served at according to the interface specification, in order to be found by systemctl.

stderr_connected_to_journal determines whether the current process has its stderr directly connected to the systemd journal (as for all processes directly started via systemd units); in this case a log control implementation should default to logging to the KnownLogTarget::Journal log target. This function also helps to implement the KnownLogTarget::Auto target.

§Logging framework implementations and D-Bus frontends

The following crates provides implementations of the LogControl1 trait for a certain logging framework:

These crates implement D-Bus frontends to actually expose an implementation of the LogControl1 trait over D-Bus:

Structs§

LogLevelParseError
The log level was invalid.
LogTargetParseError
The log target was invalid.

Enums§

KnownLogTarget
Known log targets documented in the log control interface or systemctl(1).
LogControl1Error
An error in a LogControl1 operation.
LogLevel
A syslog log level as used by the systemd log control interface.

Statics§

DBUS_OBJ_PATH
The D-Bus object path a log control interface needs to be served on for systemd to find it.

Traits§

LogControl1
Abstract representation of the LogControl1 interface.

Functions§

stderr_connected_to_journal
Whether the current process is directly connected to the systemd journal.
syslog_identifier
Determine the syslog identifier for this process.