Clarify on relationship between FilterBuilder and max-level

[pronebird]

Hi,

Could you please clarify why do we need max_level and filter at the same time? I understand that we can set the log level for individual crates but how does debug, in the filter string affects the max level that we set? (trace)

android_logger::init_once(
        Config::default()
            .with_max_level(LevelFilter::Trace)
            .with_tag("mytag")
            .with_filter(FilterBuilder::new().parse("debug,hello::crate=trace").build()),
    );

[Nercury]

It's a historical leftover. We did not have filter at the start.

[MarijnS95]

This is still something we need to address, either by improving the code or at the very least by improving our documentation. The above snippet is taken from the README/documentation and doesn't spend any effort to explain why it's setting this max_level to Trace, the global log level to debug, and then one specific module to trace again. TL;DR: they stack.

Caution

This explanation does not include the recently added API level 30 __android_log_is_loggable_len() call which might make things even more complicated.

• with_max_level() configures log::set_max_level(). This defaults to Off meaning no log::log!() macros ever come through to android_logger;
• Once those log messages finally come through, we use env_filter's Filter struct (per its FilterBuilder above) to filter messages again. If a user didn't specify debug, to let all unspecified modules log at debug level, they won't pass through at all and only hello::crate becomes visible ¹.

Combining these observations together, it seems like with_max_level() should be removed in favour of simply setting it to the highest LevelFilter that the filter could possibly match on. Conveniently, this is exactly what env_logger (the main user of env_filter) does through the provided helper function:

https://github.com/rust-cli/env_logger/blob/8b81e467b719777cc28850ffb879de8b403e0a1d/src/logger.rs#L501-L505

Footnotes

1. This is where I got stuck initially. I only had with_max_level(Trace), and started adding a Filter to limit one verbose module to use Debug. What I didn't realize is that the Filter would skip every module that doesn't match, unless a global filter_level() was configured. With that over with, I had to come here to realize that with_max_level() plays independently into it too. ↩

[Nercury]

I am totally for simplifying the API; as long as we release it as next version - 0.16.

[MarijnS95]

I'll set something up along these lines and rework the recently merged test along with it.

[MarijnS95]

I've had quite a hard time setting this up after #84 and the merge of #89, which complicate the internal setup and confusion among max_level even further :/. Apologies for taking more time.