Collecting Quentier logs for troubleshooting

As contribution guide mentions, in order to make it easy to troubleshoot any bug, one should provide the application's log collected while reproducing the issue. This document explains how exactly the log can be collected.

Quentier's logging system is actually a part of libquentier, the application's core library. There are several logging levels of different importance:

1. Error - the log level for most serious errors which indicate something went so wrong the application most probably won't be able to continue its work in a reasonable manner
2. Warn - the log level for unexpected events which most probably indicate some logical flaws within the app's implementation; but, unlike with error log level, the app can most probably recover itself from such unexpected event.
3. Info - the log level for notable events including important user actions and the kinds of errors which are not fatal for the app and which are most likely not caused by the app's logical flaws but by something else - environment, user error etc.
4. Debug - the log level for non-heavy messages useful primarily for troubleshooting i.e. for tracing the execution path of the app which leads to some bug.
5. Trace - one more log level serving the troubleshooting purposes, the difference from "Debug" is that within "Trace" level more detailed logging is performed - for example, if whole note content needs to be printed into the log, "Trace" would most likely be the appropriate log level.

By default "Debug" and "Trace" log level messages are not persisted i.e. they are simply skipped when the app is running. That allows the app work sufficiently faster than otherwise. If some issue has already happened while "Debug" or "Trace" logs were not enabled, higher level logs were persisted nevertheless so with luck they'd be enough to figure out the root cause of the problem. However, if they won't be enough, it'd be most useful to reproduce the issue (i.e. trigger it to happen again by doing the same thing as before) while having "Debug" or "Trace" logs enabled.

In order to collect the log for troubleshooting you need to:

1. Enable "Debug" or "Trace" log level manually before reproducing the bug
2. Reproduce the bug
3. Provide the collected logs as part of the bug report

Note that the collected logs might contain information from your notes, notebooks etc. If you care about keeping this information private, you'd need to remove it from the collected log manually before posting it. However, in most cases it's better to reproduce the issue with some non-private note/notebook/tag/etc as by manually tinkering with the collected log you might accidentally remove the information vital for further troubleshooting.

Here's the easy way to collect the trace level log of Quentier:

1. Open the log viewer

You'd see the following window:

2. Press "Trace" button in the right bottom part of the window - it would go into the pressed state with its name changed to "Stop tracing" + most part of the window's layout would be greyed out:

3. Now return to Quentier's main window and do whatever you need to do to reproduce the occurring bug.
4. Once the issue is reproduced, go back to the log viewer window. Now you need to either copy the collected log to the clipboard by pressing "Copy all to clipboard" button or to save the collected log to some file (which can later be attached to the bug report) by pressing "Save to file..." button. Once that is done, press "Stop tracing" button. Congratulations, you finished collecting the log required for troubleshooting!

If you had any logs collected before the current session, you might notice that pressing "Trace" button makes it disappear from the log viewer window. That's because "Trace" button each time creates a separate "logging session" for the convenience of collecting the log starting from some particular moment and in order to avoid including any old logs into the currently collected ones. Similar effect might be achieved by pressing "Clear" button in the left bottom corner of the log viewer window: the old logs would be hidden. Pressing that button would make "Reset" button clickable - that button undoes the effects of "Clear" i.e. pressing it would unhide all the existing logs.

Unfortunately, the above described simple technique has limitations: logs collection into the log viewer's window currently consumes quite a lot of memory and if, for example, you'd like to catch into trace-level logs the entire synchronization of your huge Evernote account, that would most likely result in Quentier app crashing due to the lack of memory. That might be corrected in future but for such heavy enough operations which need to be logged slightly different approach needs to be taken:

1. First you'd need to get rid of any existing logs. If you still need them, back them up before proceeding. Quentier's logs are stored in the following locations depending on the platform:

• ~/.quentier/logs-quentier on Linux
• ~/Library/Application Support/quentier.org/Quentier/logs-quentier on Mac
• C:\Users\%USERNAME%\AppData\Roaming\Quentier\logs-quentier on Windows

There might be several log files there - they are automatically rotated. It's important to clear the contents of Quentier-log.txt file or just to remove it, it would be recreated then. If you don't need to back up any previous logs, it's easy to get rid of them from the log viewer window: just press "Wipe" button in the upper part of the window.

2. Change the current log level to "Trace" or "Debug" via "Log level" combo box. Note that enabling any of these log levels might sufficiently slow Quentier down, especially when it's data is stored on HDD, not SSD. So you might notice that with "Trace" level logs Quentier is not responsive enough to reproduce the bug. In this case stick to "Debug" log level, it should help a bit.
3. Close the log viewer window to prevent it from consuming too much memory during reproducing the issue.
4. Reproduce the original issue.
5. Attach Quentier-log.txt file to the bug report.