Add support for logging to a log file in the $XDG_STATE_DIR/flameshot (flameshot-org#4371)

(or equivelent directories on windows/mac-os)

By default logging to file is enabled for all log messages.

Filtering log messages written to disk by level severity and choosing a
different path to save the log files is configurable via the config menu.

There is also a shortcut on the about menu popup to open the configured
logging directory. This shortcut is disabled if logging to file is
disabled

The log file implements a simple roller that saves only the two most
recent sets of logs generated by flameshot. This should stop log
messages from eating users' disk.

We use cmake to check the version of QT6. If greater than or equal to
6.7, we set the default log directory to the standard App State
directory. If not, we use the app local data directory

Author: samwcoulter

src/CMakeLists.txt

@@ -539,3 +539,7 @@ if (APPLE)
 
 
 endif ()
+
+if(${Qt6Core_VERSION} VERSION_GREATER_EQUAL 6.7)
+    target_compile_definitions(flameshot PRIVATE QT_STATE_DIR_SUPPORTED=1)
+endif()

src/config/generalconf.cpp

@@ -2,7 +2,9 @@
 // SPDX-FileCopyrightText: 2017-2019 Alejandro Sirgo Rica & Contributors
 #include "generalconf.h"
 #include "src/core/flameshot.h"
+#include "src/utils/abstractlogger.h"
 #include "src/utils/confighandler.h"
+#include "src/utils/logfile.h"
 #include <QCheckBox>
 #include <QComboBox>
 #include <QFile>
@@ -56,6 +58,7 @@ GeneralConf::GeneralConf(QWidget* parent)
     initAntialiasingPinZoom();
     initUndoLimit();
     initInsecurePixelate();
+    initLogToFile();
 #ifdef ENABLE_IMGUR
     initCopyAndCloseAfterUpload();
     initUploadWithoutConfirmation();
@@ -121,6 +124,9 @@ void GeneralConf::_updateComponents(bool allowEmptySavePath)
     if (allowEmptySavePath || !config.savePath().isEmpty()) {
         m_savePath->setText(config.savePath());
     }
+    m_logToFile->setChecked(config.logToFile());
+    m_logFilePath->setText(config.logFilePath());
+
 #if defined(Q_OS_LINUX) || defined(Q_OS_UNIX)
     m_showTray->setChecked(!config.disabledTrayIcon());
 #endif
@@ -244,6 +250,7 @@ void GeneralConf::resetConfiguration()
     if (reply == QMessageBox::Yes) {
         m_savePath->setText(
           QStandardPaths::writableLocation(QStandardPaths::PicturesLocation));
+        m_logFilePath->setText(LogFile::defaultLogFilePath());
         ConfigHandler().setDefaultSettings();
         _updateComponents(true);
     }
@@ -706,6 +713,33 @@ void GeneralConf::changeSavePath()
     }
 }
 
+void GeneralConf::changeLogFilePath()
+{
+    QString path = ConfigHandler().logFilePath();
+
+    if (path.isEmpty()) {
+        path = LogFile::defaultLogFilePath();
+    }
+
+    path = QFileDialog::getExistingDirectory(
+      this,
+      tr("Choose a Folder"),
+      path,
+      QFileDialog::ShowDirsOnly | QFileDialog::DontResolveSymlinks);
+
+    if (!QFileInfo(path).isWritable()) {
+        QMessageBox::about(
+          this, tr("Error"), tr("Unable to write to directory."));
+        path = QString();
+    }
+
+    if (!path.isEmpty()) {
+        m_logFilePath->setText(path);
+        ConfigHandler().setLogFilePath(path);
+        LogFile::resetLogFile();
+    }
+}
+
 void GeneralConf::initCopyPathAfterSave()
 {
     m_copyPathAfterSave = new QCheckBox(tr("Copy file path after save"), this);
@@ -880,7 +914,7 @@ void GeneralConf::initInsecurePixelate()
 {
     m_insecurePixelate = new QCheckBox(tr("Insecure Pixelate"), this);
     m_insecurePixelate->setToolTip(
-      tr("Draw the pixelation effect in an insecure but more asethetic way."));
+      tr("Draw the pixelation effect in an insecure but more aesthetic way."));
     m_insecurePixelate->setChecked(ConfigHandler().insecurePixelate());
     m_scrollAreaLayout->addWidget(m_insecurePixelate);
 
@@ -890,6 +924,70 @@ void GeneralConf::initInsecurePixelate()
             &GeneralConf::setInsecurePixelate);
 }
 
