Logging and Debugging
The application manager installs its own message handler to format logging output neatly. If the QtDltLogging module is available, this message handler passes the output to GENIVI Diagnostic Log and Trace (DLT).
The application manager defines the following logging categories:
|DLT Context ID
|General system messages
|Installer sub-system messages
|OpenGL/UI related messages
|Wayland related messages
|General QML related messages
|QML runtime messages
|Notification sub-system messages
|Intent sub-system messages
|Cache sub-system messages
|Used for DLT logging only and enabled by default. Categories that have no context ID mapping in DLT default to
GEN; this includes uncategorized logging.
This is a (incomplete) list of environment variables that influence the logging output at runtime:
|If set to
1, debug output is not redirected to DLT, colorized or nicely formatted.
|If set to
1, debug output is not redirected to DLT.
|If set to
1, a startup performance analysis is printed to the console. Anything other than
1 is interpreted as the name of a file to use, instead of the console. For more information, see StartupTimer.
|Can be set to
on to force color output to the console or to
off to disable it. Any other value enables the default, auto-detection behavior.
|An integer factor that slows down all timed wait statements within the application manager. Useful if running in slow wrappers, such as Valgrind. The default value is
|Setting this variable has the same effect as described in Debugging Techniques and overwrites the default application manager message handler. Parallel DLT logging is still supported, if available.
When debugging the application manager, the System UI and applications are dependent on the mode in which the application manager runs:
- In single-process mode, you can start the
appmanbinary using any debugging tool directly, for example,
gdb --args appman -c config.yaml. Since everything runs in a single process, you can't debug applications separately. Instead, all applications started are loaded into a single process, so you can only debug the entire process at once; not each application independently.
- In multi-process mode, you have to distinguish between debugging the application manager itself or the System UI and debugging individual applications: The application manager and System UI can be debugged in the same way as for a single-process setup above. Debugging is a bit more tricky for applications, as they have to be started by the application manager. You can accomplish this by running the application through a debug wrapper which describes how to start an application using your favorite debugging tool.
To enable QML Debugging or QML Profiling in the application manager or an application, start it with the
--qml-debug argument. For more information, see QML Debugging Infrastructure.
Note: Although the concept is called "debug" wrappers, these wrappers are not limited to debugging tasks only. They are also useful for various other tasks that involve running the application under test through a wrapper, like profiling tools.
When it comes to debugging via
gdbserver specifically, you might also want to have a look at the debugging documentation in the QtCreator manual.
If you need to use
gdbserver (to debug apps in multi-process mode, or to debug the appman process itself), check out the chapter about remote debugging.
This is a (incomplete) list of environment variables that influence debugging at runtime:
|If set to
1, no crash handler is installed. Use this, if the application manager's crash handler is interfering with other debugging tools you are using.
There are three ways to start applications using debug wrappers - all of them rely on a common way to specify which debug wrapper to use:
- Within your System UI, use
debugApplicationto start an application, instead of
ApplicationManager.debugApplication("io.qt.app", "/usr/bin/strace -f")
- Via D-Bus, you can call the debugApplication method:
qdbus io.qt.ApplicationManager /ApplicationManager debugApplication "gdbserver :5555" io.qt.app
- Using the
appman-controllerwhich uses D-Bus internally, but is able to find the correct bus automatically and supports standard-IO redirection:
appman-controller debug-application -ioe "valgrind --tool=helgrind" io.qt.app
-eparameters redirect the respective IO streams (
stderr) to the calling terminal.
Note: To use the D-Bus options, the application manager has to be connected to either a session- or system-bus; don't run it with
The debug wrapper specification has to be a single argument string, that is interpreted as a command line. If this string contains the
%program% sub-string, it is replaced with the full path to the application's executable (or the
appman-launcher-qml binary for QML applications). The same thing happens for
%arguments%, which is replaced with potential command line arguments for the application. If you don't specify
%arguments%, they are appended to the resulting command line.
This means that all of these debug wrappers are essentially the same:
appman-controller debug-application "gdbserver :5555 %program% %arguments%" io.qt.music appman-controller debug-application "gdbserver :5555 %program%" io.qt.music appman-controller debug-application "gdbserver :5555" io.qt.music
appman-controller debug-application "%program% -qmljsdebugger=port:1234,block %arguments%" io.qt.browser
You can also specify environment variables for the debug wrapper - just like on the command line. This command runs your application through
strace while also setting the
WAYLAND_DEBUG environment variable to
appman-controller debug-application "WAYLAND_DEBUG=1 strace -f" io.qt.browser
For added convenience, you can even set environment variables only, without any actual debug wrapper, to debug imports and plugin loading in a QML application:
appman-controller debug-application "QT_DEBUG_PLUGINS=1 QML_IMPORT_TRACE=1" io.qt.browser
When using complex debug wrappers on the command line often, it's advisable to create aliases or wrapper scripts.
© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.