<QtLogging> - Qt Logging Types

<QtLogging> 헤더 파일은 Qt 로깅 유형, 함수 및 매크로를 정의합니다. 더 보기...

Header: #include <QtLogging>

Types

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, ...)

자세한 설명

<QtLogging> 헤더 파일에는 로깅을 위한 여러 유형, 함수 및 매크로가 포함되어 있습니다.

QtMsgType 열거형은 생성되어 Qt 메시지 핸들러로 전송될 수 있는 다양한 메시지를 식별합니다; QtMessageHandler 은 서명이 void myMessageHandler(QtMsgType, const QMessageLogContext &, const char *) 인 함수에 대한 포인터에 대한 형 정의입니다. qInstallMessageHandler() 함수는 주어진 QtMessageHandler 을 설치하는 데 사용할 수 있습니다. QMessageLogContext 클래스는 메시지가 로깅된 줄, 파일 및 함수를 포함합니다. 이 정보는 QMessageLogger 클래스에 의해 생성됩니다.

<QtLogging>에는 지정된 문자열 인자로부터 메시지를 생성하는 함수 qDebug(), qInfo(), qWarning(), qCritical(), qFatal()도 포함되어 있습니다. 이러한 함수는 주어진 메시지로 메시지 핸들러를 호출합니다.

예시:

if (!driver()->isOpen() || driver()->isOpenError()) {    qWarning("QSqlQuery::exec: database not open");
   반환 거짓; }

QLoggingCategory도 참조하세요 .

문서 유형

QtMessageHandler

다음 서명을 가진 함수에 대한 포인터에 대한 타입 정의입니다:

void myMessageHandler(QtMsgType, const QMessageLogContext &, const QString &);

QtMsgTypeqInstallMessageHandler()도 참조하세요 .

enum QtMsgType

이 열거형은 메시지 핸들러(QtMessageHandler)로 보낼 수 있는 메시지를 설명합니다. 이 열거형을 사용하여 다양한 메시지 유형을 식별하고 적절한 작업과 연결할 수 있습니다. 이 값은 심각도가 높아지는 순서대로 다음과 같습니다:

상수설명
QtDebugMsg0qDebug() 함수에 의해 생성된 메시지입니다.
QtInfoMsg4qInfo() 함수에 의해 생성된 메시지입니다.
QtWarningMsg1qWarning() 함수에 의해 생성된 메시지입니다.
QtCriticalMsg2qCritical() 함수에 의해 생성된 메시지입니다.
QtFatalMsg3qFatal() 함수에 의해 생성된 메시지입니다.

QtMessageHandler, qInstallMessageHandler() 및 QLoggingCategory참조하세요 .

함수 문서

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

type, context, str 인자로부터 형식이 지정된 문자열을 생성합니다.

qFormatLogMessage는 현재 메시지 패턴에 따라 형식이 지정된 QString 을 반환합니다. 이 함수는 사용자 정의 메시지 핸들러에서 Qt의 기본 메시지 핸들러와 유사한 출력 포맷을 지정하는 데 사용할 수 있습니다.

이 함수는 스레드 안전합니다.

qInstallMessageHandler() 및 qSetMessagePattern()도 참조하십시오 .

QtMessageHandler qInstallMessageHandler(QtMessageHandler handler)

Qt 메시지를 설치합니다 handler. 이전에 설치된 메시지 핸들러에 대한 포인터를 반환합니다.

메시지 핸들러는 Qt의 로깅 인프라에서 디버그, 정보, 경고, 치명적, 치명적인 메시지를 출력하는 함수입니다. 기본적으로 Qt는 표준 메시지 핸들러를 사용하여 운영 체제 및 Qt 구성에 따라 다른 싱크에 메시지를 포맷하고 인쇄합니다. 자체 메시지 핸들러를 설치하면 파일 시스템에 메시지를 로깅하는 등 모든 권한을 가질 수 있습니다.

