Struct Level

pub struct Level(/* private fields */);

Describes the level of verbosity of a span or event.

Comparing Levels

Level implements the [PartialOrd] and [Ord] traits, allowing two Levels to be compared to determine which is considered more or less verbose. Levels which are more verbose are considered “greater than” levels which are less verbose, with Level::ERROR considered the lowest, and Level::TRACE considered the highest.

For example:

use tracing_core::Level;

assert!(Level::TRACE > Level::DEBUG);
assert!(Level::ERROR < Level::WARN);
assert!(Level::INFO <= Level::DEBUG);
assert_eq!(Level::TRACE, Level::TRACE);

Filtering

Levels are typically used to implement filtering that determines which spans and events are enabled. Depending on the use case, more or less verbose diagnostics may be desired. For example, when running in development, DEBUG-level traces may be enabled by default. When running in production, only INFO-level and lower traces might be enabled. Libraries may include very verbose diagnostics at the DEBUG and/or TRACE levels. Applications using those libraries typically chose to ignore those traces. However, when debugging an issue involving said libraries, it may be useful to temporarily enable the more verbose traces.

The [LevelFilter] type is provided to enable filtering traces by verbosity. Levels can be compared against [LevelFilter]s, and [LevelFilter] has a variant for each Level, which compares analogously to that level. In addition, [LevelFilter] adds a [LevelFilter::OFF] variant, which is considered “less verbose” than every other Level. This is intended to allow filters to completely disable tracing in a particular context.

For example:

use tracing_core::{Level, LevelFilter};

assert!(LevelFilter::OFF < Level::TRACE);
assert!(LevelFilter::TRACE > Level::DEBUG);
assert!(LevelFilter::ERROR < Level::WARN);
assert!(LevelFilter::INFO <= Level::DEBUG);
assert!(LevelFilter::INFO >= Level::INFO);

Examples

Below is a simple example of how a Subscriber could implement filtering through a [LevelFilter]. When a span or event is recorded, the Subscriber::enabled method compares the span or event’s Level against the configured [LevelFilter]. The optional Subscriber::max_level_hint method can also be implemented to allow spans and events above a maximum verbosity level to be skipped more efficiently, often improving performance in short-lived programs.

use tracing_core::{span, Event, Level, LevelFilter, Subscriber, Metadata};

#[derive(Debug)]
pub struct MySubscriber {
    /// The most verbose level that this subscriber will enable.
    max_level: LevelFilter,

    // ...
}

impl MySubscriber {
    /// Returns a new `MySubscriber` which will record spans and events up to
    /// `max_level`.
    pub fn with_max_level(max_level: LevelFilter) -> Self {
        Self {
            max_level,
            // ...
        }
    }
}
impl Subscriber for MySubscriber {
    fn enabled(&self, meta: &Metadata<'_>) -> bool {
        // A span or event is enabled if it is at or below the configured
        // maximum level.
        meta.level() <= &self.max_level
    }

    // This optional method returns the most verbose level that this
    // subscriber will enable. Although implementing this method is not
    // *required*, it permits additional optimizations when it is provided,
    // allowing spans and events above the max level to be skipped
    // more efficiently.
    fn max_level_hint(&self) -> Option<LevelFilter> {
        Some(self.max_level)
    }

    // Implement the rest of the subscriber...
    fn new_span(&self, span: &span::Attributes<'_>) -> span::Id {
        // ...
    }
    fn event(&self, event: &Event<'_>) {
        // ...
    }

    // ...
}

It is worth noting that the tracing-subscriber crate provides additional APIs for performing more sophisticated filtering, such as enabling different levels based on which module or crate a span or event is recorded in.

Implementations

impl Level

pub const ERROR: Level = _

The “error” level.

Designates very serious errors.

pub const WARN: Level = _

The “warn” level.

Designates hazardous situations.

pub const INFO: Level = _

The “info” level.

Designates useful information.

pub const DEBUG: Level = _

The “debug” level.

Designates lower priority information.

pub const TRACE: Level = _

The “trace” level.

Designates very low priority, often extremely verbose, information.

pub fn as_str(&self) -> &'static str

Returns the string representation of the Level.

This returns the same string as the fmt::Display implementation.

Trait Implementations

impl Clone for Level

fn clone(&self) -> Level

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Level

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

Formats the value using the given formatter.

impl Display for Level

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

Formats the value using the given formatter.

impl FromStr for Level

type Err = ParseLevelError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Level, ParseLevelError>

Parses a string s to return a value of this type.

impl Hash for Level

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given [Hasher].

impl Ord for Level

fn cmp(&self, other: &Level) -> Ordering

This method returns an [Ordering] between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<LevelFilter> for Level

fn eq(&self, other: &LevelFilter) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Level

fn eq(&self, other: &Level) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<LevelFilter> for Level

fn partial_cmp(&self, other: &LevelFilter) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &LevelFilter) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &LevelFilter) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &LevelFilter) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &LevelFilter) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd for Level

fn partial_cmp(&self, other: &Level) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Level) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Level) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Level) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Level) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Level

impl Eq for Level

impl StructuralPartialEq for Level