Struct Logger

pub struct Logger<D = Arc<dyn SendSyncRefUnwindSafeDrain<Ok = (), Err = Never>>>
where
    D: SendSyncUnwindSafeDrain<Ok = (), Err = Never>,
{ /* private fields */ }

Logging handle used to execute logging statements

In an essence Logger instance holds two pieces of information:

• drain - destination where to forward logging Records for processing.
• context - list of key-value pairs associated with it.

The root Logger is created with a Drain that will be cloned to every member of its hierarchy.

Child Loggers are built from existing ones, and inherit their key-value pairs, which can be supplemented with additional pairs.

Cloning existing loggers and creating new ones is cheap. Loggers can be freely passed around the code and between threads.

Loggers are Sync+Send - there’s no need to synchronize accesses to them, as they can accept logging records from multiple threads at once. They can be sent to any thread. Because of that they require the Drain to be Sync+Send as well. Not all Drains are Sync or Send but they can often be made so by wrapping in a Mutex and/or Arc.

Logger implements Drain trait. Any logging Record delivered to a Logger functioning as a Drain will be delivered to its Drain with existing key-value pairs appended to the Logger’s key-value pairs. By itself, it is effectively very similar to Logger being an ancestor of Logger that originated the logging Record. Combined with other Drains, this allows custom processing logic for a sub-tree of a whole logging tree.

Logger is parametrized over type of a Drain associated with it (D). It default to type-erased version so Logger without any type annotation means Logger<Arc<SendSyncRefUnwindSafeDrain<Ok = (), Err = Never>>>. See Logger::root_typed and Logger::to_erased for more information.

Implementations

impl<D> Logger<D>

where D: SendSyncUnwindSafeDrain<Ok = (), Err = Never>,

pub fn root<T>(drain: D, values: OwnedKV<T>) -> Logger

where D: 'static + SendSyncRefUnwindSafeDrain<Err = Never, Ok = ()>, T: SendSyncRefUnwindSafeKV + 'static,

Build a root Logger

Root logger starts a new tree associated with a given Drain. Root logger drain must return no errors. See Drain::ignore_res() and Drain::fuse().

All children and their children (and so on), form one logging tree sharing a common drain. See Logger::new.

This version (as opposed to Logger:root_typed) will take drain and made it into Arc<SendSyncRefUnwindSafeDrain<Ok = (), Err = Never>>. This is typically the most convenient way to work with Loggers.

Use o! macro to build OwnedKV object.

#[macro_use]
extern crate slog;

fn main() {
    let _root = slog::Logger::root(
        slog::Discard,
        o!("key1" => "value1", "key2" => "value2"),
    );
}

pub fn root_typed<T>(drain: D, values: OwnedKV<T>) -> Logger<D>

where D: 'static + SendSyncUnwindSafeDrain<Err = Never, Ok = ()> + Sized, T: SendSyncRefUnwindSafeKV + 'static,

Build a root Logger that retains drain type

Unlike Logger::root, this constructor retains the type of a drain, which allows highest performance possible by eliminating indirect call on Drain::log, and allowing monomorphization of Logger and Drain objects.

If you don’t understand the implications, you should probably just ignore it.

See Logger:into_erased and Logger::to_erased for conversion from type returned by this function to version that would be returned by Logger::root.

pub fn new<T>(&self, values: OwnedKV<T>) -> Logger<D>

where T: SendSyncRefUnwindSafeKV + 'static, D: Clone,

Build a child logger

Child logger inherits all existing key-value pairs from its parent and supplements them with additional ones.

Use o! macro to build OwnedKV object.

Drain cloning (D : Clone requirement)

All children, their children and so on, form one tree sharing a common drain. This drain, will be Cloned when this method is called. That is why Clone must be implemented for D in Logger<D>::new.

For some Drain types Clone is cheap or even free (a no-op). This is the case for any Logger returned by Logger::root and its children.

When using Logger::root_typed, it’s possible that cloning might be expensive, or even impossible.

The reason why wrapping in an Arc is not done internally, and exposed to the user is performance. Calling Drain::log through an Arc is tiny bit slower than doing it directly.

#[macro_use]
extern crate slog;

fn main() {
    let root = slog::Logger::root(slog::Discard,
        o!("key1" => "value1", "key2" => "value2"));
    let _log = root.new(o!("key" => "value"));
}

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

Log one logging Record

Use specific logging functions instead. See log! macro documentation.

pub fn list(&self) -> &OwnedKVList

Get list of key-value pairs assigned to this Logger

pub fn into_erased( self, ) -> Logger<Arc<dyn SendSyncRefUnwindSafeDrain<Ok = (), Err = Never>>>

where D: SendRefUnwindSafeDrain + 'static,

Convert to default, “erased” type: Logger<Arc<SendSyncUnwindSafeDrain>>

Useful to adapt Logger<D : Clone> to an interface expecting Logger<Arc<...>>.

Note that calling on a Logger<Arc<...>> will convert it to Logger<Arc<Arc<...>>> which is not optimal. This might be fixed when Rust gains trait implementation specialization.

pub fn to_erased( &self, ) -> Logger<Arc<dyn SendSyncRefUnwindSafeDrain<Ok = (), Err = Never>>>

where D: SendRefUnwindSafeDrain + 'static + Clone,

Create a copy with “erased” type

See into_erased

Trait Implementations

impl<D> Clone for Logger<D>

where D: SendSyncUnwindSafeDrain<Ok = (), Err = Never> + Clone,

fn clone(&self) -> Logger<D>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<D> Debug for Logger<D>

where D: SendSyncUnwindSafeDrain<Ok = (), Err = Never>,

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

Formats the value using the given formatter.

impl<D> Drain for Logger<D>

where D: SendSyncUnwindSafeDrain<Ok = (), Err = Never>,

type Ok = ()

Type returned by this drain

type Err = NeverStruct

Type of potential errors that can be returned by this Drain

fn log( &self, record: &Record<'_>, values: &OwnedKVList, ) -> Result<Self::Ok, Self::Err>

Handle one logging statement (Record)

fn is_enabled(&self, level: Level) -> bool

Avoid: Check if messages at the specified log level are maybe enabled for this logger.

fn is_critical_enabled(&self) -> bool

Avoid: See is_enabled

fn is_error_enabled(&self) -> bool

Avoid: See is_enabled

fn is_warning_enabled(&self) -> bool

Avoid: See is_enabled

fn is_info_enabled(&self) -> bool

Avoid: See is_enabled

fn is_debug_enabled(&self) -> bool

Avoid: See is_enabled

fn is_trace_enabled(&self) -> bool

Avoid: See is_enabled

fn map<F, R>(self, f: F) -> R

where Self: Sized, F: FnOnce(Self) -> R,

Pass Drain through a closure, eg. to wrap into another Drain.

fn filter<F>(self, f: F) -> Filter<Self, F>

where Self: Sized, F: FilterFn,

Filter logging records passed to Drain

fn filter_level(self, level: Level) -> LevelFilter<Self>

where Self: Sized,

Filter logging records passed to Drain (by level)

fn map_err<F, E>(self, f: F) -> MapError<Self, E>

where Self: Sized, F: MapErrFn<Self::Err, E>,

Map logging errors returned by this drain

fn ignore_res(self) -> IgnoreResult<Self>

where Self: Sized,

Ignore results returned by this drain

fn fuse(self) -> Fuse<Self>

where Self::Err: Debug, Self: Sized,

Make Self panic when returning any errors