tracing: Add examples to root readme

[yaahc]

Feature Request

It's pretty common for crate to have a set of code snippets needed to get started with the least effort possible, and I rely on crates I use having the frequently used syntax in snippets in their main README to advertise this. A good example of this is https://github.com/dtolnay/trybuild

Proposal

We should add a basic example of the minimal set of dependencies and syntax to get setup with tracing including

• libraries to include and their most recent versions as a Cargo.toml snippet
• The recommended starting point for setting up a Subscriber
• Minimal example of usage

It may also be helpful to include a screenshot of "Tracing in Action".

[hawkw]

👍 this seems like a great idea! There are examples in the tracing crate's readme (since that's the readme used on its crates.io page), but none in the root repo readme — we should definitely fix that.

[lunchboxav]

Hi, may I try to solve this issue? I'm currently super curious about tracing and want to do more Rust, so this feels like something very interesting for me personally

[yaahc]

I think that sounds like a great idea. If you do make sure your example includes setting the default log level to info or something

[lunchboxav]

hi @yaahc , I think I can get this to work. I made quick code like this

#[instrument]
fn count(nums: i32) -> Vec<i32> {
    let mut seq = vec![];

    for n in 0..=nums {
        debug!("Print number {}", n);
        seq.push(n);
    }

    seq
}

fn main() {
    use tracing_subscriber::fmt;
    let subscriber = fmt::Subscriber::builder()
        .with_env_filter("attrs_args=info")
        .finish();

    tracing::subscriber::with_default(subscriber, || {
        let n = 10;
        let sequence = count(n);
        info!("The first {} numbers are {:?}", n, sequence);
    })
}

But I couldn't get any debug or info message printed in the command line while running the code with cargo run. Is there any specific command or setting that I missed? Thank you

[yaahc]

I'm not sure precisely why its not working, can you remove the attrs_args= part of the filter and just set it to info and confirm that attrs_args actually matches the module_path?

Alternatively I recommend using

static DEFAULT_FILTER: &str = concat!(module_path!(), "=", "debug");

[hawkw]

@lunchboxav In your example, you're setting a filter attr_args=info. This means that any spans and events with a target starting with "attrs_args" and verbosity level INFO or higher will be enabled.

By default, the target of a span or event is the module path of the code it occurs in. I'm assuming your code is not in a file is not called attrs_args. Also, the filter you're setting means the debug events in the count function will not be enabled.

[hawkw]

Instead of using with_env_filter, you could just use

    let subscriber = fmt::Subscriber::builder()
        .with_max_level(tracing::Level::DEBUG)
        .finish();

[yaahc]

this is vaguely what I want to see, though I would prefer to see these split up into multiple small snippets that focus on each piece of syntax that I'd want to quickly refer to

use tracing::{debug, info, instrument};
use tracing_subscriber::fmt;

// using instrument to setup a span and skip to exclude args
#[instrument(skip(_too_long_string))]
fn count(nums: i32, _too_long_string: &str) -> Vec<i32> {
    let mut seq = vec![];

    for n in 0..=nums {
        // logging n in structured form
        debug!(n, "Next Number");
        seq.push(n);
    }

    seq
}

static DEFAULT_FILTER: &str = concat!(module_path!(), "=", "info");

fn main() {
    let filter = tracing_subscriber::EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| DEFAULT_FILTER.into());
    let subscriber = fmt::Subscriber::builder().with_env_filter(filter).finish();

    // setup a scoped subscriber
    tracing::subscriber::with_default(subscriber, || {
        let n = 10;
        let sequence = count(n, "I would really prefer this string wasn't in every log");
        // standard string interpolation log message
        info!("The first {} numbers are {:?}", n, sequence);
    })
}

[lunchboxav]

ah, yes @yaahc @hawkw , I realized I messed up the env_filter there. thanks!

Also, well noted @yaahc , let me break that down..

[hawkw]

I believe #496 closed this.