sink/docs/logging.md

0001 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 analyze 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.
0002
0003 ## Requirements
0004 * runtime configurability of debug level for specific components
0005 * queriable debug logs. If everything is turned on, a *lot* of information will be generated.
0006 * 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.
0007 * debug information *must* be available in release builds
0008 * 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.
0009 * Ideally little interaction with stdout (i.e. only warnings). Proper monitoring should happen through:
0010     * logfiles
0011     * a commandline monitor tool
0012     * some other developer tool
0013 This way we get complete logs also if some resource was not started from the console (i.e. because it was already running).
0014
0015 ## Debug levels
0016 * trace: trace individual codepaths. Likely outputs way to much information for all normal cases and likely is only ever temporarily enabled for certain areas.
0017 * log: Comprehensive debug output. Enabled on demand
0018 * warning: Only warnings, should always be logged.
0019 * error: Critical messages that should never appear. Should always be logged.
0020
0021 ## Debug areas and components
0022 Debug areas and components split the code into sections that can be enabled/disabled as one. This gives finer grained control over what is logged or displayed.
0023
0024 Debug areas are the static part, that typically represent a class or file, but give no information about which runtime-component is executing the given code.
0025
0026 Components are the runtime information part that can represent i.e. the resource plugin in the client process or the resource process itself.
0027
0028 The full debugging area is then assembled as: "Component.Area"
0029
0030 This can result in identifiers like:
0031
0032 * $RESOURCE_IDENTIFIER.sync.performance
0033 * $RESOURCE_IDENTIFIER.sync
0034 * $RESOURCE_IDENTIFIER.communication
0035 * $RESOURCE_IDENTIFIER.pipeline
0036 * kube.$RESOURCE_IDENTIFIER.communication
0037 * kube.$RESOURCE_IDENTIFIER.queryrunner
0038 * kube.actions
0039
0040 ## Logging guidelines
0041 * The trace log level should be used for any information that is not continuously required.
0042 * Messages on the Log level should scale. During a sync with 10k messages we don't want 10k messages on the log level, these should go to trace.
0043
0044 ## Collected information
0045 Additionally to the regular message we want:
0046
0047 * pid
0048 * threadid?
0049 * timestamp
0050 * sourcefile + position + function name
0051 * application name / resource identifier
0052 * area (i.e. resource access)