Inconsistent behaviour in tracing_subscriber wrt tracing_log

[VorpalBlade]

Bug Report

Version

❯ cargo tree | grep tracing
│   │   │   │   │   ├── tracing v0.1.40
│   │   │   │   │   │   ├── tracing-attributes v0.1.27 (proc-macro)
│   │   │   │   │   │   └── tracing-core v0.1.32
│   │   │   │   │   ├── tracing-subscriber v0.3.18
│   │   │   │   │   │   ├── tracing v0.1.40 (*)
│   │   │   │   │   │   ├── tracing-core v0.1.32 (*)
│   │   │   │   │   │   └── tracing-log v0.2.0
│   │   │   │   │   │       └── tracing-core v0.1.32 (*)
│   │   │   │   ├── tracing v0.1.40 (*)
│   │   │   │   ├── tracing-core v0.1.32 (*)
│   │   │   │   ├── tracing-log v0.2.0 (*)
│   │   │   │   ├── tracing-subscriber v0.3.18 (*)
│   └── tracing v0.1.40 (*)
│   │   └── tracing v0.1.40 (*)
│   ├── tracing v0.1.40 (*)
│   └── tracing v0.1.40 (*)
├── tracing v0.1.40 (*)
├── tracing-log v0.2.0 (*)
└── tracing-subscriber v0.3.18 (*)

(Some of that duplication is due to using cargo workspace hack I believe.)

Platform

Linux athena 6.10.3-zen1-1-zen #1 ZEN SMP PREEMPT_DYNAMIC Sun, 04 Aug 2024 05:11:13 +0000 x86_64 GNU/Linux

Crates

tracing-subscriber and/or tracing-log

Description

The behaviour between tracing_subscriber and tracing_log is inconsistent with regards to if you need both or just the former:

Take the following code:

    // Set up logging with tracing
    let filter = tracing_subscriber::EnvFilter::builder()
        .with_default_directive(tracing::level_filters::LevelFilter::INFO.into())
        .from_env()?;
    let subscriber = tracing_subscriber::fmt::Subscriber::builder()
        .with_env_filter(filter)
        .finish();
    tracing::subscriber::set_global_default(subscriber)?;
    // Compatibility for log crate
    tracing_log::LogTracer::init()?;

Here the tracing_log call is required to get events from the log crate to appear. However if I rewrite it to use tracing_subscriber::registry() instead, it suddenly causes a panic and the tracing_log call must be removed. This seems very inconsistent:

    // Set up logging with tracing
    let filter = tracing_subscriber::EnvFilter::builder()
        .with_default_directive(tracing::level_filters::LevelFilter::INFO.into())
        .from_env()?;
    tracing_subscriber::registry()
        .with(tracing_subscriber::fmt::layer())
        .with(filter)
        .init();
    // Compatibility for log crate, must now *not* be used to prevent panic
    // tracing_log::LogTracer::init()?;

As far as I understood the documentation the two above ways of using tracing_subscriber should be equivalent, but apparently they are not. This might be a documentation issue, and the docs needs to explain the difference (I came across this when rewriting to the second form to be able to add support for tokio-console as well).

Either both should work the same, or the documentation should be clear on why they don't work the same.

[kaffarell]

Do you have the tracing-log feature enabled on tracing-subscriber? Because if you have, the init() function also initiates the log-logger. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/util/trait.SubscriberInitExt.html#method.init.)

[VorpalBlade]

Yes, I have it turned on for both code examples above. It is surprising it doesn't init it also in the first code example though.

[kaffarell]

The first example initiates your own subscriber using the tracing crate (which does not have a tracing-log feature). The second example uses a "default-subscriber" (the registry) from tracing-subscriber, which does have a tracing-log feature.

[VorpalBlade]

Aha, perhaps that should be better documented somewhere (tracing is a non-trivial ecosystem, much more complex than log). I don't know where this would be best documented though. Perhaps some overview "theory of operation" style docs would be a suitable place for it.

[kaffarell]

Yeah, I know, especially initiating a logger is confusing for a lot of people. Maybe we should add a section in here about the initiation of tracing-log? What do you think?

[VorpalBlade]

Hm, I like what some crates like clap, bpaf and winnow are doing: having special "chapters" (modules only included for docs.rs) that contain more of reference/tutorial style documentation (as the module level doc). An mdbook could also be an even better (but more work) location for that.

Another way to look at it: are there too many different ways to do the same thing today? Perhaps it should be documented as "this is the full way of setting up loggers" and "this is the shortcut for the common case" (and reduce the number of possible shortcut approaches). That is obviously a breaking change, so not to be taken lightly, but there is something to be said for simplifying the API.

Yet another perspective: For everything except the most simplest of crates the majority of users will not have time to read all the docs and get a full understanding of how it works. As a user I generally just want to get whatever I'm trying to do done and the move on with my own project.

This applies even more so for "helpers" (like logging, serialisation, command line argument parsing etc) that are necessary but not part of my main objective. That means the the top level documentation (and any clap/winnow style chapters or mdbooks) for the crate in question is critical. That is where I will find out how to use the crate, take the examples and adapt it to what I need.

In conclusion: adding a note where you suggest is not a bad idea, but I would have missed it anyway, since I wasn't even looking at the registry until tokio-console forced me to (before I used the non-registry approach based on the top level docs of tracing/tracing-subscriber)

[kaffarell]

That's actually a nice idea, I like what clap is doing there. I also find myself often looking at the tracing examples, so maybe we could "convert" them somehow to written chapters.