Log files provide a way to track exactly what is going on in a Python plugin or script, by creating messages that are available even if the script or QGIS crashes. These log messages make troubleshooting easier. In this recipe, we'll demonstrate two methods used for logging. One method is using actual log files on the filesystem, and the other is using the QGIS Log Messages window, which is available by clicking on the yellow triangle with an exclamation point at the bottom-right corner of the QGIS application window, or by selecting View menu, then clicking on Panels, and then checking Log Messages.
To use log files, we must configure the QGIS_LOG_FILE environment variable by performing the following steps so that QGIS knows where to write log messages:
- From the QGIS Settings menu, select Options.
- In the Options dialog, select System panel.
- In the System panel, scroll down to the Environment section.
- In the Environment section, check the Use custom variables checkbox.
- Click on the Add button.
- In the Variable field, enter
QGIS_LOG_FILE. - In the Value field, enter
/qgis_data/log.txtor the path to another directory where you have write permissions. - Click on the OK button to close the Options dialog.
- Restart QGIS for the environment variable to take effect.
We will write a message to our custom log file configured in the previous section, and then write a message to the tabbed QGIS Log Messages window. To do this, we need to perform the following steps:
- First, open the Python Console in QGIS.
- Next, we'll write the following log file message:
QgsLogger.logMessageToFile("This is a message to a log file.") - Then, we'll write a message to the QGIS Log Messages window, specifying the message as the first argument and a name for the tab in which the message will appear:
QgsMessageLog.logMessage("This is a message from the Python Console", "Python Console") - Now, open the log file and check whether the message has appeared.
- Finally, open the QGIS Log Messages window, click on the Python Console tab, and verify that the second log message appears.
The traditional log file provides a simple and portable way to record information from QGIS using Python. The Log Messages window is a more structured way to view information from many different sources, with a tabbed interface and a convenient timestamp on each message. In most cases, you'll probably want to use the Log Messages window because QGIS users are familiar with it. However, use it sparingly. It's OK to log lots of messages when testing code, but restrict logging for plugins or applications to serious errors only. Heavy logging — for example, logging messages while looping over every feature in a layer — can slow down QGIS or even cause it to crash.