+void GeneralConf::initLogToFile()
+{
+    auto* box = new QGroupBox(tr("Logging"));
+    box->setFlat(true);
+    m_layout->addWidget(box);
+
+    auto* vboxLayout = new QVBoxLayout();
+    box->setLayout(vboxLayout);
+
+    m_logToFile = new QCheckBox(tr("Log to file"), this);
+    m_logToFile->setToolTip(
+      tr("Save all log messages produced by flameshot to a file"));
+    m_logToFile->setChecked(ConfigHandler().logToFile());
+
+    connect(m_logToFile, &QCheckBox::clicked, this, &GeneralConf::setLogToFile);
+    vboxLayout->addWidget(m_logToFile);
+
+    auto* pathLayout = new QHBoxLayout();
+
+    QString path = ConfigHandler().logFilePath();
+    m_logFilePath = new QLineEdit(path, this);
+    m_logFilePath->setToolTip(
+      tr("The directory where log files will be saved"));
+    m_logFilePath->setDisabled(true);
+    QString foreground = this->palette().windowText().color().name();
+    m_logFilePath->setStyleSheet(QStringLiteral("color:%1").arg(foreground));
+    pathLayout->addWidget(m_logFilePath);
+
+    m_changeLogFilePathButton = new QPushButton(tr("Change..."), this);
+    pathLayout->addWidget(m_changeLogFilePathButton);
+    connect(m_changeLogFilePathButton,
+            &QPushButton::clicked,
+            this,
+            &GeneralConf::changeLogFilePath);
+
+    vboxLayout->addLayout(pathLayout);
+
+    auto* levelLayout = new QHBoxLayout();
+    auto* levelLabel = new QLabel(tr("Minimum Log Level"));
+    levelLabel->setToolTip(
+      tr("Specify the minimum severity level of log messages that "
+         "should be saved to disk"));
+    levelLayout->addWidget(levelLabel);
+
+    m_logFileLevel = new QComboBox(this);
+
+    m_logFileLevel->addItem(tr("Info (All Log Messages)"),
+                            AbstractLogger::Channel::Info);
+    m_logFileLevel->addItem(tr("Warnings and Errors"),
+                            AbstractLogger::Channel::Warning);
+    m_logFileLevel->addItem(tr("Errors"), AbstractLogger::Channel::Error);
+
+    auto level = ConfigHandler().value("logFileLevel").toInt();
+    m_logFileLevel->setCurrentIndex(m_logFileLevel->findData(level));
+
+    connect(
+      m_logFileLevel,
+      static_cast<void (QComboBox::*)(int)>(&QComboBox::currentIndexChanged),
+      this,
+      &GeneralConf::setLogFileLevel);
+    levelLayout->addWidget(m_logFileLevel);
+    vboxLayout->addLayout(levelLayout);
+}
+
 void GeneralConf::setSelGeoHideTime(int v)
 {
     ConfigHandler().setValue("showSelectionGeometryHideTime", v);
@@ -929,4 +1027,14 @@ void GeneralConf::setReverseArrow(bool checked)
 void GeneralConf::setInsecurePixelate(bool checked)
 {
     ConfigHandler().setInsecurePixelate(checked);
-}
+}
+
+void GeneralConf::setLogToFile(bool checked)
+{
+    ConfigHandler().setLogToFile(checked);
+}
+
+void GeneralConf::setLogFileLevel(int index)
+{
+    ConfigHandler().setValue("logFileLevel", m_logFileLevel->itemData(index));
+}

