Logging#

By default, pymmcore-plus logs to the console at the INFO level and to a logfile in the pymmcore-plus application data directory at the DEBUG level. The logfile is named pymmcore_plus.log and is rotated at 40MB, with a maximum retention of 20 logfiles.

Customizing logging#

The pymmcore_plus.configure_logging function allows you to customize the log level, logfile name, and logfile rotation settings.

You may also configure logging using the following environment variables:

Variable	Default	Description
PYMM_LOG_LEVEL	INFO	The log level.
PYMM_LOG_FILE	`pymmcore_plus.log` in the pymmcore-plus log directory	The logfile location.

pymmcore-plus log directory

The application data directory is platform-dependent. Here are the log folders for each supported platform:

OS	Path
macOS	~/Library/Application Support/pymmcore-plus/logs
Unix	~/.local/share/pymmcore-plus/logs
Win	C:\Users\username\AppData\Local\pymmcore-plus\pymmcore-plus\logs

You can also use mmcore logs --reveal to open the log directory in your file manager.

Note that both pymmcore-plus and the underlying CMMCore object will write to the log file. By default, CMMCorePlus will call setPrimaryLogFile() with the location of the pymmcore-plus logfile upon instantiation.

Managing logs with the CLI#

The mmcore CLI provides a logs subcommand for managing logs.

$ mmcore logs --help
[1m                                                                            [0m
[1m [0m[1;33mUsage: [0m[1mmmcore logs [OPTIONS][0m[1m                                              [0m[1m [0m
[1m                                                                            [0m
 Display recent output from pymmcore-plus log.                              

[2m╭─[0m[2m Options [0m[2m───────────────────────────────────────────────────────────────[0m[2m─╮[0m
[2m│[0m [1;36m-[0m[1;36m-num[0m     [1;32m-n[0m      [1;33mINTEGER[0m  Number of lines to display. [2m[default: None][0m   [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-tail[0m    [1;32m-t[0m      [1;33m       [0m  Continually stream logs.                      [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-clear[0m   [1;32m-c[0m      [1;33m       [0m  Delete all log files.                         [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-reveal[0m          [1;33m       [0m  Reveal log file in Explorer/Finder.           [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-help[0m            [1;33m       [0m  Show this message and exit.                   [2m│[0m
[2m╰──────────────────────────────────────────────────────────────────────────╯[0m

A particularly useful command is mmcore logs --tail, which will continually stream the current logfile to the console. This can be started in another process and left running to monitor an experiment in progress.

To delete all logfiles, use mmcore logs --clear.