Qt는 관련 메시지를 시맨틱 카테고리로 그룹화하기 위해 logging categories 을 지원합니다. 이를 사용하여 범주별 로깅과 message type 을 활성화 또는 비활성화할 수 있습니다. 로깅 범주에 대한 필터링은 메시지가 생성되기 전에도 수행되므로 비활성화된 유형 및 범주에 대한 메시지는 메시지 핸들러에 도달하지 않습니다.

메시지 핸들러는 reentrant 여야 합니다. 즉, 다른 스레드에서 병렬로 호출될 수 있습니다. 따라서 공통 싱크(예: 데이터베이스 또는 파일)에 대한 쓰기는 종종 동기화해야 합니다.

Qt에서는 qSetMessagePattern()를 호출하거나 QT_MESSAGE_PATTERN 환경 변수를 설정하여 추가 메타 정보로 로깅 메시지를 보강할 수 있습니다. 이 형식을 유지하기 위해 사용자 정의 메시지 핸들러는 qFormatLogMessage()를 사용할 수 있습니다.

메시지 처리기 자체의 코드는 비용이 많이 드는 작업으로 인해 애플리케이션이 차단될 수 있으므로 최소한으로 유지하세요. 또한 재귀를 방지하기 위해 메시지 처리기 자체에서 생성된 모든 로깅 메시지는 무시됩니다.

메시지 핸들러는 항상 반환되어야 합니다. fatal messages 의 경우 해당 메시지를 처리한 후 애플리케이션이 즉시 중단됩니다.

전체 애플리케이션에 대해 한 번에 하나의 메시지 핸들러만 설치할 수 있습니다. 이전에 설치된 사용자 지정 메시지 처리기가 있는 경우 함수는 해당 처리기에 대한 포인터를 반환합니다. 이 핸들러는 나중에 메서드를 다시 호출하여 다시 설치할 수 있습니다. 또한 qInstallMessageHandler(nullptr) 을 호출하면 기본 메시지 처리기가 복원됩니다.

다음은 기본 처리기를 호출하기 전에 로컬 파일에 로깅하는 메시지 처리기의 예입니다:

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

C++ 표준은 static FILE *f 이 스레드 안전 방식으로 초기화되도록 보장합니다. fprintf()fflush() 도 스레드 안전하므로 추가 동기화가 필요하지 않습니다.

QtMessageHandler, QtMsgType, qDebug(), qInfo(), qWarning(), qCritical(), qFatal(), 디버깅 기법qFormatLogMessage()도 참조하세요 .

void qSetMessagePattern(const QString &pattern)

기본 메시지 핸들러의 출력을 변경합니다.

qDebug(), qInfo(), qWarning(), qCritical() 및 qFatal()의 출력을 조정할 수 있습니다. qCDebug (), qCInfo(), qCWarning() 및 qCCritical()의 카테고리 로깅 출력도 서식이 지정됩니다.

지원되는 플레이스홀더는 다음과 같습니다:

플레이스홀더설명
%{appname}QCoreApplication::applicationName()
%{category}로깅 카테고리
%{file}소스 파일 경로
%{function}함수
%{line}소스 파일의 줄
%{message}실제 메시지
%{pid}QCoreApplication::applicationPid()
%{threadid}현재 스레드의 시스템 전체 ID(얻을 수 있는 경우)
%{qthreadptr}현재 QThread 에 대한 포인터( QThread::currentThread()의 결과)
%{type}"디버그", "경고", "치명적" 또는 "치명적"
%{time process}프로세스가 시작된 후 메시지 시간(초) (토큰 "프로세스"는 리터럴)
%{time boot}메시지의 시간(시스템 부팅 이후 초 단위)(확인할 수 있는 경우 "boot" 토큰은 리터럴). 부팅 이후 시간을 구할 수 없는 경우 출력은 불확정입니다( QElapsedTimer::msecsSinceReference() 참조).
%{time [format]}메시지가 발생한 시스템 시간으로, formatQDateTime::toString()에 전달하여 형식을 지정합니다. 형식을 지정하지 않으면 Qt::ISODate 형식이 사용됩니다.
%{backtrace [depth=N] [separator="..."]}선택적 depth 매개변수(기본값은 5)로 지정된 프레임 수와 선택적 separator 매개변수(기본값은 "|")로 구분된 백트레이스입니다.

