Struct LineFilter

pub struct LineFilter { /* private fields */ }

A filter for enabling spans and events by file/module path and line number.

Implementations

impl LineFilter

pub fn new() -> Self

Returns a new LineFilter.

By default, no spans and events are enabled.

pub fn with_env_filter(&mut self, env: EnvFilter) -> &mut Self

Composes self with an EnvFilter that will be checked for spans and events if they are not in the lists of enabled (module, line) and (file, line) pairs.

Examples

use tracing_subscriber::EnvFilter;
use tracing_line_filter::LineFilter;

let mut filter = LineFilter::default();
filter
    .enable_by_mod("my_crate", 28)
    .enable_by_mod("my_crate::my_module", 16)
    // use an ``EnvFilter` that enables DEBUG and lower in `some_module`, and
    // all ERROR spans or events, regardless of location.
    .with_env_filter(EnvFilter::new("error,my_crate::some_other_module=debug"));

pub fn enable_by_mod( &mut self, module: impl Into<Cow<'static, str>>, line: u32, ) -> &mut Self

Enable a span or event in the Rust module module on line line.

Notes

• Module paths should include the name of the crate. For example, the module my_module in my_crate would have path my_crate::my_module.
• If no span or event exists at the specified location, or if the module path does not exist, this will silently do nothing.
• Line numbers are relative to the start of the file, not to the start of the module. If a module does not have its own file (i.e., it’s defined like mod my_module { ... }), the line number is relative to the containing file.

Examples

Enabling an event:

use tracing_line_filter::LineFilter;

mod my_module {
    pub fn do_stuff() {
        tracing::info!("doing stuff!")
        // ...
    }
}

// Build a line filter to enable the event in `do_stuff`.
let mut filter = LineFilter::default();
filter.enable_by_mod("my_crate::my_module", 5);

// Build a subscriber and enable that filter.
use tracing_subscriber::prelude::*;

tracing_subscriber::registry()
    .with(tracing_subscriber::fmt::layer())
    .with(filter)
    .init();

// Now, the event is enabled!
my_module::do_stuff();

The std::module_path!() macro can be used to enable an event in the current module:

use tracing_line_filter::LineFilter;

pub fn do_stuff() {
    tracing::info!("doing stuff!")
    // ...
}

let mut filter = LineFilter::default();
filter.enable_by_mod(module_path!(), 4);

 // ...

pub fn enable_by_file( &mut self, file: impl AsRef<Path>, line: u32, ) -> Result<&mut Self, BadPath>

Enable a span or event in the file file on line line.

Notes

These file paths must match the file paths emitted by the std::file!() macro. In particular:

• Paths must be absolute.
• Paths must be Rust source code files.
• Paths must be valid UTF-8.

This method validates paths and returns an error if the path is not valid for use in a LineFilter.

Since these paths are absolute, files in Cargo dependencies will include their full path in the local Cargo registry. For example:

/home/eliza/.cargo/registry/src/github.com-1ecc6299db9ec823/tokio-1.0.0/src/util/trace.rs

Therefore, it can be challenging for humans to determine the correct path to a file, especially when it is in a dependency. For this reason, it’s likely best to prefer Rust module paths rather than file paths when accepting input from users directly. Enabling events and spans by file paths is primarily intended for use by automated tools.

pub fn with_modules<I>( &mut self, modules: impl IntoIterator<Item = (I, u32)>, ) -> &mut Self

where I: Into<Cow<'static, str>>,

Enable a set of spans or events by module path.

This is equivalent to repeatedly calling [enable_by_mod].

Examples

use tracing_line_filter::LineFilter;

mod foo {
    pub fn do_stuff() {
        tracing::info!("doing stuff!")
        // ...
    }
}

mod bar {
    pub fn do_other_stuff() {
        tracing::debug!("doing some different stuff...")
        // ...
    }
}

// Build a line filter to enable the events in `do_stuff`
// and `do_other_stuff`.
let mut filter = LineFilter::default();
filter.with_modules(vec![
   ("my_crate::foo", 5),
   ("my_crate::bar", 12)
]);

// Build a subscriber and enable that filter.
use tracing_subscriber::prelude::*;

tracing_subscriber::registry()
    .with(tracing_subscriber::fmt::layer())
    .with(filter)
    .init();

// Now, the events are enabled!
foo::do_stuff();
bar::do_other_stuff();

pub fn with_files<I>( &mut self, files: impl IntoIterator<Item = (I, u32)>, ) -> Result<&mut Self, BadPath>

where I: AsRef<Path>,

Enable a set of spans or events by file path.

This is equivalent to repeatedly calling [enable_by_file], and follows the same path validation rules as that method. See the documentation for [enable_by_file] for details.

Trait Implementations

impl Debug for LineFilter

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

Formats the value using the given formatter.

impl Default for LineFilter

fn default() -> LineFilter

Returns the “default value” for a type.

impl<S: Subscriber> Layer<S> for LineFilter

where EnvFilter: Layer<S>,

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

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

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

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

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

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

fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, S>)

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

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

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

fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, S>)

Notifies this layer that an event has occurred.

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

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

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

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

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

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

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

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

fn and_then<L>(self, layer: L) -> Layered<L, Self, S>

where L: Layer<S>, Self: Sized,

Composes this layer around the given Layer, returning a Layered struct implementing Layer.

fn with_subscriber(self, inner: S) -> Layered<Self, S>

where Self: Sized,

Composes this Layer with the given Subscriber, returning a Layered struct that implements Subscriber.