QLoggingCategory Class

The QLoggingCategory class represents a category, or 'area' in the logging infrastructure. More...

• List of all members, including inherited members

Note: All functions in this class are thread-safe.

Public Types

Public Functions

Static Public Members

Macros

Detailed Description

The QLoggingCategory class represents a category, or 'area' in the logging infrastructure.

QLoggingCategory represents a certain logging category - identified by a string - at runtime. A category can be configured to enable or disable logging of messages per message type. Whether a message type is enabled or not can be checked with the isDebugEnabled(), isInfoEnabled(), isWarningEnabled(), and isCriticalEnabled() methods.

All objects are meant to be configured by a common registry (see also Configuring Categories). Different objects can also represent the same category. It is therefore not recommended to export objects across module boundaries, nor to manipulate the objects directly, nor to inherit from QLoggingCategory.

Creating Category Objects

The Q_DECLARE_LOGGING_CATEGORY() and Q_LOGGING_CATEGORY() macros conveniently declare and create QLoggingCategory objects:

// in a header
Q_DECLARE_LOGGING_CATEGORY(driverUsb)

// in one source file
Q_LOGGING_CATEGORY(driverUsb, "driver.usb")

Note: Category names are free text. However, to allow easy configuration of the categories using Logging Rules the names should follow some rules:

• Use letters and numbers only.
• Further structure categories into common areas by using dots.
• Avoid the category names debug, info, warning, and critical.
• Category names starting with qt are reserved for Qt modules.

QLoggingCategory objects implicitly defined by Q_LOGGING_CATEGORY() are created on first use in a thread-safe manner.

Checking Category Configuration

QLoggingCategory provides isDebugEnabled(), isInfoEnabled(), isWarningEnabled(), isCriticalEnabled(), as well as isEnabled() to check whether messages for the given message type should be logged.

Note: The qCDebug(), qCWarning(), qCCritical() macros prevent arguments from being evaluated if the respective message types are not enabled for the category, so explicit checking is not needed:

    // usbEntries() will only be called if driverUsb category is enabled
    qCDebug(driverUsb) << "devices: " << usbEntries();

Default Category Configuration

Both the QLoggingCategory constructor and the Q_LOGGING_CATEGORY() macro accept an optional QtMsgType argument, which disables all message types with a lower severity. That is, a category declared with

Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)

will log messages of type QtWarningMsg, QtCriticalMsg, QtFatalMsg, but will ignore messages of type QtDebugMsg and QtInfoMsg.

If no argument is passed, all messages will be logged.

Configuring Categories

The default configuration of categories can be overridden either by setting logging rules, or by installing a custom filter.

Logging Rules

Logging rules allow logging for categories to be enabled or disabled in a flexible way. Rules are specified in text, where every line must have the format

    <category>[.<type>] = true|false

<category> is the name of the category, potentially with * as a wildcard symbol as the first or last character (or at both positions). The optional <type> must be either debug, info, warning, or critical. Lines that do not fit this scheme are ignored.

Rules are evaluated in text order, from first to last. That is, if two rules apply to a category/type, the rule that comes later is applied.

Rules can be set via setFilterRules():

    QLoggingCategory::setFilterRules("*.debug=false\n"
                                     "driver.usb.debug=true");

Since Qt 5.3, logging rules are also automatically loaded from the [Rules] section of a logging configuration file. Such configuration files are looked up in the QtProject configuration directory, or explicitly set in a QT_LOGGING_CONF environment variable:

    [Rules]
    *.debug=false
    driver.usb.debug=true

Since Qt 5.3, logging rules can also be specified in a QT_LOGGING_RULES environment variable. And since Qt 5.6, multiple rules can also be separated by semicolons:

    QT_LOGGING_RULES="*.debug=false;driver.usb.debug=true"

Rules set by setFilterRules() take precedence over rules specified in the QtProject configuration directory, and can, in turn, be overwritten by rules from the configuration file specified by QT_LOGGING_CONF, and rules set by QT_LOGGING_RULES.

Order of evaluation:

• [QLibraryInfo::DataPath]/qtlogging.ini
• QtProject/qtlogging.ini
• setFilterRules()
• QT_LOGGING_CONF
• QT_LOGGING_RULES

The QtProject/qtlogging.ini file is looked up in all directories returned by QStandardPaths::GenericConfigLocation, e.g.

• on macOS and iOS: ~/Library/Preferences
• on Unix: ~/.config, /etc/xdg
• on Windows: %LOCALAPPDATA%, %ProgramData%, QCoreApplication::applicationDirPath(), QCoreApplication::applicationDirPath() + "/data"

Set the QT_LOGGING_DEBUG environment variable to see from where logging rules are loaded.

Installing a Custom Filter

As a lower-level alternative to the text rules, you can also implement a custom filter via installFilter(). All filter rules are ignored in this case.

Printing the Category