src/config/generalconf.h

@@ -50,6 +50,7 @@ private slots:
     void undoLimit(int limit);
     void saveAfterCopyChanged(bool checked);
     void changeSavePath();
+    void changeLogFilePath();
     void importConfiguration();
     void exportFileConfiguration();
     void resetConfiguration();
@@ -62,6 +63,8 @@ private slots:
     void setJpegQuality(int v);
     void setReverseArrow(bool checked);
     void setInsecurePixelate(bool checked);
+    void setLogToFile(bool checked);
+    void setLogFileLevel(int index);
 
 private:
     const QString chooseFolder(const QString& currentPath = "");
@@ -101,6 +104,7 @@ private slots:
     void initJpegQuality();
     void initReverseArrow();
     void initInsecurePixelate();
+    void initLogToFile();
 
     void _updateComponents(bool allowEmptySavePath);
 
@@ -150,4 +154,8 @@ private slots:
     QSpinBox* m_jpegQuality;
     QCheckBox* m_reverseArrow;
     QCheckBox* m_insecurePixelate;
+    QCheckBox* m_logToFile;
+    QLineEdit* m_logFilePath;
+    QPushButton* m_changeLogFilePathButton;
+    QComboBox* m_logFileLevel;
 };

src/utils/CMakeLists.txt

@@ -25,19 +25,20 @@ target_sources(
           colorutils.cpp
           history.cpp
           strfparse.cpp
+          logfile.cpp
 )
 
 IF (UNIX AND NOT APPLE)
-target_sources(
-  flameshot
-  PRIVATE request.h
-          request.cpp
-)
+    target_sources(
+      flameshot
+      PRIVATE request.h
+              request.cpp
+    )
 ENDIF()
 
 IF (WIN32)
-  target_sources(
-    flameshot
-    PRIVATE winlnkfileparse.cpp
-  )
+    target_sources(
+        flameshot
+        PRIVATE winlnkfileparse.cpp
+      )
 ENDIF()

src/utils/abstractlogger.cpp

@@ -1,17 +1,16 @@
 #include "abstractlogger.h"
+#include "confighandler.h"
+#include "logfile.h"
 #include "systemnotification.h"
 #include <cassert>
 
+#include <QDateTime>
 #include <QFileInfo>
 
 AbstractLogger::AbstractLogger(Channel channel, int targets)
   : m_defaultChannel(channel)
   , m_targets(targets)
