Introduce logging modes

[semohr]

Description

We’ve made solid progress over the past months on the logging enhancements proposed in #6553. It’s now a good time to align on a clear direction for how logging modes should work going forward.

I’ve put together an initial draft of the updated logging specification in the documentation. @beetbox/maintainers Please take a look and share your ideas/feedback/questions.

Once we’re aligned on the approach, I’ll proceed with the implementation.

---

This is related to the multi-step efforts to improve logging in beets #6553

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.59%. Comparing base (3736513) to head (0071961).
⚠️ Report is 33 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6773      +/-   ##
==========================================
+ Coverage   75.17%   75.59%   +0.42%     
==========================================
  Files         163      163              
  Lines       21228    21299      +71     
  Branches     3352     3358       +6     
==========================================
+ Hits        15958    16101     +143     
+ Misses       4496     4407      -89     
- Partials      774      791      +17     

see 13 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[semohr]

@JOJ0 Would you mind having a look 🙃

[JOJ0]

Hi @semohr appologies for not responding earlier. I'm already picturing how useful the new default mode will be:

This mode explains what beets is doing in a more explicit way than
``legacy``, including key decisions such as matching, tagging, and
file operations, without exposing full internal debug information.

This sounds promising and exactly what I'm often missing in beets. More info, less noise!

What I can't grasp is how this would look like from a plugin developer's perspective. Would we still simply write a log line that looks like this: self._log.info("...", arg)? Would we still only have to define "one explicit log level" for a message? Or would we have to define which log level and as well in which mode it is displayed?

Also I'm wondering if this feature wish could be realised (without using grep): Display regular output of beets plugincmd and give me DEBUG level of only plugincmd, not the other plugins and not core DEBUG stuff.

Maybe all dumb questions but some example snippets of how calls would look like and how refactoring of existing log calls could look like (if required). Many thanks for this proposal!

[semohr]

Thanks for having a look! You think anything of the following should go into the docs?

---

What I can't grasp is how this would look like from a plugin developer's perspective. Would we still simply write a log line that looks like this: self._log.info("...", arg)? Would we still only have to define "one explicit log level" for a message? Or would we have to define which log level and as well in which mode it is displayed?

Things should not change from a plugin developer's perspective. You would continue to use the existing logging API, for example:

self._log.info("Info message")
self._log.debug("Info message")
self._log.warning("Info message")
# Or equivalently:
logging.getLogger("beets.<plugin>").info("info message")

Plugin developers would still only choose the appropriate log level (info, debug, warning, etc.). The new modes do not introduce an additional concept that plugins need to target. Instead, they determine which log messages are shown in the terminal and how they are presented. In other words, the modes are simply an abstraction over the logging configuration.

---

Also I'm wondering if this feature wish could be realised (without using grep): Display regular output of beets plugincmd and give me DEBUG level of only plugincmd, not the other plugins and not core DEBUG stuff.

Yes, that should be possible if we decide to allow custom modes. Personally, my ideal configuration would be to only show warning and error messages in the console, while writing everything else (including debug output) to a log file. But that's just my personal preference. :)

---

Maybe all dumb questions but some example snippets of how calls would look like and how refactoring of existing log calls could look like (if required). Many thanks for this proposal!

The dump questions are the ones not asked 🙃 Modes can simply be thought of as predefined logging configurations that a user can toggle. The concept does not really propagate into the code beyond the initial logging configuration. From a plugin maintainer's perspective, there should be no refactoring required.

[JOJ0]

Love the log file idea! I'm missing this since ever! ❤️

[Serene-Arc]

Couple things. First, is it worth having all these additional configuration options when the standard is -v flags for command-line interfaces? It seems like a lot of extra stuff. Those built-in modes correlate exactly with increasing levels of -v.

Also, one thing that I've done for a project with lots of diagnostic output that normal users aren't really interested in is, by default, have a logging file with the maximum level of information by default. It's written to with each run of the program and as part of bug reports, we can just point users to that and have it pasted in the report. It might simplify things in that respect.

We should definitely be using the built-in logging features that Python comes with more. Being able to specify those through the YAML is a nice touch.

[semohr]

Thanks for having a look and the reply! Here my thought, hope it gives you insights into my perspective :)

---

Couple things. First, is it worth having all these additional configuration options when the standard is -v flags for command-line interfaces? It seems like a lot of extra stuff. Those built-in modes correlate exactly with increasing levels of -v.

From my perspective, beets has always stood out because of how customizable and configurable it is. In the same way giving users the freedom to configure the logging freely opens up genuinely useful new avenues.

Regarding the verbose options it is intended to correlate with the logging modes (it already mostly behaves the way I have written up in the specs). Verbosity adjusts the level of what gets logged, while the mode controls the initial configuration, like formatting, handlers, colors, all that stuff.

In that regard modes and verbose options seem orthogonal to me. I imagine I would set a mode (which I like and maybe even customized) as default in the config file and than adjust the level with the -v flag if I need more information. Ofc one can also use --logging as that is our common interface for configuration options. I see this cli argument mostly used when reporting issues (with --logging debug) or maybe depending on a user workflows.

Also, one thing that I've done for a project with lots of diagnostic output that normal users aren't really interested in is, by default, have a logging file with the maximum level of information by default. It's written to with each run of the program and as part of bug reports, we can just point users to that and have it pasted in the report. It might simplify things in that respect.

I was thinking about this but I don't want to enforce it for the same reason as above. Imo beets tries to be a agnostic framework and should not lock people into a singular opinion. MAX level is also not too well defined: does it include DEBUG from third-party libraries? From plugins? What about tracing information?

There seem to be many subjective takes here. Instead of baking in one opinionated default, different modes and the escapehatch with arbitrary logging configs lets us stay impartial.