Struct slog::Logger [−] [src]

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

Logging handle used to execute logging statements

In an essence Logger instance holds two pieces of information:

Root Logger is created with a Drain that will be cloned to every member of it's hierarchy.

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

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+Sync 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 it's Drain with existing key-value pairs appended to the Loggers key-value pairs. By itself it's effectively very similar to Logger being an ancestor of Logger that originated the logging Record. Combined with other Drains, 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.

Methods

impl<D> Logger<D> where
    D: SendSyncUnwindSafeDrain<Ok = (), Err = Never>, 
[src]

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"),
    );
}

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.

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 it's 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"));
}

Log one logging Record

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

Get list of key-value pairs assigned to this Logger

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.

Create a copy with "erased" type

See into_erased

Trait Implementations

impl<D: Clone> Clone for Logger<D> where
    D: SendSyncUnwindSafeDrain<Ok = (), Err = Never>, 
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl<D> Debug for Logger<D> where
    D: SendSyncUnwindSafeDrain<Ok = (), Err = Never>, 
[src]

Formats the value using the given formatter.

impl<D> Drain for Logger<D> where
    D: SendSyncUnwindSafeDrain<Ok = (), Err = Never>, 
[src]

Type returned by this drain Read more

Type of potential errors that can be returned by this Drain

Handle one logging statement (Record) Read more

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

Filter logging records passed to Drain Read more

Filter logging records passed to Drain (by level) Read more

Map logging errors returned by this drain Read more

Ignore results returned by this drain Read more

Make Self panic when returning any errors Read more