Struct sp_tracing::Level
pub struct Level(_);Expand description
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.