From 00719616cadd3c8699a8f5b623bbfbcf8e50a663 Mon Sep 17 00:00:00 2001
From: Sebastian Mohr <sebastian@mohrenclan.de>
Date: Wed, 24 Jun 2026 18:56:40 +0200
Subject: [PATCH] Added proposal for logging modes to docs. This is intended
 for review and decision making at the moment.

---
 docs/reference/index.rst   |   1 +
 docs/reference/logging.rst | 181 +++++++++++++++++++++++++++++++++++++
 2 files changed, 182 insertions(+)
 create mode 100644 docs/reference/logging.rst

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 1f04366597..edb7856245 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -12,3 +12,4 @@ started with beets as a new user, though, you may want to read the
     config
     pathformat
     query
+    logging
diff --git a/docs/reference/logging.rst b/docs/reference/logging.rst
new file mode 100644
index 0000000000..9902a114c3
--- /dev/null
+++ b/docs/reference/logging.rst
@@ -0,0 +1,181 @@
+Logging
+=======
+
+Beets implements a flexible logging solution and ships multiple built-in modes.
+You can select a mode from the command line for quick control, or define and
+customize modes in the configuration file for more advanced setups.
+
+Use the ``--logging <mode>`` option to select a logging mode for a single
+invocation of any beets command. For example, to run the import command in debug
+mode, you could do:
+
+.. code-block:: console
+
+    beets --logging debug import music/
+
+.. note::
+
+    The command-line option overrides any logging mode configured in the
+    configuration file.
+
+If you want to persist a logging mode across multiple invocations of beets, you
+can define a mode in the configuration file. For example, to set the default
+logging mode to ``debug``, you could add the following to your configuration
+file:
+
+.. code-block:: yaml
+    :caption: config.yaml
+
+    logging: debug
+
+.. note::
+
+    Invalid logging modes will be ignored, and beets will fall back to the
+    default mode.
+
+Built-in modes
+--------------
+
+Beets ships with several built-in logging modes. The following table summarizes
+the available modes and their characteristics:
+
+.. conf:: legacy
+
+    Replicates the logging behavior of beets versions prior to 3.0. Messages are emitted
+    as plain text with minimal formatting.
+
+
+    .. code-block:: console
+
+        <plugin>: <message>
+        TODO Add a real output
+
+.. conf:: verbose
+
+     The default logging mode for ``beets>=v3.0.0``.
+
+     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.
+
+     .. code-block:: console
+
+         [<level:Info+>] <logger>: <message>
+         TODO Add a real output
+
+
+    It provides more insight into what beets is doing while keeping output concise
+    enough for everyday use.
+
+.. conf:: quiet
+
+    Suppresses informational output and only displays warnings and errors.
+
+    Useful for scripts or automated workflows where only warnings and errors should be
+    displayed.
+
+    .. code-block:: console
+
+        [<level:Warning+>] <logger>: <message>
+        TODO Add a real output
+
+.. conf:: debug
+
+    Enables verbose diagnostic logging for both core functionality and plugins.
+
+    This mode includes timestamps, log levels, and logger names, making it
+    useful for debugging and development.
+
+    .. code-block:: console
+
+        <time> [<level:Debug+>] <logger>: <message> (<filename>:<line number>)
+        TODO Add a real output
+
+    This mode can produce a large volume of output, especially when plugins emit
+    detailed diagnostic messages.
+
+Custom modes
+------------
+
+While the built-in modes should cover most use cases, having more control over
+the logging configuration can be useful. Beets allows you to define custom
+logging modes in the configuration file.
+
+Custom modes use Python's standard logging configuration dictionary. This gives
+you full access to handlers, formatters, filters, and logger configuration
+options as described in the `Python logging documentation
+<https://docs.python.org/3/library/logging.config.html#logging-config-dictschema>`_.
+
+.. code-block:: yaml
+    :caption: config.yaml: Example custom logging mode
+
+    logging: my_mode
+
+    logging_modes:
+        my_mode:
+            version: 1
+            formatters:
+                detailed:
+                    format: "[%(levelname)s] %(name)s: %(message)s"
+
+            handlers:
+                console:
+                    class: logging.StreamHandler
+                    level: DEBUG
+                    formatter: detailed
+                    stream: ext://sys.stdout
+
+            root:
+                level: DEBUG
+                handlers: [console]
+
+What about the current ``print`` calls?
+---------------------------------------
+
+Will remove this section or rewrite it (just for discussion right now).
+
+``print`` statements should only be used in the ``ui`` layer and are not part of
+the logging system.
+
+Unlike log messages, output from the UI layer is always shown regardless of the
+active logging mode. This ensures that essential user-facing interaction is
+never hidden or filtered by logging configuration.
+
+The UI layer is intended for direct user communication, such as:
+
+- prompts and confirmations
+- interactive questions
+- critical status messages that require immediate attention
+- explicit user-facing feedback during command execution
+
+In other words, the UI layer represents the *communication interface* of beets,
+while the logging system represents *diagnostic and operational telemetry*.
+
+What to do with the ``-v`` options?
+-----------------------------------
+
+Will remove this section or rewrite it (just for discussion right now).
+
+The ``-v`` flags increase the verbosity of the active logging mode by lowering
+the minimum log level. Each additional ``-v`` enables more detailed output while
+keeping the configuration of the selected logging mode. The logging mode
+continues to control formatting, handlers, and filters; the -v flags only adjust
+the minimum log level.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 15 85
+
+    - - Flag
+      - Effect
+    - - (none)
+      - Uses the default logging level defined by the active logging mode.
+    - - ``-v``
+      - Increases verbosity by one level (for example from ``ERROR`` to
+        ``WARNING``).
+    - - ``-vv``
+      - Increases verbosity by two levels (for example from ``ERROR`` to
+        ``INFO``).
+    - - ``-vvv``
+      - Increases verbosity by three levels (for example from ``ERROR`` to
+        ``DEBUG``).