<QtLogging> - Qt Logging Types
El archivo de cabecera <QtLogging> define los tipos, las funciones y las macros de registro de Qt. Más información...
| Header: | #include <QtLogging> |
Tipos
| QtMessageHandler | |
| enum | QtMsgType { QtDebugMsg, QtInfoMsg, QtWarningMsg, QtCriticalMsg, QtFatalMsg } |
Funciones
| QString | qFormatLogMessage(QtMsgType type, const QMessageLogContext &context, const QString &str) |
| QtMessageHandler | qInstallMessageHandler(QtMessageHandler handler) |
| void | qSetMessagePattern(const QString &pattern) |
Macros
| qCritical(const char *format, ...) | |
| qDebug(const char *format, ...) | |
| qFatal(const char *format, ...) | |
| qInfo(const char *format, ...) | |
| qWarning(const char *format, ...) |
Descripción detallada
El archivo de cabecera <QtLogging> contiene varios tipos, funciones y macros para el registro de eventos.
La enumeración ` QtMsgType ` identifica los distintos mensajes que se pueden generar y enviar a un gestor de mensajes de Qt; ` QtMessageHandler ` es una definición de tipo para un puntero a una función con la firma ` void myMessageHandler(QtMsgType, const QMessageLogContext &, const char *)`. La función ` qInstallMessageHandler()` se puede utilizar para instalar el ` QtMessageHandler` indicado. La clase ` QMessageLogContext ` contiene la línea, el archivo y la función en los que se registró el mensaje. Esta información la genera la clase ` QMessageLogger `.
<QtLogging> también contiene funciones que generan mensajes a partir del argumento de cadena proporcionado: ` qDebug()`, ` qInfo()`, ` qWarning()`, ` qCritical()` y ` qFatal()`. Estas funciones llaman al gestor de mensajes con el mensaje proporcionado.
Ejemplo:
if (!driver()->isOpen()|| driver()->isOpenError()) {
qWarning("QSqlQuery::exec: database not open");
return false;
}Véase también QLoggingCategory.
Documentación del tipo
QtMessageHandler
Se trata de un `typedef` para un puntero a una función con la siguiente firma:
void myMessageHandler(QtMsgType, const QMessageLogContext &, const QString &);Véase también QtMsgType y qInstallMessageHandler().
enum QtMsgType
Esta enumeración describe los mensajes que se pueden enviar a un gestor de mensajes (QtMessageHandler). Puedes utilizar la enumeración para identificar y asociar los distintos tipos de mensajes con las acciones adecuadas. Sus valores son, en orden creciente de gravedad:
| Constante | Valor | Descripción |
|---|---|---|
QtDebugMsg | 0 | Un mensaje generado por la función qDebug(). |
QtInfoMsg | 4 | Un mensaje generado por la función qInfo(). |
QtWarningMsg | 1 | Un mensaje generado por la función qWarning(). |
QtCriticalMsg | 2 | Un mensaje generado por la función qCritical(). |
QtFatalMsg | 3 | Un mensaje generado por la función qFatal(). |
Véase también QtMessageHandler, qInstallMessageHandler() y QLoggingCategory.
Documentación de la función
QString qFormatLogMessage(QtMsgType type, const QMessageLogContext &context, const QString &str)
Genera una cadena formateada a partir de los argumentos type, context y str.
qFormatLogMessage devuelve un objeto ` QString ` formateado según el patrón de mensaje actual. Los gestores de mensajes personalizados pueden utilizarlo para dar formato a la salida de forma similar al gestor de mensajes predeterminado de Qt.
La función es segura para subprocesos.
Véase también qInstallMessageHandler() y qSetMessagePattern().
QtMessageHandler qInstallMessageHandler(QtMessageHandler handler)
Instala un gestionador de mensajes de Qt handler. Devuelve un puntero al gest instalado anteriormente.
Un gestor de mensajes es una función que muestra mensajes de depuración, información, advertencia, críticos y fatales procedentes de la infraestructura de registro de Qt. Por defecto, Qt utiliza un gestor de mensajes estándar que da formato a los mensajes y los envía a diferentes destinos específicos del sistema operativo y de la configuración de Qt. Instalar tu propio gestor de mensajes te permite asumir el control total y, por ejemplo, registrar mensajes en el sistema de archivos.
Ten en cuenta que Qt admite logging categories para agrupar mensajes relacionados en categorías semánticas. Puedes utilizarlas para habilitar o deshabilitar el registro por categoría y message type. Dado que el filtrado de las categorías de registro se realiza incluso antes de que se cree un mensaje, los mensajes de los tipos y categorías deshabilitados no llegarán al gestor de mensajes.
Un gestor de mensajes debe ser « reentrant ». Es decir, puede ser invocado desde diferentes subprocesos, en paralelo. Por lo tanto, las operaciones de escritura en destinos comunes (como una base de datos o un archivo) suelen necesitar sincronización.
Qt permite enriquecer los mensajes de registro con más metainformación llamando a ` qSetMessagePattern()` o estableciendo la variable de entorno ` QT_MESSAGE_PATTERN `. Para mantener este formato, un gestor de mensajes personalizado puede utilizar ` qFormatLogMessage()`.
Intenta que el código del propio gestor de mensajes sea lo más breve posible, ya que las operaciones que consumen muchos recursos podrían bloquear la aplicación. Además, para evitar la recursividad, se ignorarán los mensajes de registro generados en el propio gestor de mensajes.
El gestor de mensajes siempre debe devolver un valor. En el caso de ` fatal messages`, la aplicación se interrumpe inmediatamente tras gestionar ese mensaje.
Solo se puede instalar un gestor de mensajes a la vez para toda la aplicación. Si había instalado previamente un gestor de mensajes personalizado, la función devolverá un puntero a él. Este gestor se podrá reinstalar más tarde mediante otra llamada al método. Además, al llamar a ` qInstallMessageHandler(nullptr) ` se restablecerá el gestor de mensajes predeterminado.
A continuación se muestra un ejemplo de un gestor de mensajes que registra la información en un archivo local antes de llamar al gestor predeterminado:
#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();
}Ten en cuenta que el estándar de C++ garantiza que ` static FILE *f ` se inicializa de forma segura para subprocesos. También podemos dar por hecho que ` fprintf() ` y ` fflush() ` son seguras para subprocesos, por lo que no es necesaria ninguna sincronización adicional.
Véase también QtMessageHandler, QtMsgType, qDebug(), qInfo(), qWarning(), qCritical(), qFatal(), «Técnicas de depuración» y qFormatLogMessage().
void qSetMessagePattern(const QString &pattern)
Modifica la salida del gestor de mensajes predeterminado.
Permite ajustar la salida de qDebug(), qInfo(), qWarning(), qCritical() y qFatal(). También se formatea la salida de registro de categoría de qCDebug(), qCInfo(), qCWarning() y qCCritical().
Se admiten los siguientes marcadores de posición:
| Marcador de posición | Descripción |
|---|---|
%{appname} | QCoreApplication::applicationName() |
%{category} | Categoría de registro |
%{file} | Ruta al archivo fuente |
%{function} | Función |
%{line} | Línea en el archivo fuente |
%{message} | El mensaje real |
%{pid} | QCoreApplication::applicationPid() |
%{threadid} | El identificador del hilo actual a nivel del sistema (si se puede obtener) |
%{threadname} | El nombre del hilo actual (si se puede obtener, o el ID del hilo, desde Qt 6.10) |
%{qthreadptr} | Un puntero al objeto « QThread » actual (resultado de QThread::currentThread()) |
%{type} | «debug», «warning», «critical» o «fatal» |
%{time process} | hora del mensaje, en segundos desde que se inició el proceso (el token «process» es literal) |
%{time boot} | la hora del mensaje, en segundos desde el arranque del sistema, si es posible determinarla (el token «boot» es literal). Si no se ha podido obtener el tiempo transcurrido desde el arranque, el resultado es indeterminado (véase QElapsedTimer::msecsSinceReference()). |
%{time [format]} | hora del sistema en la que se produjo el mensaje, formateada pasando el format a QDateTime::toString(). Si no se especifica el formato, se utiliza el formato de Qt::ISODate. |
%{backtrace [depth=N] [separator="..."]} | Un backtrace con el número de tramas especificado por el parámetro opcional depth (por defecto, 5), y separadas por el parámetro opcional separator (por defecto, «|»). A partir de Qt 6.12, el número máximo de tramas depth está limitado a 16 384.Esta ampliación solo está disponible en algunas plataformas:
Dependiendo de la plataforma, existen algunas restricciones en los nombres de las funciones que muestra esta expansión. En algunas plataformas, solo se conocen los nombres de las funciones exportadas. Si quieres ver el nombre de todas las funciones de tu aplicación, asegúrate de que esta se compile y se enlace con Al leer los trazas de pila, ten en cuenta que pueden faltar marcos debido a la optimización de llamadas en línea o a la optimización de llamadas de cola. |
También puedes utilizar condiciones basadas en el tipo del mensaje mediante %{if-debug}, %{if-info}, %{if-warning}, %{if-critical} o %{if-fatal}, seguidas de un %{endif}. El contenido de %{if-*} y %{endif} solo se mostrará si el tipo coincide.
Por último, el texto que aparece en %{if-category}... %{endif} solo se muestra si la categoría no es la predeterminada.
Ejemplo:
QT_MESSAGE_PATTERN="[%{time yyyyMMdd h:mm:ss.zzz ttt} %{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}] %{file}:%{line} - %{message}"El « pattern » predeterminado es %{if-category}%{category}: %{endif}%{message}.
Nota: En Android, el « pattern » predeterminado es %{message}, ya que la categoría se utiliza como etiqueta, dado que el logcat de Android dispone de un campo específico para las categorías de registro; véase «Registro en Android». Si se utiliza un « pattern » personalizado que incluya la categoría, se utiliza QCoreApplication::applicationName() como etiqueta.
El pattern también se puede modificar en tiempo de ejecución configurando la variable de entorno QT_MESSAGE_PATTERN; si se llama a qSetMessagePattern() y se ha configurado QT_MESSAGE_PATTERN, la variable de entorno tiene prioridad.
Nota: La información relativa a los marcadores de posición category, file, function y line solo se registra en compilaciones de depuración. Como alternativa, se puede definir explícitamente QT_MESSAGELOGCONTEXT. Para obtener más información, consulte la documentación de QMessageLogContext.
Nota: El patrón de mensaje solo se aplica al registro no estructurado, como la salida predeterminada de stderr. El registro estructurado, como el de systemd, registrará el mensaje tal cual, junto con toda la información estructurada que se pueda capturar.
Los gestores de mensajes personalizados pueden utilizar ` qFormatLogMessage()` para tener en cuenta ` pattern `.
Consideraciones de seguridad
Qt no elimina ni escapa los caracteres de control de ` pattern `, incluidos ` LF`, ` CR`, los bytes ` NUL ` y las secuencias de control de terminal. Por lo tanto, aceptar un patrón procedente de una fuente no fiable permite la falsificación de registros o el envío de secuencias de control al consumidor del flujo de registro. Además, en algunos backends de registro, los mensajes pueden truncarse en el byte ` NUL `, si lo hay.
Véase también qInstallMessageHandler(), Técnicas de depuración, QLoggingCategory y QMessageLogContext.
Documentación de macros
qCritical(const char *format, ...)
Registra el mensaje crítico « format » en el gestor central de mensajes. « format » puede contener especificadores de formato que se sustituyen por los valores indicados en argumentos adicionales.
Ejemplo:
void load(const QString &fileName)
{
QFile file(fileName);
if (!file.exists())
qCritical("File '%s' does not exist!", qUtf8Printable(fileName));
}format puede contener especificadores de formato como %s para cadenas UTF-8, o %i para números enteros. Esto es similar al funcionamiento de la función C printf(). Para obtener más detalles sobre el formateo, consulta QString::asprintf().
Para mayor comodidad y compatibilidad con más tipos, también puede utilizar QDebug::qCritical(), que sigue el paradigma de flujo (similar a std::cout o std::cerr).
Para suprimir la salida en tiempo de ejecución, puede definir logging rules o registrar un filter personalizado.
A efectos de depuración, a veces resulta conveniente que el programa se interrumpa ante mensajes críticos. Esto permite inspeccionar el volcado de memoria o conectar un depurador; véase también qFatal(). Para habilitar esta opción, establezca la variable de entorno QT_FATAL_CRITICALS en un número n. El programa se detendrá entonces ante el enésimo mensaje crítico. Es decir, si la variable de entorno se establece en 1, el programa terminará en la primera llamada; si contiene el valor 10, se cerrará en la décima llamada. Cualquier valor no numérico en la variable de entorno equivale a 1.
Nota: Esta macro es segura para subprocesos.
Véase también QDebug::qCritical, qCCritical(), qDebug(), qInfo(), qWarning(), qFatal(), qInstallMessageHandler() y «Técnicas de depuración».
qDebug(const char *format, ...)
Registra el mensaje de depuración « format » en el gestor central de mensajes. « format » puede contener especificadores de formato que se sustituyen por los valores indicados en argumentos adicionales.
Ejemplo:
qDebug("Items in list: %d", myList.size());format puede contener especificadores de formato como %s para cadenas UTF-8, o %i para números enteros. Esto es similar al funcionamiento de la función C ` printf() `. Para obtener más detalles sobre el formato, consulta QString::asprintf().
Para mayor comodidad y compatibilidad con más tipos, también se puede utilizar QDebug::qDebug(), que sigue el paradigma de flujo (similar a std::cout o std::cerr).
Esta función no hace nada si se ha definido QT_NO_DEBUG_OUTPUT durante la compilación.
Para suprimir la salida en tiempo de ejecución, instale su propio gestor de mensajes con qInstallMessageHandler().
Nota: Esta macro es segura para subprocesos.
Véase también QDebug::qDebug(), qCDebug(), qInfo(), qWarning(), qCritical(), qFatal(), qInstallMessageHandler() y «Técnicas de depuración».
qFatal(const char *format, ...)
Registra el mensaje fatal « format » en el gestor central de mensajes. « format » puede contener especificadores de formato que se sustituyen por los valores indicados en los argumentos adicionales.
Ejemplo:
int divide_by_zero(int a, int b)
{
if (b == 0) // program error
qFatal("divide: cannot divide by zero");
return a / b;
}Si utilizas el gestor de mensajes predeterminado, esta función se interrumpirá para crear un volcado de memoria. En Windows, para compilaciones de depuración, esta función informará de un _CRT_ERROR, lo que te permitirá conectar un depurador a la aplicación.
Para suprimir la salida en tiempo de ejecución, instala tu propio gestor de mensajes con qInstallMessageHandler().
Véase también qCFatal(), qDebug(), qInfo(), qWarning(), qCritical(), qInstallMessageHandler() y Técnicas de depuración.
qInfo(const char *format, ...)
Registra el mensaje informativo « format » en el gestor central de mensajes. « format » puede contener especificadores de formato que se sustituyen por los valores indicados en argumentos adicionales.
Ejemplo:
qInfo("Items in list: %d", myList.size());format puede contener especificadores de formato como %s para cadenas UTF-8, o %i para números enteros. Esto es similar al funcionamiento de la función C printf(). Para obtener más detalles sobre el formateo, consulta QString::asprintf().
Para mayor comodidad y compatibilidad con más tipos, también se puede utilizar QDebug::qInfo(), que sigue el paradigma de flujo (similar a std::cout o std::cerr).
Esta función no realiza ninguna acción si se ha definido QT_NO_INFO_OUTPUT durante la compilación.
Para suprimir la salida en tiempo de ejecución, instala tu propio gestor de mensajes utilizando qInstallMessageHandler().
Nota: Esta macro es segura para subprocesos.
Véase también QDebug::qInfo(), qCInfo(), qDebug(), qWarning(), qCritical(), qFatal(), qInstallMessageHandler() y «Técnicas de depuración».
qWarning(const char *format, ...)
Registra el mensaje de advertencia « format » en el gestor central de mensajes. « format » puede contener especificadores de formato que se sustituyen por los valores indicados en argumentos adicionales.
Ejemplo:
void f(int c)
{
if (c > 200)
qWarning("f: bad argument, c == %d", c);
}format puede contener especificadores de formato como %s para cadenas UTF-8, o %i para números enteros. Esto es similar al funcionamiento de la función C printf(). Para obtener más detalles sobre el formateo, consulta QString::asprintf().
Para mayor comodidad y compatibilidad con más tipos, también puedes utilizar QDebug::qWarning(), que sigue el paradigma de streaming (similar a std::cout o std::cerr).
Esta función no realiza ninguna acción si se ha definido QT_NO_WARNING_OUTPUT durante la compilación. Para suprimir la salida en tiempo de ejecución, puede establecer logging rules o registrar un filter personalizado.
A efectos de depuración, a veces resulta conveniente que el programa se interrumpa ante mensajes de advertencia. Esto permite inspeccionar el volcado de memoria o conectar un depurador; véase también qFatal(). Para habilitar esto, establezca la variable de entorno QT_FATAL_WARNINGS en un número n. El programa se terminará entonces tras la enésima advertencia. Es decir, si la variable de entorno se establece en 1, el programa se terminará en la primera llamada; si contiene el valor 10, se terminará en la décima llamada. Cualquier valor no numérico en la variable de entorno equivale a 1.
Nota: Esta macro es segura para subprocesos.
Véase también QDebug::qWarning(), qCWarning(), qDebug(), qInfo(), qCritical(), qFatal(), qInstallMessageHandler() y Técnicas de depuración.
© 2026 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.