<QtLogging> - Qt Logging Types

El fichero de cabecera <QtLogging> define los tipos, funciones y macros de registro de Qt. Más...

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 fichero de cabecera <QtLogging> contiene varios tipos, funciones y macros para el registro.

El enum QtMsgType identifica los distintos mensajes que pueden generarse y enviarse a un gestor de mensajes 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 *). qInstallMessageHandler QtMessageHandler(La clase QMessageLogContext contiene la línea, archivo y función en la que se registró el mensaje. Esta información es creada por la clase QMessageLogger.

<QtLogging> también contiene funciones que generan mensajes a partir del argumento de cadena dado: qDebug(), qInfo(), qWarning(), qCritical(), y qFatal(). Estas funciones llaman al manejador de mensajes con el mensaje dado.

Ejemplo:

if (!driver()->isOpen() || driver()->isOpenError()) {    qWarning("QSqlQuery::exec: database not open");
   return false; }

Véase también QLoggingCategory.

Documentación de tipos

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

Este enum describe los mensajes que pueden enviarse a un gestor de mensajes (QtMessageHandler). Puede utilizar el enum para identificar y asociar los distintos tipos de mensajes con las acciones apropiadas. Sus valores son, por orden de gravedad creciente

Constante	Valor	Descripción
`QtDebugMsg`	`0`	Mensaje generado por la función qDebug().
`QtInfoMsg`	`4`	Mensaje generado por la función qInfo().
`QtWarningMsg`	`1`	Mensaje generado por la función qWarning().
`QtCriticalMsg`	`2`	Mensaje generado por la función qCritical().
`QtFatalMsg`	`3`	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, str.

qFormatLogMessage devuelve un QString formateado según el patrón de mensajes actual. Puede ser utilizado por gestores de mensajes personalizados para formatear la salida de forma similar al gestor de mensajes por defecto de Qt.

La función es segura para hilos.

Véase también qInstallMessageHandler() y qSetMessagePattern().

QtMessageHandler qInstallMessageHandler(QtMessageHandler handler)

Instala un mensaje Qt handler. Devuelve un puntero al manejador de mensajes previamente instalado.

Un gestor de mensajes es una función que imprime mensajes de depuración, información, advertencia, críticos y fatales desde la infraestructura de registro de Qt. Por defecto, Qt utiliza un manejador de mensajes estándar que formatea e imprime mensajes a diferentes sumideros 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 los mensajes en el sistema de archivos.

Tenga en cuenta que Qt soporta logging categories para agrupar mensajes relacionados en categorías semánticas. Puede utilizarlas para activar o desactivar el registro por categoría y message type. Como el filtrado de categorías de registro se realiza incluso antes de que se cree un mensaje, los mensajes para tipos y categorías desactivados no llegarán al gestor de mensajes.

Un gestor de mensajes debe ser reentrant. Es decir, puede ser llamado desde diferentes hilos, en paralelo. Por lo tanto, las escrituras a sumideros comunes (como una base de datos, o un archivo) a menudo necesitan ser sincronizadas.

Qt permite enriquecer los mensajes de registro con meta-información adicional 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 manejador de mensajes sea mínimo, ya que las operaciones costosas podrían bloquear la aplicación. Además, para evitar la recursividad, cualquier mensaje de registro generado en el propio manejador de mensajes será ignorado.

El manejador de mensajes siempre debe retornar. Para fatal messages, la aplicación aborta inmediatamente después de manejar ese mensaje.

Sólo se puede instalar un manejador de mensajes a la vez, para toda la aplicación. Si había un gestor de mensajes personalizado instalado anteriormente, la función devolverá un puntero a él. Este gestor puede ser reinstalado posteriormente mediante otra llamada al método. Además, si se llama a qInstallMessageHandler(nullptr) se restaurará el manejador de mensajes por defecto.

Este es un ejemplo de un manejador de mensajes que se registra en un archivo local antes de llamar al manejador por defecto:

#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();
}