Use the %{category} placeholder to print the category in the default message handler:

    qSetMessagePattern("%{category} %{message}");

Member Type Documentation

typedef QLoggingCategory::CategoryFilter

This is a typedef for a pointer to a function with the following signature:

void myCategoryFilter(QLoggingCategory *);

A function with this signature can be installed with installFilter().

Member Function Documentation

QLoggingCategory::QLoggingCategory(const char *category)

Constructs a QLoggingCategory object with the provided category name. All message types for this category are enabled by default.

If category is 0, the category name is changed to "default".

Note that category must be kept valid during the lifetime of this object.

QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel)

Constructs a QLoggingCategory object with the provided category name, and enables all messages with types more severe or equal than enableForLevel.

If category is 0, the category name is changed to "default".

Note that category must be kept valid during the lifetime of this object.

This function was introduced in Qt 5.4.

QLoggingCategory::~QLoggingCategory()

Destructs a QLoggingCategory object.

const char *QLoggingCategory::categoryName() const

Returns the name of the category.

[static] QLoggingCategory *QLoggingCategory::defaultCategory()

Returns a pointer to the global category "default" that is used e.g. by qDebug(), qInfo(), qWarning(), qCritical(), qFatal().

Note: The returned pointer may be null during destruction of static objects.

Note: Ownership of the category is not transferred, do not delete the returned pointer.

[static] QLoggingCategory::CategoryFilter QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)

Installs a function filter that is used to determine which categories and message types should be enabled. Returns a pointer to the previous installed filter.

Every QLoggingCategory object created is passed to the filter, and the filter is free to change the respective category configuration with setEnabled().

The filter might be called from different threads, but never concurrently. The filter shall not call any static functions of QLoggingCategory.

Example:

QLoggingCategory::CategoryFilter oldCategoryFilter;

void myCategoryFilter(QLoggingCategory *category)
{
    // configure driver.usb category here, otherwise forward to to default filter.
    if (qstrcmp(category->categoryName(), "driver.usb") == 0)
        category->setEnabled(QtDebugMsg, true);
    else
        oldCategoryFilter(category);
}

An alternative way of configuring the default filter is via setFilterRules().

bool QLoggingCategory::isCriticalEnabled() const

Returns true if critical messages should be shown for this category. Returns false otherwise.

Note: The qCCritical() macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.

bool QLoggingCategory::isDebugEnabled() const

Returns true if debug messages should be shown for this category. Returns false otherwise.

Note: The qCDebug() macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.

bool QLoggingCategory::isEnabled(QtMsgType msgtype) const

Returns true if a message of type msgtype for the category should be shown. Returns false otherwise.

bool QLoggingCategory::isInfoEnabled() const

Returns true if informational messages should be shown for this category. Returns false otherwise.

Note: The qCInfo() macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.

This function was introduced in Qt 5.5.

bool QLoggingCategory::isWarningEnabled() const

Returns true if warning messages should be shown for this category. Returns false otherwise.

Note: The qCWarning() macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.

void QLoggingCategory::setEnabled(QtMsgType type, bool enable)

Changes the message type type for the category to enable.

This method is meant to be used only from inside a filter installed by installFilter(). See Configuring Categories for an overview on how to configure categories globally.

Note: QtFatalMsg cannot be changed. It will always remain true.

See also isEnabled().

[static] void QLoggingCategory::setFilterRules(const QString &rules)

Configures which categories and message types should be enabled through a a set of rules.

Example:

    QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));

Note: The rules might be ignored if a custom category filter is installed with installFilter(), or if the user defined QT_LOGGING_CONF or QT_LOGGING_RULES environment variable.

QLoggingCategory &QLoggingCategory::operator()()

Returns the object itself. This allows both a QLoggingCategory variable, and a factory method returning a QLoggingCategory, to be used in qCDebug(), qCWarning(), qCCritical() macros.

const QLoggingCategory &QLoggingCategory::operator()() const

Returns the object itself. This allows both a QLoggingCategory variable, and a factory method returning a QLoggingCategory, to be used in qCDebug(), qCWarning(), qCCritical() macros.

    QLoggingCategory category("driver.usb");
    qCCritical(category) << "a critical message";

    QLoggingCategory category("driver.usb");
    qCCritical(category, "a critical message logged into category %s", category.categoryName());

    QLoggingCategory category("driver.usb");
    qCDebug(category) << "a debug message";

    QLoggingCategory category("driver.usb");
    qCDebug(category, "a debug message logged into category %s", category.categoryName());

    QLoggingCategory category("driver.usb");
    qCInfo(category) << "an informational message";

    QLoggingCategory category("driver.usb");
    qCInfo(category, "an informational message logged into category %s", category.categoryName());

    QLoggingCategory category("driver.usb");
    qCWarning(category) << "a warning message";

    QLoggingCategory category("driver.usb");
    qCWarning(category, "a warning message logged into category %s", category.categoryName());