Skip to main content
`Ctrl`+`K`

# Logging

Each plugin object has a `_log` attribute, which behaves like a logger from the standard Python logging module but is provided by beets’ `BeetsLogger` class. The logger is set up to PEP 3101, str.format-style string formatting. So you can write logging calls like this:

    self._log.debug("Processing {0.title} by {0.artist}", item)

For especially noisy diagnostics, plugins can use `self._log.extra_debug(...)`. These messages are logged at `DEBUG` level only when beets is run with verbosity level 3 or higher, such as `-vvv`.

When beets is in verbose mode, plugin messages are prefixed with the plugin name to make them easier to see.

Which messages will be logged depends on the logging level and the action performed:

- Inside import stages and event handlers, the default is `WARNING` messages and above.

- Everywhere else, the default is `INFO` or above.

The verbosity can be increased with `--verbose` (`-v`) flags: each flags lowers the level by a notch. That means that, with a single `-v` flag, event handlers won’t have their `DEBUG` messages displayed, but command functions (for example) will. With `-vv` on the command line, `DEBUG` messages will be displayed everywhere.

This addresses a common pattern where plugins need to use the same code for a command and an import stage, but the command needs to print more messages than the import stage. (For example, you’ll want to log “found lyrics for this song” when you’re run explicitly as a command, but you don’t want to noisily interrupt the importer interface when running automatically.)