Nótese que el estándar C++ garantiza que static FILE *f se inicializa de forma segura para los hilos. También podemos esperar que fprintf() y fflush() sean thread-safe, por lo que no es necesaria ninguna otra sincronización.

Véase también QtMessageHandler, QtMsgType, qDebug(), qInfo(), qWarning(), qCritical(), qFatal(), Técnicas de depuración, y qFormatLogMessage().

void qSetMessagePattern(const QString &pattern)

Cambia la salida del manejador de mensajes por defecto.

Permite modificar la salida de qDebug(), qInfo(), qWarning(), qCritical(), y qFatal(). También se formatea la salida del registro de categorías 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 del archivo fuente
`%{message}`	El mensaje real
`%{pid}`	QCoreApplication::applicationPid()
`%{threadid}`	El ID del hilo actual en todo el sistema (si se puede obtener)
`%{threadname}`	El nombre del thread actual (si se puede obtener, o el ID del thread, desde Qt 6.10)
`%{qthreadptr}`	Un puntero al QThread actual (resultado de QThread::currentThread())
`%{type}`	"debug", "warning", "critical" o "fatal
`%{time process}`	la 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 puede determinarse (el token "boot" es literal). Si no se puede obtener el tiempo transcurrido desde el arranque, la salida es indeterminada (véase QElapsedTimer::msecsSinceReference()).
`%{time [format]}`	La hora del sistema en que se produjo el mensaje, formateada pasando `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 frames especificados por el parámetro opcional `depth` (por defecto 5), y separados por el parámetro opcional `separator` (por defecto "\|"). Esta expansión sólo está disponible en algunas plataformas: plataformas que utilizan glibc; plataformas que utilicen la cabecera `<stacktrace>` de C++23 (requiere compilar Qt en modo C++23). Dependiendo de la plataforma, hay algunas restricciones en los nombres de función impresos por esta expansión. En algunas plataformas, sólo se conocen los nombres de las funciones exportadas. Si quieres ver el nombre de cada función en tu aplicación, asegúrate de que tu aplicación está compilada y enlazada con `-rdynamic`, o un equivalente. Cuando leas backtraces, ten en cuenta que pueden faltar frames debido a la optimización de inlining o tail call.

También puede utilizar condicionales sobre el tipo del mensaje utilizando %{if-debug}, %{if-info} %{if-warning} , %{if-critical} o %{if-fatal} seguido de un %{endif}. Lo que esté dentro de %{if-*} y %{endif} sólo se imprimirá si el tipo coincide.

Por último, el texto dentro de %{if-category}... %{endif} sólo se imprime 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}"

La categoría por defecto pattern es %{if-category}%{category}: %{endif}%{message}.

Nota: En Android, el pattern por defecto es %{message} porque la categoría se usa como etiqueta ya que Android logcat tiene un campo dedicado para las categorías de registro, ver 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 cambiar en tiempo de ejecución estableciendo la variable de entorno QT_MESSAGE_PATTERN; si se llama tanto a qSetMessagePattern() como a QT_MESSAGE_PATTERN, la variable de entorno tiene prioridad.

Nota: La información de los marcadores de posición category, file, function y line sólo se registra en las compilaciones de depuración. Como alternativa, QT_MESSAGELOGCONTEXT puede definirse explícitamente. Para más información, consulte la documentación de QMessageLogContext.

Nota: El patrón de mensajes sólo se aplica al registro no estructurado, como la salida por defecto stderr. Los registros estructurados como systemd registrarán 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.

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 valores especificados en argumentos adicionales.

Por 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 enteros. Esto es similar a cómo funciona la función C printf(). Para más detalles sobre el formato, véase QString::asprintf().

Para mayor comodidad y soporte de tipos, también puede utilizar QDebug::qCritical(), que sigue el paradigma de streaming (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.

Para propósitos de depuración, a veces es conveniente dejar que el programa aborte para mensajes críticos. Esto le permite inspeccionar el volcado del núcleo, o conectar un depurador - véase también qFatal(). Para habilitar esto, establezca la variable de entorno QT_FATAL_CRITICALS a un número n. El programa termina entonces para el n-ésimo mensaje crítico. Es decir, si la variable de entorno se establece en 1, terminará en la primera llamada; si contiene el valor 10, saldrá en la décima llamada. Cualquier valor no numérico en la variable de entorno es equivalente a 1.

Nota: Esta macro es segura para hilos.

Ver 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 valores especificados en argumentos adicionales.

Por ejemplo

qDebug("Items in list: %d", myList.size());

Para mayor comodidad y soporte de tipos, también puede utilizar QDebug::qDebug(), que sigue el paradigma de flujo (similar a std::cout o std::cerr).

Esta función no hace nada si QT_NO_DEBUG_OUTPUT se definió durante la compilación.

Para suprimir la salida en tiempo de ejecución, instale su propio manejador de mensajes con qInstallMessageHandler().

Nota: Esta macro es thread-safe.

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 valores especificados en 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 está utilizando el gestor de mensajes predeterminado, esta función abortará la creación de un volcado del núcleo. En Windows, para construcciones de depuración, esta función reportará un _CRT_ERROR permitiéndole conectar un depurador a la aplicación.

Para suprimir la salida en tiempo de ejecución, instale su propio manejador 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 valores especificados en argumentos adicionales.

Por ejemplo

qInfo("Items in list: %d", myList.size());

Para mayor comodidad y soporte de tipos, también puede utilizar QDebug::qInfo(), que sigue el paradigma de flujo (similar a std::cout o std::cerr).

Esta función no hace nada si QT_NO_INFO_OUTPUT se definió durante la compilación.

Para suprimir la salida en tiempo de ejecución, instale su propio manejador de mensajes utilizando qInstallMessageHandler().

Nota: Esta macro es thread-safe.

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 valores especificados en argumentos adicionales.

Por ejemplo

void f(int c)
{
    if (c > 200)
        qWarning("f: bad argument, c == %d", c);
}

Para mayor comodidad y soporte de tipos, también puede utilizar QDebug::qWarning(), que sigue el paradigma de flujo (similar a std::cout o std::cerr).

Esta función no hace nada si QT_NO_WARNING_OUTPUT se definió durante la compilación. Para suprimir la salida en tiempo de ejecución, puede definir logging rules o registrar un filter personalizado.

Para propósitos de depuración, a veces es conveniente dejar que el programa aborte por mensajes de advertencia. Esto le permite inspeccionar el volcado del núcleo, o adjuntar un depurador - véase también qFatal(). Para habilitar esto, establezca la variable de entorno QT_FATAL_WARNINGS a un número n. El programa termina entonces para la n-ésima advertencia. Es decir, si la variable de entorno se establece en 1, terminará en la primera llamada; si contiene el valor 10, saldrá en la décima llamada. Cualquier valor no numérico en la variable de entorno es equivalente a 1.

Nota: Esta macro es segura para hilos.

Ver 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.

<QtLogging> - Qt Logging Types

Tipos

Funciones

Macros

Descripción detallada

Documentación de tipos

QtMessageHandler

enum QtMsgType

Documentación de la función

QString qFormatLogMessage(QtMsgType type, const QMessageLogContext &context, const QString &str)

QtMessageHandler qInstallMessageHandler(QtMessageHandler handler)

void qSetMessagePattern(const QString &pattern)

Documentación de macros

qCritical(const char *format, ...)

qDebug(const char *format, ...)

qFatal(const char *format, ...)

qInfo(const char *format, ...)

qWarning(const char *format, ...)

qCritical(const char **format*, ...)

qDebug(const char **format*, ...)

qFatal(const char **format*, ...)

qInfo(const char **format*, ...)

qWarning(const char **format*, ...)