diff options
Diffstat (limited to 'docs/logging.md')
| -rw-r--r-- | docs/logging.md | 26 |
1 files changed, 26 insertions, 0 deletions
diff --git a/docs/logging.md b/docs/logging.md new file mode 100644 index 0000000..a88bc0f --- /dev/null +++ b/docs/logging.md | |||
| @@ -0,0 +1,26 @@ | |||
| 1 | For debugging purposes a logging framework is required. Simple qDebugs() proved to be insufficient for any non-trivial software. Developers should be enabled to add detailed debug information that allows to analize problems, and users should be enabled to record that information at runtime to debug a problem. The aim is to get away from the situation where developers remove messages because "it's to noisy", and then have to ship a special version with additional debug output to a user to debug a problem, just to then remove the debug output again. | ||
| 2 | |||
| 3 | ## Requirements | ||
| 4 | * runtime configurability of debug level for specific components | ||
| 5 | * queriable debug logs. If everything is turned on a *lot* of information will be generated. | ||
| 6 | * integration with the system log. It likely makes sense to integrate with the system-log instead of rolling our own solution or use .xsession-errors as dumping ground. In any case, simply logging to the console is not enough. | ||
| 7 | * debug information *must* be available in release builds | ||
| 8 | * It may make sense to be able to disable certain debug output (configurable per debug level) for certain components at compile time, for performance reasons. | ||
| 9 | * Ideally little interaction with stdout (i.e. only warnings). Proper monitoring should happen through: | ||
| 10 | * logfiles | ||
| 11 | * a commandline monitor tool | ||
| 12 | * akonadiconsole | ||
| 13 | |||
| 14 | ## Debug levels | ||
| 15 | * trace: trace individual codepaths. Likely outputs way to many information for all normal cases and likely is only ever temporarily enabled. Trace points are likely only inserted into code fragments that are known to be problematic. | ||
| 16 | * debug: Comprehensive debug output. Enabled on demand | ||
| 17 | * warning: Only warnings, should always be logged. | ||
| 18 | * error: Critical messages that should never appear. Should always be logged. | ||
| 19 | |||
| 20 | ## Collected information | ||
| 21 | Additionally to the regular message we want: | ||
| 22 | * pid | ||
| 23 | * threadid? | ||
| 24 | * timestamp | ||
| 25 | * sourcefile + position + function name | ||
| 26 | * application name | ||