-{
-    if (targets & LogFile) {
-        // TODO
-    }
-}
+{}
 
 /**
  * @brief Construct an AbstractLogger with output to a string.
@@ -56,8 +55,12 @@ AbstractLogger& AbstractLogger::sendMessage(const QString& msg, Channel channel)
             *stream << messageHeader(channel, String) << msg << "\n";
         }
     }
-    if (m_targets & LogFile) {
-        // TODO
+    if (m_targets & LogFile && ConfigHandler().logToFile()) {
+        if (channel >= ConfigHandler().logFileLevel()) {
+            QString data;
+            data = messageHeader(channel, LogFile) + msg + "\n";
+            LogFile::write(&data);
+        }
     }
     if (m_targets & Stderr) {
         QTextStream stream(stderr);
@@ -132,6 +135,9 @@ QString AbstractLogger::messageHeader(Channel channel, Target target)
     if (target == Notification) {
         messageChannel[0] = messageChannel[0].toUpper();
         return "Flameshot " + messageChannel;
+    } else if (target == LogFile) {
+        return QDateTime::currentDateTime().toString(Qt::ISODateWithMs) + ":[" +
+               messageChannel + "]: ";
     } else {
         return "flameshot: " + messageChannel + ": ";
     }

src/utils/confighandler.cpp

@@ -138,6 +138,9 @@ static QMap<class QString, QSharedPointer<ValueHandler>>
     OPTION("jpegQuality"                 , BoundedInt        ( 0,100,75      )),
     OPTION("reverseArrow"                ,Bool               ( false         )),
     OPTION("insecurePixelate"            ,Bool               ( false         )),
+    OPTION("logToFile"                   ,Bool               ( true          )),
+    OPTION("logFilePath"                 ,LoggingDir         (               )),
+    OPTION("logFileLevel"                ,BoundedInt         ( AbstractLogger::Channel::Info, AbstractLogger::Channel::Error, AbstractLogger::Channel::Info)),  
 };
 
 static QMap<QString, QSharedPointer<KeySequence>> recognizedShortcuts = {

src/utils/confighandler.h

@@ -141,6 +141,9 @@ class ConfigHandler : public QObject
     CONFIG_GETTER_SETTER(showSelectionGeometryHideTime,
                          showSelectionGeometryHideTime,
                          int)
+    CONFIG_GETTER_SETTER(logToFile, setLogToFile, bool)
+    CONFIG_GETTER_SETTER(logFilePath, setLogFilePath, QString)
+    CONFIG_GETTER_SETTER(logFileLevel, setLogFileLevel, int)
 
     // SPECIAL CASES
     bool startupLaunch();

src/utils/logfile.cpp

@@ -0,0 +1,73 @@
+#include "logfile.h"
+
+#include "confighandler.h"
+
+#include <QDir>
+#include <QMutexLocker>
+#include <QStandardPaths>
+
+constexpr const char* LOG_FILE_NAME = "flameshot.log";
+constexpr const char* OLD_LOG_FILE_NAME = "flameshot.log.old";
+
+void LogFile::write(const QString* data)
+{
+    QMutexLocker locker(&m_mutex);
+    if (nullptr == m_instance) {
+        m_instance = new LogFile();
+    }
+
+    m_instance->writeToFile(data);
+}
+
+void LogFile::resetLogFile()
+{
+    QMutexLocker locker(&m_mutex);
+    delete m_instance;
+    m_instance = nullptr;
+}
+
+QString LogFile::defaultLogFilePath()
+{
+#ifdef QT_STATE_DIR_SUPPORTED
+    const auto defaultLocation = QStandardPaths::GenericStateLocation;
+#else
+    const auto defaultLocation = QStandardPaths::GenericDataLocation;
+#endif
+    return QDir::toNativeSeparators(
+      QStandardPaths::writableLocation(defaultLocation) + "/flameshot");
+}
+
+LogFile::LogFile()
+{
+    auto loggingDirectory = QDir(ConfigHandler().logFilePath());
+
+    if (!loggingDirectory.exists()) {
+        loggingDirectory.mkpath(".");
+    }
+
+    if (loggingDirectory.exists(OLD_LOG_FILE_NAME)) {
+        loggingDirectory.remove(OLD_LOG_FILE_NAME);
+    }
+
+    if (loggingDirectory.exists(LOG_FILE_NAME)) {
+        loggingDirectory.rename(LOG_FILE_NAME, OLD_LOG_FILE_NAME);
+    }
+
+    auto logFilePath = loggingDirectory.filePath(LOG_FILE_NAME);
+    m_logFile = std::make_unique<QFile>(logFilePath);
+    if (m_logFile->open(QIODeviceBase::WriteOnly | QIODeviceBase::Append)) {
+        m_writer = std::make_unique<QTextStream>();
+        m_writer->setDevice(m_logFile.get());
+    }
+}
+
+void LogFile::writeToFile(const QString* data)
+{
+    if (m_writer) {
+        *m_writer << *data;
+        m_writer->flush();
+    }
+}
+
+LogFile* LogFile::m_instance = nullptr;
+QMutex LogFile::m_mutex;