qLog - Categorized Logging
Qt Extended provides the qLog(CategoryIdentifier) function for categorized logging, built on top of the QDebug class in Qt for Embedded Linux.
The following is an example of using a log message in the source code:
#include <qtopialog.h>
qLog(Type) << "Test";
qLog(Type) << "string=" << str << ", int=" << i;
where Type is a category as defined in qtopialog-config.h.
The categories are declared by using one of the following macros:
- QLOG_DISABLE(CategoryIdentifier) - no logging code is generated.
- QLOG_ENABLE(CategoryIdentifier) - logging code is always generated and invoked.
- QTOPIA_LOG_OPTION(CategoryIdentifier) - logging code is always generated, invoked depending on the settings in the Log.conf settings file.
- QLOG_OPTION(CategoryIdentifier,expr) - logging code is always generated, invoked if expr is true at the time the log is issued, expr may be cached.
- QLOG_OPTION_VOLATILE(CategoryIdentifier,expr) - as above, but expr is not cached.
The CategoryIdentifier has _QLog appended within the macros, so it can be any identifier you choose. The associated type name might be a useful choice:
qLog(QWidget) << "Created" << name;
For categories declared with QTOPIA_LOG_OPTION, the output of logging depends on the Log settings. As with all Qt Extended settings files, the defaults are found in:
/opt/Qtopia/etc/default/Trolltech/Log.conf
and these are overridden by settings in:
$HOME/Settings/Trolltech/Log.conf
For example, the following enables logging messages related to the user interface:
[UI]
Enabled = 1
Name[] = User interface
Help[] = Anything to do with the user interface.
Note: Changes to Log.conf are not reflected in running applications immediately. A QCop message (QPE/System LogConfChanged()) can be sent which will cause all applications to re-read Log.conf and re-process the categories created with QTOPIA_LOG_OPTION.
To assist field testing, there is a Logging Settings application that uses the logread program to interface with the BusyBox syslogd output. To forward the output to syslogd, use the logger program:
- Start the syslog daemon in circular buffer mode. With the command:
syslogd -C <buffersize>
For example, to start syslogd with a 512 byte circular buffer use:
syslogd -C 512
- Start Qt Extended with logging output redirected to the system log using:
qpe 2>&1 | logger -t Qtopia
- Start Logging Settings to view log messages.
- Select Categories... from the context menu to select the log messages to enable/disable. The effects are immediate for all categories created with QTOPIA_LOG_OPTION.
- Log messages can be viewed on the console by running:
logread -f
For an example of a script that uses syslogd when starting Qt Extended see <source>/devices/greenphone/src/devtools/startup/qpe.sh
Customizing Log Output
The formatting of log messages can be modified globally by setting MessageHandler/Format in the Log2 settings file. This can be used to add additional information to all logged messages suitable for log analysis tools. A C-style format string determines the output format to be used, with the following specifiers being supported:
- %s - The text of the message being logged.
- %t - A timestamp, in milliseconds, since a fixed point in the past. All processes use the same fixed point so that timestamps can be compared between processes.
- %p - The PID (process identifier) of the current process.
- %n - The name of the current process as returned by QCoreApplication::applicationName(), or if a QCoreApplication has not yet been created, the filename of the process's executable.
For example, if $HOME/Settings/Trolltech/Log2.conf contains the following text:
[MessageHandler]
Format = %t %p %n: %s
Log messages will be formatted as in the following example:
| Code | Output |
|---|
| qLog(UI) << "Creating main user interface"; | 212 18755 myapp: UI : Creating main user interface |
| MainWindow win; | |
| qLog(UI) << "Done creating main user interface"; | 320 18755 myapp: UI : Done creating main user interface |
As with changes to the qLog categories, sending the QPE/System LogConfChanged() QCop message is necessary for changes to log formatting to take effect in running applications.
References
