Struct Subscriber

pub struct Subscriber { /* private fields */ }

Sends events and their fields to journald

journald conventions for structured field names differ from typical tracing idioms, and journald discards fields which violate its conventions. Hence, this subscriber automatically sanitizes field names by translating .s into _s, stripping leading _s and non-ascii-alphanumeric characters other than _, and upcasing.

By default, levels are mapped losslessly to journald PRIORITY values as follows:

• ERROR => Error (3)
• WARN => Warning (4)
• INFO => Notice (5)
• DEBUG => Informational (6)
• TRACE => Debug (7)

These mappings can be changed with Subscriber::with_priority_mappings.

The standard journald CODE_LINE and CODE_FILE fields are automatically emitted. A TARGET field is emitted containing the event’s target.

For events recorded inside spans, an additional SPAN_NAME field is emitted with the name of each of the event’s parent spans.

User-defined fields other than the event message field have a prefix applied by default to prevent collision with standard fields.

Implementations

impl Subscriber

pub fn new() -> Result<Self>

Construct a journald subscriber

Fails if the journald socket couldn’t be opened. Returns a NotFound error unconditionally in non-Unix environments.

pub fn with_field_prefix(self, x: Option<String>) -> Self

Sets the prefix to apply to names of user-defined fields other than the event message field. Defaults to Some("F").

pub fn with_priority_mappings(self, mappings: PriorityMappings) -> Self

Sets how tracing_core::Levels are mapped to journald priorities.

Examples

use tracing_journald::{Priority, PriorityMappings};
use tracing_subscriber::prelude::*;
use tracing::error;

let registry = tracing_subscriber::registry();
match tracing_journald::subscriber() {
    Ok(subscriber) => {
        registry.with(
            subscriber
                // We can tweak the mappings between the trace level and
                // the journal priorities.
                .with_priority_mappings(PriorityMappings {
                    info: Priority::Informational,
                    ..PriorityMappings::new()
                }),
        );
    }
    // journald is typically available on Linux systems, but nowhere else. Portable software
    // should handle its absence gracefully.
    Err(e) => {
        registry.init();
        error!("couldn't connect to journald: {}", e);
    }
}

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

Sets the syslog identifier for this logger.

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 with_custom_fields<T: AsRef<str>, U: AsRef<[u8]>>( self, fields: impl IntoIterator<Item = (T, U)>, ) -> Self

Adds fields that will get be passed to journald with every log entry.

The input values of this function are interpreted as (field, value) pairs.

This can for example be used to configure the syslog facility. See Journal Fields and journalctl for more information.

Fields specified using this method will be added to the journald message alongside fields generated from the event’s fields, its metadata, and the span context. If the name of a field provided using this method is the same as the name of a field generated by the subscriber, both fields will be sent to journald.

let sub = Subscriber::new()
    .unwrap()
    .with_custom_fields([("SYSLOG_FACILITY", "17")]);

pub fn syslog_identifier(&self) -> &str

Returns the syslog identifier in use.

Trait Implementations

impl<C> Subscribe<C> for Subscriber

where C: Collect + for<'span> LookupSpan<'span>,

fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, C>)

Notifies this subscriber that a new span was constructed with the given Attributes and Id.

fn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, C>)

Notifies this subscriber that a span with the given Id recorded the given values.

fn on_event(&self, event: &Event<'_>, ctx: Context<'_, C>)

Notifies this subscriber that an event has occurred.

fn on_register_dispatch(&self, collector: &Dispatch)

Performs late initialization when installing this subscriber as a collector.

fn on_subscribe(&mut self, collector: &mut C)

Performs late initialization when attaching a subscriber to a collector.

fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this subscriber, returning whether or not the subscriber is interested in being notified about the callsite, similarly to Collect::register_callsite.

fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, C>) -> bool

Returns true if this subscriber is interested in a span or event with the given metadata in the current Context, similarly to Collect::enabled.

fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, C>)

Notifies this subscriber that a span with the ID span recorded that it follows from the span with the ID follows.

fn event_enabled(&self, _event: &Event<'_>, _ctx: Context<'_, C>) -> bool

Called before on_event, to determine if on_event should be called.

fn on_enter(&self, _id: &Id, _ctx: Context<'_, C>)

Notifies this subscriber that a span with the given ID was entered.

fn on_exit(&self, _id: &Id, _ctx: Context<'_, C>)

Notifies this subscriber that the span with the given ID was exited.

fn on_close(&self, _id: Id, _ctx: Context<'_, C>)

Notifies this subscriber that the span with the given ID has been closed.

fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, C>)

Notifies this subscriber that a span ID has been cloned, and that the subscriber returned a different ID.

fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C>

where S: Subscribe<C>, Self: Sized,

Composes this subscriber around the given collector, returning a Layered struct implementing Subscribe.

fn with_collector(self, inner: C) -> Layered<Self, C>

where Self: Sized,

Composes this subscriber with the given collector, returning a Layered struct that implements Collect.

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, C>

where Self: Sized, F: Filter<C>,

Combines self with a Filter, returning a Filtered subscriber.

fn boxed(self) -> Box<dyn Subscribe<C> + Sync + Send>

where Self: Sized + Subscribe<C> + Send + Sync + 'static, C: Collect,

Erases the type of this subscriber, returning a Boxed dyn Subscribe trait object.