The <QtLogging> header file defines Qt logging types, functions and macros. 更多...
头: | #include <QtLogging> |
QtMessageHandler | |
enum | QtMsgType { QtDebugMsg, QtInfoMsg, QtWarningMsg, QtCriticalMsg, QtFatalMsg } |
QString | qFormatLogMessage (QtMsgType type , const QMessageLogContext & context , const QString & str ) |
QtMessageHandler | qInstallMessageHandler (QtMessageHandler handler ) |
void | qSetMessagePattern (const QString & pattern ) |
qCritical (const char * message , ...) | |
qDebug (const char * message , ...) | |
qFatal (const char * message , ...) | |
qInfo (const char * message , ...) | |
qWarning (const char * message , ...) |
The <QtLogging> header file contains several types, functions and macros for logging.
The
QtMsgType
enum identifies the various messages that can be generated and sent to a Qt message handler;
QtMessageHandler
is a type definition for a pointer to a function with the signature
void myMessageHandler(QtMsgType, const QMessageLogContext &, const char *)
.
qInstallMessageHandler
() function can be used to install the given
QtMessageHandler
.
QMessageLogContext
class contains the line, file, and function the message was logged at. This information is created by the
QMessageLogger
类。
<QtLogging> also contains functions that generate messages from the given string argument: qDebug (), qInfo (), qWarning (), qCritical (),和 qFatal (). These functions call the message handler with the given message.
范例:
if (!driver()->isOpen() || driver()->isOpenError()) { qWarning("QSqlQuery::exec: database not open"); return false; }
这是采用以下签名的函数指针的 typedef:
void myMessageHandler(QtMsgType, const QMessageLogContext &, const QString &);
另请参阅 QtMsgType and qInstallMessageHandler ().
This enum describes the messages that can be sent to a message handler ( QtMessageHandler ). You can use the enum to identify and associate the various message types with the appropriate actions. Its values are, in order of increasing severity:
常量 | 值 | 描述 |
---|---|---|
QtDebugMsg
|
0
|
消息的生成通过 qDebug () 函数。 |
QtInfoMsg
|
4
|
消息的生成通过 qInfo () 函数。 |
QtWarningMsg
|
1
|
消息的生成通过 qWarning () 函数。 |
QtCriticalMsg
|
2
|
消息的生成通过 qCritical () 函数。 |
QtFatalMsg
|
3
|
消息的生成通过 qFatal () 函数。 |
另请参阅 QtMessageHandler and qInstallMessageHandler ().
Generates a formatted string out of the type , context , str 自变量。
qFormatLogMessage returns a QString that is formatted according to the current message pattern. It can be used by custom message handlers to format output similar to Qt's default message handler.
The function is thread-safe.
另请参阅 qInstallMessageHandler () 和 qSetMessagePattern ().
Installs a Qt message handler . Returns a pointer to the previously installed message handler.
A message handler is a function that prints out debug, info, warning, critical, and fatal messages from Qt's logging infrastructure. By default, Qt uses a standard message handler that formats and prints messages to different sinks specific to the operating system and Qt configuration. Installing your own message handler allows you to assume full control, and for instance log messages to the file system.
Note that Qt supports 日志类别 for grouping related messages in semantic categories. You can use these to enable or disable logging per category and message type . As the filtering for logging categories is done even before a message is created, messages for disabled types and categories will not reach the message handler.
A message handler needs to be 可重入 . That is, it might be called from different threads, in parallel. Therefore, writes to common sinks (like a database, or a file) often need to be synchronized.
Qt allows to enrich logging messages with further meta-information by calling
qSetMessagePattern
(), or setting the
QT_MESSAGE_PATTERN
environment variable. To keep this formatting, a custom message handler can use
qFormatLogMessage
().
Try to keep the code in the message handler itself minimal, as expensive operations might block the application. Also, to avoid recursion, any logging messages generated in the message handler itself will be ignored.
The message handler should always return. For fatal messages , the application aborts immediately after handling that message.
Only one message handler can be installed at a time, for the whole application. If there was a previous custom message handler installed, the function will return a pointer to it. This handler can then be later reinstalled by another call to the method. Also, calling
qInstallMessageHandler(nullptr)
will restore the default message handler.
Here is an example of a message handler that logs to a local file before calling the default handler:
#include <QApplication> #include <stdio.h> #include <stdlib.h> QtMessageHandler originalHandler = nullptr; void logToFile(QtMsgType type, const QMessageLogContext &context, const QString &msg) { QString message = qFormatLogMessage(type, context, msg); static FILE *f = fopen("log.txt", "a"); fprintf(f, "%s\n", qPrintable(message)); fflush(f); if (originalHandler) *originalHandler(type, context, msg); } int main(int argc, char **argv) { originalHandler = qInstallMessageHandler(logToFile); QApplication app(argc, argv); ... return app.exec(); }
Note that the C++ standard guarantees that
static FILE *f
is initialized in a thread-safe way. We can also expect
fprintf()
and
fflush()
to be thread-safe, so no further synchronization is necessary.
另请参阅 QtMessageHandler , QtMsgType , qDebug (), qInfo (), qWarning (), qCritical (), qFatal (), 调试技术 ,和 qFormatLogMessage ().
Changes the output of the default message handler.
Allows to tweak the output of qDebug (), qInfo (), qWarning (), qCritical (),和 qFatal (). The category logging output of qCDebug (), qCInfo (), qCWarning (),和 qCCritical () is formatted, too.
Following placeholders are supported:
Placeholder | 描述 |
---|---|
%{appname}
|
QCoreApplication::applicationName () |
%{category}
|
Logging category |
%{file}
|
Path to source file |
%{function}
|
函数 |
%{line}
|
Line in source file |
%{message}
|
The actual message |
%{pid}
|
QCoreApplication::applicationPid () |
%{threadid}
|
The system-wide ID of current thread (if it can be obtained) |
%{qthreadptr}
|
A pointer to the current QThread (result of QThread::currentThread ()) |
%{type}
|
"debug", "warning", "critical" or "fatal" |
%{time process}
|
time of the message, in seconds since the process started (the token "process" is literal) |
%{time boot}
|
the time of the message, in seconds since the system boot if that can be determined (the token "boot" is literal). If the time since boot could not be obtained, the output is indeterminate (see QElapsedTimer::msecsSinceReference ()). |
%{time [format]}
|
system time when the message occurred, formatted by passing the
format
to
QDateTime::toString
(). If the format is not specified, the format of
Qt::ISODate
被使用。
|
%{backtrace [depth=N] [separator="..."]}
|
A backtrace with the number of frames specified by the optional
depth
parameter (defaults to 5), and separated by the optional
separator
parameter (defaults to "|").
This expansion is available only on some platforms (currently only platfoms using glibc). Names are only known for exported functions. If you want to see the name of every function in your application, make sure your application is compiled and linked with
When reading backtraces, take into account that frames might be missing due to inlining or tail call optimization. |
You can also use conditionals on the type of the message using
%{if-debug}
,
%{if-info}
%{if-warning}
,
%{if-critical}
or
%{if-fatal}
followed by an
%{endif}
. What is inside the
%{if-*}
and
%{endif}
will only be printed if the type matches.
Finally, text inside
%{if-category}
...
%{endif}
is only printed if the category is not the default one.
范例:
QT_MESSAGE_PATTERN="[%{time yyyyMMdd h:mm:ss.zzz t} %{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}] %{file}:%{line} - %{message}"
默认
pattern
is
%{if-category}%{category}: %{endif}%{message}
.
The pattern can also be changed at runtime by setting the QT_MESSAGE_PATTERN environment variable; if both qSetMessagePattern() is called and QT_MESSAGE_PATTERN is set, the environment variable takes precedence.
注意:
The information for the placeholders
category
,
file
,
function
and
line
is only recorded in debug builds. Alternatively,
QT_MESSAGELOGCONTEXT
can be defined explicitly. For more information refer to the
QMessageLogContext
文档编制。
注意:
The message pattern only applies to unstructured logging, such as the default
stderr
output. Structured logging such as systemd will record the message as is, along with as much structured information as can be captured.
Custom message handlers can use qFormatLogMessage () to take pattern into account.
另请参阅 qInstallMessageHandler (), 调试技术 , QLoggingCategory ,和 QMessageLogContext .
Calls the message handler with the critical message message . If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the debugger. On QNX the message is sent to slogger2.
This function takes a format string and a list of arguments, similar to the C printf() function. The format should be a Latin-1 string.
范例:
void load(const QString &fileName) { QFile file(fileName); if (!file.exists()) qCritical("File '%s' does not exist!", qUtf8Printable(fileName)); }
If you include <QtDebug>, a more convenient syntax is also available:
qCritical() << "Brush:" << myQBrush << "Other value:" << i;
A space is inserted between the items, and a newline is appended at the end.
To suppress the output at runtime, you can define logging rules or register a custom filter .
For debugging purposes, it is sometimes convenient to let the program abort for critical messages. This allows you then to inspect the core dump, or attach a debugger - see also
qFatal
(). To enable this, set the environment variable
QT_FATAL_CRITICALS
to a number
n
. The program terminates then for the n-th critical message. That is, if the environment variable is set to 1, it will terminate on the first call; if it contains the value 10, it will exit on the 10th call. Any non-numeric value in the environment variable is equivalent to 1.
注意: This macro is thread-safe .
另请参阅 qDebug (), qInfo (), qWarning (), qFatal (), qInstallMessageHandler (),和 调试技术 .
Calls the message handler with the debug message
message
. If no message handler has been installed, the message is printed to stderr. Under Windows the message is sent to the console, if it is a console application; otherwise, it is sent to the debugger. On QNX, the message is sent to slogger2. This function does nothing if
QT_NO_DEBUG_OUTPUT
was defined during compilation.
If you pass the function a format string and a list of arguments, it works in similar way to the C printf() function. The format should be a Latin-1 string.
范例:
qDebug("Items in list: %d", myList.size());
If you include
<QtDebug>
, a more convenient syntax is also available:
qDebug() << "Brush:" << myQBrush << "Other value:" << i;
采用此句法,函数返回 QDebug object that is configured to use the QtDebugMsg message type. It automatically puts a single space between each item, and outputs a newline at the end. It supports many C++ and Qt types.
To suppress the output at runtime, install your own message handler with qInstallMessageHandler ().
注意: This macro is thread-safe .
另请参阅 qInfo (), qWarning (), qCritical (), qFatal (), qInstallMessageHandler (),和 调试技术 .
Calls the message handler with the fatal message message . If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the debugger. On QNX the message is sent to slogger2.
若正使用 默认消息处理程序 this function will abort to create a core dump. On Windows, for debug builds, this function will report a _CRT_ERROR enabling you to connect a debugger to the application.
This function takes a format string and a list of arguments, similar to the C printf() function.
范例:
int divide(int a, int b) { if (b == 0) // program error qFatal("divide: cannot divide by zero"); return a / b; }
To suppress the output at runtime, install your own message handler with qInstallMessageHandler ().
另请参阅 qDebug (), qInfo (), qWarning (), qCritical (), qInstallMessageHandler (),和 调试技术 .
Calls the message handler with the informational message
message
. If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the console, if it is a console application; otherwise, it is sent to the debugger. On QNX the message is sent to slogger2. This function does nothing if
QT_NO_INFO_OUTPUT
was defined during compilation.
If you pass the function a format string and a list of arguments, it works in similar way to the C printf() function. The format should be a Latin-1 string.
范例:
qInfo("Items in list: %d", myList.size());
If you include
<QtDebug>
, a more convenient syntax is also available:
qInfo() << "Brush:" << myQBrush << "Other value:" << i;
采用此句法,函数返回 QDebug object that is configured to use the QtInfoMsg message type. It automatically puts a single space between each item, and outputs a newline at the end. It supports many C++ and Qt types.
To suppress the output at runtime, install your own message handler using qInstallMessageHandler ().
注意: This macro is thread-safe .
另请参阅 qDebug (), qWarning (), qCritical (), qFatal (), qInstallMessageHandler (),和 调试技术 .
调用消息处理程序采用警告消息 message . If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the debugger. On QNX the message is sent to slogger2.
This function takes a format string and a list of arguments, similar to the C printf() function. The format should be a Latin-1 string.
范例:
void f(int c) { if (c > 200) qWarning("f: bad argument, c == %d", c); }
If you include <QtDebug>, a more convenient syntax is also available:
qWarning() << "Brush:" << myQBrush << "Other value:" << i;
This syntax inserts a space between each item, and appends a newline at the end.
此函数什么都不做,若
QT_NO_WARNING_OUTPUT
was defined during compilation. To suppress the output at runtime, you can set
logging rules
or register a custom
filter
.
For debugging purposes, it is sometimes convenient to let the program abort for warning messages. This allows you then to inspect the core dump, or attach a debugger - see also
qFatal
(). To enable this, set the environment variable
QT_FATAL_WARNINGS
to a number
n
. The program terminates then for the n-th warning. That is, if the environment variable is set to 1, it will terminate on the first call; if it contains the value 10, it will exit on the 10th call. Any non-numeric value in the environment variable is equivalent to 1.
注意: This macro is thread-safe .
另请参阅 qDebug (), qInfo (), qCritical (), qFatal (), qInstallMessageHandler (),和 调试技术 .