이 확장 기능은 일부 플랫폼에서만 사용할 수 있습니다:

  • GLIBC를 사용하는 플랫폼
  • C++23의 <stacktrace> 헤더를 제공하는 플랫폼(C++23 모드에서 Qt를 컴파일해야 함).

플랫폼에 따라 이 확장 기능으로 인쇄되는 함수 이름에 몇 가지 제한이 있습니다.

일부 플랫폼에서는 내보낸 함수에 대해서만 이름을 알 수 있습니다. 애플리케이션의 모든 함수 이름을 확인하려면 애플리케이션을 컴파일하고 -rdynamic 또는 이와 동등한 방법으로 링크해야 합니다.

백트레이스를 읽을 때는 인라이닝 또는 테일 호출 최적화로 인해 프레임이 누락될 수 있다는 점을 고려하세요.

%{if-debug}, %{if-info} %{if-warning} , %{if-critical} 또는 %{if-fatal} 뒤에 %{endif} 를 사용하여 메시지 유형에 조건문을 사용할 수도 있습니다. %{if-*}%{endif} 안에 있는 내용은 유형이 일치하는 경우에만 인쇄됩니다.

마지막으로 %{if-category}... %{endif} 안의 텍스트는 해당 카테고리가 기본 카테고리가 아닌 경우에만 인쇄됩니다.

예:

    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%{if-category}%{category}: %{endif}%{message} 입니다.

참고: Android 로그캣에는 로깅 카테고리에 대한 전용 필드가 있으므로 카테고리가 태그로 사용되므로 Android에서 기본 pattern%{message} 입니다( Android 로깅 참조). 카테고리를 포함한 사용자 지정 pattern 을 사용하는 경우에는 QCoreApplication::applicationName()이 태그로 사용됩니다.

pattern 는 QT_MESSAGE_PATTERN 환경 변수를 설정하여 런타임에 변경할 수도 있으며, qSetMessagePattern()이 호출되고 QT_MESSAGE_PATTERN이 설정된 경우 환경 변수가 우선합니다.

참고: category, file, functionline 플레이스홀더에 대한 정보는 디버그 빌드에만 기록됩니다. 또는 QT_MESSAGELOGCONTEXT 을 명시적으로 정의할 수 있습니다. 자세한 내용은 QMessageLogContext 문서를 참조하세요.

참고: 메시지 패턴은 기본 stderr 출력과 같은 비정형 로깅에만 적용됩니다. systemd와 같은 구조화된 로깅은 캡처할 수 있는 만큼의 구조화된 정보와 함께 메시지를 있는 그대로 기록합니다.

사용자 지정 메시지 핸들러는 qFormatLogMessage()를 사용하여 pattern 을 고려할 수 있습니다.

qInstallMessageHandler(), 디버깅 기법, QLoggingCategory, 및 QMessageLogContext도 참조하세요 .

매크로 문서

qCritical(const char *message, ...)

중요 메시지 message 를 사용하여 메시지 핸들러를 호출합니다. 메시지 핸들러가 설치되어 있지 않으면 메시지가 stderr로 인쇄됩니다. Windows에서는 메시지가 디버거로 전송됩니다. QNX에서는 메시지가 slogger2로 전송됩니다.

이 함수는 C printf() 함수와 유사하게 형식 문자열과 인수 목록을 받습니다. 형식은 라틴-1 문자열이어야 합니다.

예시:

void load(const QString &fileName)
{
    QFile file(fileName);
    if (!file.exists())
        qCritical("File '%s' does not exist!", qUtf8Printable(fileName));
}

