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! ❤️