1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qloggingcategory.h"
5#include "qloggingregistry_p.h"
6
7QT_BEGIN_NAMESPACE
8
9const char qtDefaultCategoryName[] = "default";
10Q_GLOBAL_STATIC(QLoggingCategory, qtDefaultCategory, qtDefaultCategoryName)
11
12/*!
13 \class QLoggingCategory
14 \inmodule QtCore
15 \since 5.2
16 \threadsafe
17
18 \brief The QLoggingCategory class represents a category, or 'area' in the
19 logging infrastructure.
20
21 QLoggingCategory represents a certain logging category - identified by a
22 string - at runtime. A category can be configured to enable or disable
23 logging of messages per message type. An exception are fatal messages,
24 which are always enabled.
25
26 To check whether a message type is enabled or not, use one of these methods:
27 \l isDebugEnabled(), \l isInfoEnabled(), \l isWarningEnabled(), and
28 \l isCriticalEnabled().
29
30 All objects are meant to be configured by a common registry, as described in
31 \l{Configuring Categories}. Different objects can also represent the same
32 category. Therefore, it's \b{not} recommended to export objects across
33 module boundaries, to manipulate the objects directly, or to inherit from
34 QLoggingCategory.
35
36 \section1 Creating Category Objects
37
38 The Q_DECLARE_LOGGING_CATEGORY() and Q_LOGGING_CATEGORY() macros
39 conveniently declare and create QLoggingCategory objects:
40
41 \snippet qloggingcategory/main.cpp 1
42
43 There is also the Q_DECLARE_EXPORTED_LOGGING_CATEGORY() macro in
44 order to use a logging category across library boundaries.
45
46 Category names are free text; to configure categories using \l{Logging Rules}, their
47 names should follow this convention:
48 \list
49 \li Use letters and numbers only.
50 \li Use dots to further structure categories into common areas.
51 \li Avoid the category names: \c{debug}, \c{info}, \c{warning}, and \c{critical}.
52 \li Category names with the \c{qt} prefix are solely reserved for Qt modules.
53 \endlist
54
55 QLoggingCategory objects that are implicitly defined by Q_LOGGING_CATEGORY()
56 are created on first use, in a thread-safe manner.
57
58 \section1 Checking Category Configuration
59
60 QLoggingCategory provides \l isDebugEnabled(), \l isInfoEnabled(),
61 \l isWarningEnabled(), \l isCriticalEnabled(), as well as \l isEnabled()
62 to check whether messages for the given message type should be logged.
63
64 The qCDebug(), qCWarning(), and qCCritical() macros prevent arguments from
65 being evaluated if the respective message types are not enabled for the
66 category, so explicit checking is not needed:
67
68 \snippet qloggingcategory/main.cpp 4
69
70 \section1 Default Category Configuration
71
72 Both the QLoggingCategory constructor and the Q_LOGGING_CATEGORY() macro
73 accept an optional QtMsgType argument, which disables all message types with
74 a lower severity. That is, a category declared with
75
76 \snippet qloggingcategory/main.cpp 5
77
78 logs messages of type \c QtWarningMsg, \c QtCriticalMsg, \c QtFatalMsg, but
79 ignores messages of type \c QtDebugMsg and \c QtInfoMsg.
80
81 If no argument is passed, all messages are logged. Only Qt internal categories
82 which start with \c{qt} are handled differently: For these, only messages of type
83 \c QtInfoMsg, \c QtWarningMsg, \c QtCriticalMsg, and \c QFatalMsg are logged by default.
84
85 \note Logging categories are not affected by your C++ build configuration.
86 That is, whether messages are printed does not change depending on whether
87 the code is compiled with debug symbols ('Debug Build'), optimizations
88 ('Release Build'), or some other combination.
89
90 \section1 Configuring Categories
91
92 You can override the default configuration for categories either by setting
93 logging rules, or by installing a custom filter.
94
95 \section2 Logging Rules
96
97 Logging rules let you enable or disable logging for categories in a flexible
98 way. Rules are specified in text, where every line must have the format:
99
100 \snippet code/src_corelib_io_qloggingcategory.cpp 0
101
102 \c <category> is the name of the category, potentially with \c{*} as a
103 wildcard symbol for the first or last character; or at both positions.
104 The optional \c <type> must be \c debug, \c info, \c warning, or \c critical.
105 Lines that don't fit this scheme are ignored.
106
107 Rules are evaluated in text order, from first to last. That is, if two rules
108 apply to a category/type, the rule that comes later is applied.
109
110 Rules can be set via \l setFilterRules():
111
112 \snippet code/src_corelib_io_qloggingcategory.cpp 1
113
114 Logging rules are automatically loaded from the \c [Rules] section in a logging
115 configuration file. These configuration files are looked up in the QtProject
116 configuration directory, or explicitly set in a \c QT_LOGGING_CONF environment
117 variable:
118
119 \snippet code/src_corelib_io_qloggingcategory.cpp 2
120
121 Logging rules can also be specified in a \c QT_LOGGING_RULES environment variable;
122 multiple rules can also be separated by semicolons:
123
124 \snippet code/src_corelib_io_qloggingcategory.cpp 3
125
126 Rules set by \l setFilterRules() take precedence over rules specified in the
127 QtProject configuration directory. In turn, these rules can be overwritten by those
128 from the configuration file specified by \c QT_LOGGING_CONF, and those set by
129 \c QT_LOGGING_RULES.
130
131 The order of evaluation is as follows:
132 \list 1
133 \li [QLibraryInfo::DataPath]/qtlogging.ini
134 \li QtProject/qtlogging.ini
135 \li \l setFilterRules()
136 \li \c QT_LOGGING_CONF
137 \li \c QT_LOGGING_RULES
138 \endlist
139
140 The \c QtProject/qtlogging.ini file is looked up in all directories returned
141 by QStandardPaths::GenericConfigLocation.
142
143 Set the \c QT_LOGGING_DEBUG environment variable to find out where your logging
144 rules are loaded from.
145
146 \section2 Installing a Custom Filter
147
148 As a lower-level alternative to the text rules, you can also implement a
149 custom filter via \l installFilter(). All filter rules are ignored in this
150 case.
151
152 \section1 Printing the Category
153
154 Use the \c %{category} placeholder to print the category in the default
155 message handler:
156
157 \snippet qloggingcategory/main.cpp 3
158*/
159
160/*!
161 Constructs a QLoggingCategory object with the provided \a category name,
162 and enables all messages with types at least as verbose as \a enableForLevel,
163 which defaults to QtDebugMsg (which enables all categories).
164
165 If \a category is \nullptr, the category name \c "default" is used.
166
167 \note \a category must be kept valid during the lifetime of this object.
168 Using a string literal for it is the usual way to achieve this.
169
170 \since 5.4
171*/
172QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel)
173 : d(nullptr),
174 name(nullptr)
175{
176 init(category, severityLevel: enableForLevel);
177}
178
179void QLoggingCategory::init(const char *category, QtMsgType severityLevel)
180{
181 enabled.storeRelaxed(newValue: 0x01010101); // enabledDebug = enabledWarning = enabledCritical = true;
182
183 if (category)
184 name = category;
185 else
186 name = qtDefaultCategoryName;
187
188 if (QLoggingRegistry *reg = QLoggingRegistry::instance())
189 reg->registerCategory(category: this, enableForLevel: severityLevel);
190}
191
192/*!
193 Destroys a QLoggingCategory object.
194*/
195QLoggingCategory::~QLoggingCategory()
196{
197 if (QLoggingRegistry *reg = QLoggingRegistry::instance())
198 reg->unregisterCategory(category: this);
199}
200
201/*!
202 \fn const char *QLoggingCategory::categoryName() const
203
204 Returns the name of the category.
205*/
206
207/*!
208 \fn bool QLoggingCategory::isDebugEnabled() const
209
210 Returns \c true if debug messages should be shown for this category;
211 \c false otherwise.
212
213 \note The \l qCDebug() macro already does this check before running any
214 code. However, calling this method may be useful to avoid the
215 expensive generation of data for debug output only.
216*/
217
218
219/*!
220 \fn bool QLoggingCategory::isInfoEnabled() const
221
222 Returns \c true if informational messages should be shown for this category;
223 \c false otherwise.
224
225 \note The \l qCInfo() macro already does this check before executing any
226 code. However, calling this method may be useful to avoid the
227 expensive generation of data for debug output only.
228
229 \since 5.5
230*/
231
232
233/*!
234 \fn bool QLoggingCategory::isWarningEnabled() const
235
236 Returns \c true if warning messages should be shown for this category;
237 \c false otherwise.
238
239 \note The \l qCWarning() macro already does this check before executing any
240 code. However, calling this method may be useful to avoid the
241 expensive generation of data for debug output only.
242*/
243
244/*!
245 \fn bool QLoggingCategory::isCriticalEnabled() const
246
247 Returns \c true if critical messages should be shown for this category;
248 \c false otherwise.
249
250 \note The \l qCCritical() macro already does this check before executing any
251 code. However, calling this method may be useful to avoid the
252 expensive generation of data for debug output only.
253*/
254
255/*!
256 Returns \c true if a message of type \a msgtype for the category should be
257 shown; \c false otherwise.
258*/
259bool QLoggingCategory::isEnabled(QtMsgType msgtype) const
260{
261 switch (msgtype) {
262 case QtDebugMsg: return isDebugEnabled();
263 case QtInfoMsg: return isInfoEnabled();
264 case QtWarningMsg: return isWarningEnabled();
265 case QtCriticalMsg: return isCriticalEnabled();
266 case QtFatalMsg: return true;
267 }
268 return false;
269}
270
271/*!
272 Changes the message type \a type for the category to \a enable.
273
274 This method is meant for use only from inside a filter installed with
275 \l installFilter(). For an overview on how to configure categories globally,
276 see \l {Configuring Categories}.
277
278 \note \c QtFatalMsg cannot be changed; it will always remain \c true.
279*/
280void QLoggingCategory::setEnabled(QtMsgType type, bool enable)
281{
282 switch (type) {
283 case QtDebugMsg: bools.enabledDebug.storeRelaxed(newValue: enable); break;
284 case QtInfoMsg: bools.enabledInfo.storeRelaxed(newValue: enable); break;
285 case QtWarningMsg: bools.enabledWarning.storeRelaxed(newValue: enable); break;
286 case QtCriticalMsg: bools.enabledCritical.storeRelaxed(newValue: enable); break;
287 case QtFatalMsg: break;
288 }
289}
290
291/*!
292 \fn QLoggingCategory &QLoggingCategory::operator()()
293
294 Returns the object itself. This allows for both: a QLoggingCategory variable, and
295 a factory method that returns a QLoggingCategory, to be used in \l qCDebug(),
296 \l qCWarning(), \l qCCritical(), or \l qCFatal() macros.
297 */
298
299/*!
300 \fn const QLoggingCategory &QLoggingCategory::operator()() const
301
302 Returns the object itself. This allows for both: a QLoggingCategory variable, and
303 a factory method that returns a QLoggingCategory, to be used in \l qCDebug(),
304 \l qCWarning(), \l qCCritical(), or \l qCFatal() macros.
305 */
306
307/*!
308 Returns a pointer to the global category \c "default" that is used, for
309 example, by qDebug(), qInfo(), qWarning(), qCritical(), or qFatal().
310
311 \note The pointer returned may be null during destruction of static objects.
312 Also, don't \c delete this pointer, as ownership of the category isn't transferred.
313
314 */
315QLoggingCategory *QLoggingCategory::defaultCategory()
316{
317 return qtDefaultCategory();
318}
319
320/*!
321 \typedef QLoggingCategory::CategoryFilter
322
323 This is a typedef for a pointer to a function with the following signature:
324
325 \snippet qloggingcategory/main.cpp 20
326
327 A function with this signature can be installed with \l installFilter().
328*/
329
330/*!
331 \brief Take control of how logging categories are configured.
332
333 Installs a function \a filter that is used to determine which categories and
334 message types should be enabled. If \a filter is \nullptr, the default
335 message filter is reinstated. Returns a pointer to the previously-installed
336 filter.
337
338 Every QLoggingCategory object that already exists is passed to the filter
339 before \c installFilter() returns, and the filter is free to change each
340 category's configuration with \l setEnabled(). Any category it doesn't
341 change will retain the configuration it was given by the prior filter, so
342 the new filter does not need to delegate to the prior filter during this
343 initial pass over existing categories.
344
345 Any new categories added later will be passed to the new filter; a filter
346 that only aims to tweak the configuration of a select few categories, rather
347 than completely overriding the logging policy, can first pass the new
348 category to the prior filter, to give it its standard configuration, and
349 then tweak that as desired, if it is one of the categories of specific
350 interest to the filter. The code that installs the new filter can record the
351 return from \c installFilter() for the filter to use in such later calls.
352
353 When you define your filter, note that it can be called from different threads; but never
354 concurrently. This filter cannot call any static functions from QLoggingCategory.
355
356 Example:
357 \snippet qloggingcategory/main.cpp 21
358
359 installed (in \c{main()}, for example) by
360
361 \snippet qloggingcategory/main.cpp 22
362
363 Alternatively, you can configure the default filter via \l setFilterRules().
364 */
365QLoggingCategory::CategoryFilter
366QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
367{
368 return QLoggingRegistry::instance()->installFilter(filter);
369}
370
371/*!
372 Configures which categories and message types should be enabled through a
373 set of \a rules.
374
375 Example:
376
377 \snippet qloggingcategory/main.cpp 2
378
379 \note The rules might be ignored if a custom category filter is installed
380 with \l installFilter(), or if the user has defined the \c QT_LOGGING_CONF
381 or the \c QT_LOGGING_RULES environment variable.
382*/
383void QLoggingCategory::setFilterRules(const QString &rules)
384{
385 QLoggingRegistry::instance()->setApiRules(rules);
386}
387
388/*!
389 \macro qCDebug(category)
390 \relates QLoggingCategory
391 \threadsafe
392 \since 5.2
393
394 Returns an output stream for debug messages in the logging category,
395 \a category.
396
397 The macro expands to code that checks whether
398 \l QLoggingCategory::isDebugEnabled() evaluates to \c true.
399 If so, the stream arguments are processed and sent to the message handler.
400
401 Example:
402
403 \snippet qloggingcategory/main.cpp 10
404
405 \note Arguments aren't processed if the debug output for that \a category is not
406 enabled, so don't rely on any side effects.
407
408 \sa qDebug()
409*/
410
411/*!
412 \macro qCDebug(category, const char *message, ...)
413 \relates QLoggingCategory
414 \threadsafe
415 \since 5.3
416
417 Logs a debug message, \a message, in the logging category, \a category.
418 \a message may contain place holders to be replaced by additional arguments,
419 similar to the C printf() function.
420
421 Example:
422
423 \snippet qloggingcategory/main.cpp 13
424
425 \note Arguments aren't processed if the debug output for that \a category is not
426 enabled, so don't rely on any side effects.
427
428 \sa qDebug()
429*/
430
431/*!
432 \macro qCInfo(category)
433 \relates QLoggingCategory
434 \threadsafe
435 \since 5.5
436
437 Returns an output stream for informational messages in the logging category,
438 \a category.
439
440 The macro expands to code that checks whether
441 \l QLoggingCategory::isInfoEnabled() evaluates to \c true.
442 If so, the stream arguments are processed and sent to the message handler.
443
444 Example:
445
446 \snippet qloggingcategory/main.cpp qcinfo_stream
447
448 \note If the debug output for a particular category isn't enabled, arguments
449 won't be processed, so don't rely on any side effects.
450
451 \sa qInfo()
452*/
453
454/*!
455 \macro qCInfo(category, const char *message, ...)
456 \relates QLoggingCategory
457 \threadsafe
458 \since 5.5
459
460 Logs an informational message, \a message, in the logging category, \a category.
461 \a message may contain place holders to be replaced by additional arguments,
462 similar to the C printf() function.
463
464 Example:
465
466 \snippet qloggingcategory/main.cpp qcinfo_printf
467
468 \note If the debug output for a particular category isn't enabled, arguments
469 won't be processed, so don't rely on any side effects.
470
471 \sa qInfo()
472*/
473
474/*!
475 \macro qCWarning(category)
476 \relates QLoggingCategory
477 \threadsafe
478 \since 5.2
479
480 Returns an output stream for warning messages in the logging category,
481 \a category.
482
483 The macro expands to code that checks whether
484 \l QLoggingCategory::isWarningEnabled() evaluates to \c true.
485 If so, the stream arguments are processed and sent to the message handler.
486
487 Example:
488
489 \snippet qloggingcategory/main.cpp 11
490
491 \note If the warning output for a particular category isn't enabled, arguments
492 won't be processed, so don't rely on any side effects.
493
494 \sa qWarning()
495*/
496
497/*!
498 \macro qCWarning(category, const char *message, ...)
499 \relates QLoggingCategory
500 \threadsafe
501 \since 5.3
502
503 Logs a warning message, \a message, in the logging category, \a category.
504 \a message may contain place holders to be replaced by additional arguments,
505 similar to the C printf() function.
506
507 Example:
508
509 \snippet qloggingcategory/main.cpp 14
510
511 \note If the warning output for a particular category isn't enabled, arguments
512 won't be processed, so don't rely on any side effects.
513
514 \sa qWarning()
515*/
516
517/*!
518 \macro qCCritical(category)
519 \relates QLoggingCategory
520 \threadsafe
521 \since 5.2
522
523 Returns an output stream for critical messages in the logging category,
524 \a category.
525
526 The macro expands to code that checks whether
527 \l QLoggingCategory::isCriticalEnabled() evaluates to \c true.
528 If so, the stream arguments are processed and sent to the message handler.
529
530 Example:
531
532 \snippet qloggingcategory/main.cpp 12
533
534
535 \note If the critical output for a particular category isn't enabled, arguments
536 won't be processed, so don't rely on any side effects.
537
538 \sa qCritical()
539*/
540
541/*!
542 \macro qCCritical(category, const char *message, ...)
543 \relates QLoggingCategory
544 \threadsafe
545 \since 5.3
546
547 Logs a critical message, \a message, in the logging category, \a category.
548 \a message may contain place holders to be replaced by additional arguments,
549 similar to the C printf() function.
550
551 Example:
552
553 \snippet qloggingcategory/main.cpp 15
554
555 \note If the critical output for a particular category isn't enabled, arguments
556 won't be processed, so don't rely on any side effects.
557
558 \sa qCritical()
559*/
560
561/*!
562 \macro qCFatal(category)
563 \relates QLoggingCategory
564 \since 6.5
565
566 Returns an output stream for fatal messages in the logging category,
567 \a category.
568
569 If you are using the \b{default message handler}, the returned stream will abort
570 to create a core dump. On Windows, for debug builds, this function will
571 report a \c _CRT_ERROR enabling you to connect a debugger to the application.
572
573 Example:
574
575 \snippet qloggingcategory/main.cpp 16
576
577 \sa qFatal()
578*/
579
580/*!
581 \macro qCFatal(category, const char *message, ...)
582 \relates QLoggingCategory
583 \since 6.5
584
585 Logs a fatal message, \a message, in the logging category, \a category.
586 \a message may contain place holders to be replaced by additional arguments,
587 similar to the C printf() function.
588
589 Example:
590
591 \snippet qloggingcategory/main.cpp 17
592
593 If you are using the \b{default message handler}, this function will abort
594 to create a core dump. On Windows, for debug builds, this function will
595 report a \c _CRT_ERROR enabling you to connect a debugger to the application.
596
597 \sa qFatal()
598*/
599
600/*!
601 \macro Q_DECLARE_LOGGING_CATEGORY(name)
602 \sa Q_LOGGING_CATEGORY(), Q_DECLARE_EXPORTED_LOGGING_CATEGORY()
603 \relates QLoggingCategory
604 \since 5.2
605
606 Declares a logging category \a name. The macro can be used to declare
607 a common logging category shared in different parts of the program.
608
609 This macro must be used outside of a class or method.
610*/
611
612/*!
613 \macro Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, EXPORT_MACRO)
614 \sa Q_LOGGING_CATEGORY(), Q_DECLARE_LOGGING_CATEGORY()
615 \relates QLoggingCategory
616 \since 6.5
617
618 Declares a logging category \a name. The macro can be used to declare
619 a common logging category shared in different parts of the program.
620
621 This works exactly like Q_DECLARE_LOGGING_CATEGORY(). However,
622 the logging category declared by this macro is additionally
623 qualified with \a EXPORT_MACRO. This is useful if the logging
624 category needs to be exported from a dynamic library.
625
626 For example:
627
628 \code
629 Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcCore, LIB_EXPORT_MACRO)
630 \endcode
631
632 This macro must be used outside of a class or function.
633*/
634
635/*!
636 \macro Q_LOGGING_CATEGORY(name, string)
637 \sa Q_DECLARE_LOGGING_CATEGORY(), Q_DECLARE_EXPORTED_LOGGING_CATEGORY()
638 \relates QLoggingCategory
639 \since 5.2
640
641 Defines a logging category \a name, and makes it configurable under the
642 \a string identifier. By default, all message types are enabled.
643
644 Only one translation unit in a library or executable can define a category
645 with a specific name. The implicitly-defined QLoggingCategory object is
646 created on first use, in a thread-safe manner.
647
648 This macro must be used outside of a class or method.
649*/
650
651/*!
652 \macro Q_LOGGING_CATEGORY(name, string, msgType)
653 \sa Q_DECLARE_LOGGING_CATEGORY()
654 \relates QLoggingCategory
655 \since 5.4
656
657 Defines a logging category \a name, and makes it configurable under the
658 \a string identifier. By default, messages of QtMsgType \a msgType
659 and more severe are enabled, types with a lower severity are disabled.
660
661 Only one translation unit in a library or executable can define a category
662 with a specific name. The implicitly-defined QLoggingCategory object is
663 created on first use, in a thread-safe manner.
664
665 This macro must be used outside of a class or method.
666*/
667
668QT_END_NAMESPACE
669

source code of qtbase/src/corelib/io/qloggingcategory.cpp