<QtDebug>를 포함하면 더 편리한 구문도 사용할 수 있습니다:

qCritical() << "Brush:" << myQBrush << "Other value:" << i;

항목 사이에 공백이 삽입되고 끝에 개행이 추가됩니다.

런타임에 출력을 억제하려면 logging rules 을 정의하거나 사용자 정의 filter 을 등록할 수 있습니다.

디버깅 목적으로 중요한 메시지에 대해 프로그램이 중단되도록 하는 것이 편리할 때가 있습니다. 이렇게 하면 코어 덤프를 검사하거나 디버거를 연결할 수 있습니다( qFatal() 참조). 이를 활성화하려면 환경 변수 QT_FATAL_CRITICALS 를 숫자로 설정하세요 n. 그러면 n번째 중요 메시지에 대해 프로그램이 종료됩니다. 즉, 환경 변수가 1로 설정되어 있으면 첫 번째 호출에서 종료되고, 값 10이 포함되어 있으면 10번째 호출에서 종료됩니다. 환경 변수에 숫자가 아닌 값은 모두 1에 해당합니다.

참고: 이 매크로는 스레드에 안전합니다.

qCCritical(), qDebug(), qInfo(), qWarning(), qFatal(), qInstallMessageHandler() 및 디버깅 기법도참조하세요 .

qDebug(const char *message, ...)

디버그 메시지 message 를 사용하여 메시지 핸들러를 호출합니다. 메시지 처리기가 설치되지 않은 경우 메시지는 stderr로 인쇄됩니다. Windows에서는 콘솔 애플리케이션인 경우 메시지가 콘솔로 전송되고, 그렇지 않으면 디버거로 전송됩니다. QNX에서는 메시지가 slogger2로 전송됩니다. 컴파일 중에 QT_NO_DEBUG_OUTPUT 이 정의된 경우 이 함수는 아무 작업도 수행하지 않습니다.

함수에 형식 문자열과 인수 목록을 전달하면 C printf() 함수와 비슷한 방식으로 작동합니다. 형식은 라틴-1 문자열이어야 합니다.

예시:

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

<QtDebug> 를 포함하면 더 편리한 구문도 사용할 수 있습니다:

qDebug() << "Brush:" << myQBrush << "Other value:" << i;

이 구문을 사용하면 QtDebugMsg 메시지 유형을 사용하도록 구성된 QDebug 객체를 반환합니다. 각 항목 사이에 자동으로 공백을 하나씩 넣고 마지막에 줄 바꿈을 출력합니다. 이 함수는 다양한 C++ 및 Qt 유형을 지원합니다.

런타임에 출력을 억제하려면 qInstallMessageHandler()를 사용하여 자체 메시지 핸들러를 설치하세요.

참고: 이 매크로는 스레드에 안전합니다.

qCDebug(), qInfo(), qWarning(), qCritical(), qFatal(), qInstallMessageHandler() 및 디버깅 기법도참조하세요 .

qFatal(const char *message, ...)

치명적인 메시지 message 를 사용하여 메시지 핸들러를 호출합니다. 메시지 핸들러가 설치되어 있지 않으면 메시지가 stderr로 인쇄됩니다. Windows에서는 메시지가 디버거로 전송됩니다. QNX에서는 메시지가 slogger2로 전송됩니다.

기본 메시지 핸들러를 사용하는 경우 이 함수는 코어 덤프를 생성하기 위해 중단됩니다. Windows에서 디버그 빌드의 경우 이 함수는 디버거를 애플리케이션에 연결할 수 있도록 _CRT_ERROR를 보고합니다.

이 함수는 C printf() 함수와 유사하게 형식 문자열과 인수 목록을 받습니다.

예제:

int divide(int a, int b)
{
    if (b == 0)                                // program error
        qFatal("divide: cannot divide by zero");
    return a / b;
}

런타임에 출력을 억제하려면 qInstallMessageHandler()를 사용하여 자체 메시지 핸들러를 설치하세요.

qCFatal(), qDebug(), qInfo(), qWarning(), qCritical(), qInstallMessageHandler() 및 디버깅 기법도참조하세요 .

qInfo(const char *message, ...)

정보 메시지 message 를 사용하여 메시지 핸들러를 호출합니다. 메시지 핸들러가 설치되지 않은 경우 메시지는 stderr로 인쇄됩니다. Windows에서는 콘솔 애플리케이션인 경우 메시지가 콘솔로 전송되고, 그렇지 않으면 디버거로 전송됩니다. QNX에서는 메시지가 slogger2로 전송됩니다. 컴파일 중에 QT_NO_INFO_OUTPUT 이 정의된 경우 이 함수는 아무 작업도 수행하지 않습니다.

함수에 형식 문자열과 인수 목록을 전달하면 C printf() 함수와 비슷한 방식으로 작동합니다. 형식은 라틴-1 문자열이어야 합니다.

예시:

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

<QtDebug> 를 포함하면 더 편리한 구문도 사용할 수 있습니다:

qInfo() << "Brush:" << myQBrush << "Other value:" << i;

이 구문을 사용하면 QtInfoMsg 메시지 유형을 사용하도록 구성된 QDebug 객체를 반환합니다. 각 항목 사이에 자동으로 공백을 하나씩 넣고 마지막에 줄 바꿈을 출력합니다. 이 함수는 다양한 C++ 및 Qt 유형을 지원합니다.

런타임에 출력을 억제하려면 qInstallMessageHandler()를 사용하여 자체 메시지 핸들러를 설치하세요.

참고: 이 매크로는 스레드에 안전합니다.

qCInfo(), qDebug(), qWarning(), qCritical(), qFatal(), qInstallMessageHandler() 및 디버깅 기법도참조하세요 .

qWarning(const char *message, ...)

경고 메시지와 함께 메시지 핸들러를 호출합니다 message. 메시지 처리기가 설치되어 있지 않으면 메시지가 stderr로 인쇄됩니다. Windows에서는 메시지가 디버거로 전송됩니다. QNX에서는 메시지가 slogger2로 전송됩니다.

이 함수는 C printf() 함수와 유사하게 형식 문자열과 인수 목록을 받습니다. 형식은 라틴-1 문자열이어야 합니다.

예시:

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

<QtDebug>를 포함하면 더 편리한 구문도 사용할 수 있습니다:

qWarning() << "Brush:" << myQBrush << "Other value:" << i;

이 구문은 각 항목 사이에 공백을 삽입하고 끝에 개행을 추가합니다.

컴파일 중에 QT_NO_WARNING_OUTPUT 을 정의한 경우 이 함수는 아무 작업도 수행하지 않습니다. 런타임에 출력을 억제하려면 logging rules 을 설정하거나 사용자 정의 filter 을 등록할 수 있습니다.

디버깅 목적으로 경고 메시지가 표시될 때 프로그램이 중단되도록 하는 것이 편리할 때가 있습니다. 이렇게 하면 코어 덤프를 검사하거나 디버거를 연결할 수 있습니다( qFatal() 참조). 이를 활성화하려면 환경 변수 QT_FATAL_WARNINGS 를 숫자로 설정하세요 n. 그러면 프로그램이 n번째 경고에 대해 종료됩니다. 즉, 환경 변수가 1로 설정되어 있으면 첫 번째 호출 시 종료되고, 10 값이 포함되어 있으면 10번째 호출 시 종료됩니다. 환경 변수에 숫자가 아닌 값은 모두 1에 해당합니다.

참고: 이 매크로는 스레드에 안전합니다.

qCWarning(), qDebug(), qInfo(), qCritical(), qFatal(), qInstallMessageHandler() 및 디버깅 기법도참조하세요 .

© 2025 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.