From ffd3a4bff3b9c675572b2f882e3f0de11f8a144e Mon Sep 17 00:00:00 2001
From: Michal <michalszandarowski@gmail.com>
Date: Tue, 13 Oct 2026 17:03:29 +0200
Subject: [PATCH] feat: add quill logger * create logger for each subsystem *
 replace all couts and cerrs with logger * fix failing tests

---
 CLAUDE.md                                   |  12 +-
 README.md                                   |  35 ++++-
 cmake/Dependencies.cmake                    |  14 +-
 include/logging/Logging.hpp                 |  39 ++++++
 include/parser/Parser.hpp                   |   2 +-
 include/scene/SceneObject.hpp               |   1 -
 include/scene/components/BlinkComponent.hpp |   2 -
 src/CMakeLists.txt                          |   2 +
 src/Runtime.cpp                             |  11 +-
 src/logging/CMakeLists.txt                  |   7 +
 src/logging/Logging.cpp                     | 133 ++++++++++++++++++
 src/lslreader/CMakeLists.txt                |   2 +
 src/lslreader/LSLReader.cpp                 |  15 +-
 src/main.cpp                                |  29 +++-
 src/parser/CMakeLists.txt                   |   3 +-
 src/parser/Parser.cpp                       |   9 ++
 src/scene/SceneObject.cpp                   |   4 +-
 tests/CMakeLists.txt                        |   6 +-
 tests/cli_tests/CMakeLists.txt              |  24 ++++
 tests/component_tests/CMakeLists.txt        |   2 +-
 tests/unit_tests/CMakeLists.txt             |   2 +-
 tests/unit_tests/logging_test.cpp           |  49 +++++++
 tests/unit_tests/lslreader_test.cpp         | 144 ++++++++++----------
 tests/utils/TestMain.cpp                    |   9 ++
 24 files changed, 452 insertions(+), 104 deletions(-)
 create mode 100644 include/logging/Logging.hpp
 create mode 100644 src/logging/CMakeLists.txt
 create mode 100644 src/logging/Logging.cpp
 create mode 100644 tests/cli_tests/CMakeLists.txt
 create mode 100644 tests/unit_tests/logging_test.cpp
 create mode 100644 tests/utils/TestMain.cpp

diff --git a/CLAUDE.md b/CLAUDE.md
index d056b2a..d2431f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,10 +5,13 @@ You are in the **runtime** repo. Read the system overview below first.
 ## This repo
 
 - Build: `cmake -B build && cmake --build build`. Tests: `cd build && ctest --output-on-failure`
-  (`-L unit` / `-L component`). Format: `cmake --build build --target format` — CI fails on
-  unformatted code.
+  (`-L unit` / `-L component` / `-L cli`). Format: `cmake --build build --target format` — CI
+  fails on unformatted code.
 - Layout: `include/` headers, `src/` impl, `src/parser/Parser.cpp` turns a `.neuroz`/`.pb` file
-  into a `Scene`, `scene/components/` component classes, `tests/{unit,component}_tests/`.
+  into a `Scene`, `scene/components/` component classes, `tests/{unit,component,cli}_tests/`.
+- Logging: `LOG_*(logging::logger(logging::Subsystem::…), "…{}", …)` from
+  `<logging/Logging.hpp>` (Quill, README §3 "Logging"); never `std::cout` / `std::cerr`.
+  Nothing per frame or per sample. Level: `NEURONIDE_LOG_LEVEL`.
 - New component: subclass `Component`, add a static creator, and
   `REGISTER_COMPONENT(NeuronIDE::Component::k<Name>, Creator)` in its `.cpp`. The proto oneof
   entry must exist first — which means a backend change too.
@@ -20,7 +23,8 @@ You are in the **runtime** repo. Read the system overview below first.
   device `config.json` is written by the launcher, which starts the runtime with `[config.json] <experiment.neuroz>`
   (#31). The output folder comes from `config.json` (`output.directory`), which the launcher
   sets to each run's own folder; distinct exit codes are part of the same contract, because
-  the launcher shows them to the experimenter (both in runtime#37).
+  the launcher shows them to the experimenter (both in runtime#37). Diagnostics go to stderr
+  as `<time> <LEVEL> [<subsystem>] <message>` lines; tell the launcher team if that changes.
 - `config.json` is also produced by the launcher (Python). Changing its keys or validation rules
   is a cross-team change: bump `config_version` and tell the launcher team.
 
diff --git a/README.md b/README.md
index 959f8e6..b9ae5c9 100644
--- a/README.md
+++ b/README.md
@@ -41,11 +41,12 @@ EEG samples and the stimulus markers must share a **common clock domain** so tha
 | EEG acquisition          | [LSL — Lab Streaming Layer](https://github.com/sccn/liblsl) (`liblsl`) |
 | Rendering / windowing    | SDL2 (+ SDL2_image), with vsync                                        |
 | Inter-thread queues      | [moodycamel ConcurrentQueue](https://github.com/cameron314/concurrentqueue) (lock-free) |
+| Logging                  | [Quill](https://github.com/odygrd/quill) (asynchronous), to stderr — see §3 |
 | Python scripting (planned)| pybind11 (`ScriptComponent`)                                          |
 | Testing                  | GoogleTest + CTest                                                     |
 | Tooling                  | clang-format, clang-tidy, gcovr (coverage)                             |
 
-`liblsl`, `concurrentqueue`, `nlohmann/json`, and `googletest` are fetched
+`liblsl`, `concurrentqueue`, `nlohmann/json`, `quill`, and `googletest` are fetched
 automatically by CMake (`FetchContent`). SDL2 and Protobuf are expected to be
 installed on the system.
 
@@ -159,6 +160,29 @@ struct Context {                 // passed to Component::update each frame
 };
 ```
 
+### Logging
+
+Diagnostics go to **stderr** through [Quill](https://github.com/odygrd/quill). The
+calling thread only copies the message into a queue; a backend thread formats and
+writes it, so the render and acquisition threads never wait on I/O to log.
+
+```
+2026-10-13 16:43:15.852 WARNING  [lslreader] Stream 'obci_eeg1' lost (...); re-resolving
+```
+
+- Log through `logging::logger(logging::Subsystem::…)` from `<logging/Logging.hpp>`
+  with Quill's `LOG_DEBUG` … `LOG_CRITICAL` macros and `{}` placeholders. The
+  subsystem is printed in brackets, so messages need no `"LSLReader:"`-style prefix.
+  Do not write to `std::cout` / `std::cerr`; the usage text is the one exception.
+- `main()` holds a `logging::Session` for the whole run: it starts the backend and
+  writes out every queued message on exit. Tests get one from `tests/utils/TestMain.cpp`.
+- The level is `info` unless `NEURONIDE_LOG_LEVEL` sets another (`debug`, `warning`,
+  `none`, …); an unknown value is reported and ignored.
+- A crash (SIGSEGV, SIGABRT, …) still flushes the log. SIGINT and SIGTERM are left
+  to SDL, which turns them into `SDL_QUIT`, so a stopped run still closes its recording.
+- Nothing is logged per frame or per sample. Either log an error or throw it, not
+  both — except on a worker thread, where the log records *when* it failed.
+
 ## 4. Clock synchronization (critical)
 
 EEG analysis depends on EEG samples and stimulus markers being **comparable in
@@ -366,6 +390,7 @@ correct when `SDL_RenderPresent` waits for the refresh.
 | Config `validate()`         | Implemented   | semantic rules on the config types themselves, independent of JSON (see §5) |
 | `DataWriter`                | Implemented   | strategy-based; `CSVFormatStrategy`                          |
 | `DataFormatStrategyFactory` | Implemented   | `output.format` → format strategy; unknown formats rejected  |
+| Logging                     | Implemented   | Quill, one logger per subsystem, stderr (see §3) |
 | `Runtime` orchestration     | Implemented   | owns SDL session, parses both config files, gates the experiment on live EEG, records to a fresh file, drives the render loop, stops workers (see §6) |
 
 The class diagram in older docs is partly aspirational; the table above reflects
@@ -389,11 +414,14 @@ Neuron-IDE-runtime/       # the C++ runtime (git repo)
   │   ├── renderer/         # Renderer
   │   ├── lslreader/        # LSLReader
   │   ├── datawriter/       # DataWriter, IDataFormatStrategy, CSVFormatStrategy
+  │   ├── logging/          # subsystem loggers + logging Session (Quill)
   │   └── Runtime.hpp
   ├── src/                  # one CMake subdirectory (static lib) per module
   └── tests/
       ├── unit_tests/       # CTest label: "unit"
-      └── component_tests/  # CTest label: "component"
+      ├── component_tests/  # CTest label: "component"
+      ├── cli_tests/        # CTest label: "cli" — runs the NeuronIDE binary
+      └── utils/            # shared helpers, test main()
 ```
 
 Each `src/<module>/` builds a static library; `runtime_core` links them together
@@ -408,7 +436,7 @@ All commands are run from the `Neuron-IDE-runtime/` directory.
 ```bash
 sudo apt update
 sudo apt install cmake ninja-build clang-format clang-tidy-20 libsdl2-dev protobuf-compiler gcovr
-# GTest, LSL, concurrentqueue and nlohmann/json are fetched automatically by CMake.
+# GTest, LSL, concurrentqueue, nlohmann/json and Quill are fetched automatically by CMake.
 ```
 
 ### Configure & build
@@ -458,6 +486,7 @@ cd build
 ctest --output-on-failure          # all tests
 ctest -L unit --output-on-failure  # unit tests only
 ctest -L component --output-on-failure
+ctest -L cli --output-on-failure   # the NeuronIDE binary end to end
 ```
 
 > Note: `LSLReader` and `Runtime` unit tests open local LSL streams and exercise a
diff --git a/cmake/Dependencies.cmake b/cmake/Dependencies.cmake
index d9f2c02..29ee933 100644
--- a/cmake/Dependencies.cmake
+++ b/cmake/Dependencies.cmake
@@ -35,6 +35,14 @@ FetchContent_Declare(
 )
 set(JSON_BuildTests OFF CACHE INTERNAL "")
 
+# 5. Quill (header-only) - asynchronous logging
+FetchContent_Declare(
+  quill
+  URL https://github.com/odygrd/quill/archive/refs/tags/v13.0.0.tar.gz
+  URL_HASH SHA256=88b4a1542125577a4d51cf444c51e34d63618c422ba6a4fa9bd23894b49d696b
+  SYSTEM
+)
+
 # Suppress compiler warnings from third-party targets when compiling their source files
 set(BACKUP_C_FLAGS "${CMAKE_C_FLAGS}")
 set(BACKUP_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
@@ -46,14 +54,14 @@ elseif(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /w")
 endif()
 
-FetchContent_MakeAvailable(googletest liblsl concurrentqueue nlohmann_json)
+FetchContent_MakeAvailable(googletest liblsl concurrentqueue nlohmann_json quill)
 
 # Restore compiler flags for our own project code
 set(CMAKE_C_FLAGS "${BACKUP_C_FLAGS}")
 set(CMAKE_CXX_FLAGS "${BACKUP_CXX_FLAGS}")
 
-# 5. SDL2 (System installed)
+# 6. SDL2 (System installed)
 find_package(SDL2 REQUIRED)
 
-# 6. Protobuf (System installed)
+# 7. Protobuf (System installed)
 find_package(Protobuf REQUIRED)
diff --git a/include/logging/Logging.hpp b/include/logging/Logging.hpp
new file mode 100644
index 0000000..1734f12
--- /dev/null
+++ b/include/logging/Logging.hpp
@@ -0,0 +1,39 @@
+#ifndef LOGGING_HPP
+#define LOGGING_HPP
+
+#include <quill/LogMacros.h>
+#include <quill/Logger.h>
+
+#include <cstdint>
+#include <optional>
+#include <string_view>
+
+namespace logging {
+
+enum class Subsystem : std::uint8_t { App, Runtime, LslReader, Scene };
+
+// Safe to call from any thread. Messages reach stderr only while a Session is
+// running; without one they are queued and never printed.
+quill::Logger* logger(Subsystem subsystem);
+
+// Parses a NEURONIDE_LOG_LEVEL value such as "debug" or "WARNING". Returns
+// nullopt for anything a logger cannot be set to.
+std::optional<quill::LogLevel> parseLogLevel(std::string_view name);
+
+// Runs the logging backend thread; the destructor writes out every queued
+// message. Create it first in main() so it outlives every thread that logs.
+// Keep one at a time: the backend is shared, so destroying any Session stops it.
+class Session {
+   public:
+    Session();
+    ~Session();
+
+    Session(const Session&)            = delete;
+    Session& operator=(const Session&) = delete;
+    Session(Session&&)                 = delete;
+    Session& operator=(Session&&)      = delete;
+};
+
+}  // namespace logging
+
+#endif  // LOGGING_HPP
diff --git a/include/parser/Parser.hpp b/include/parser/Parser.hpp
index d4e8660..9c73dbe 100644
--- a/include/parser/Parser.hpp
+++ b/include/parser/Parser.hpp
@@ -1,7 +1,7 @@
 #ifndef PARSER_HPP
 #define PARSER_HPP
 
-#include <iostream>
+#include <iosfwd>
 #include <memory>
 #include <string>
 
diff --git a/include/scene/SceneObject.hpp b/include/scene/SceneObject.hpp
index df63ea9..170ced6 100644
--- a/include/scene/SceneObject.hpp
+++ b/include/scene/SceneObject.hpp
@@ -1,7 +1,6 @@
 #ifndef SCENEOBJECT_HPP
 #define SCENEOBJECT_HPP
 
-#include <iostream>
 #include <memory>
 #include <string>
 #include <vector>
diff --git a/include/scene/components/BlinkComponent.hpp b/include/scene/components/BlinkComponent.hpp
index dd68a4a..778dd0c 100644
--- a/include/scene/components/BlinkComponent.hpp
+++ b/include/scene/components/BlinkComponent.hpp
@@ -1,8 +1,6 @@
 #ifndef BLINKCOMPONENT_HPP
 #define BLINKCOMPONENT_HPP
 
-#include <iostream>
-
 #include "Component.hpp"
 
 namespace NeuronIDE {
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index c134744..3a96d96 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -5,6 +5,7 @@ set_target_properties(neuronide_proto PROPERTIES CXX_CLANG_TIDY "")
 target_include_directories(neuronide_proto SYSTEM PUBLIC ${CMAKE_CURRENT_BINARY_DIR})
 target_link_libraries(neuronide_proto PUBLIC protobuf::libprotobuf)
 
+add_subdirectory(logging)
 add_subdirectory(scene)
 add_subdirectory(parser)
 add_subdirectory(config)
@@ -17,6 +18,7 @@ add_library(runtime_core STATIC
 )
 target_include_directories(runtime_core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 target_link_libraries(runtime_core PUBLIC
+    logging
     scene
     parser
     config
diff --git a/src/Runtime.cpp b/src/Runtime.cpp
index 10e4936..3bc61de 100644
--- a/src/Runtime.cpp
+++ b/src/Runtime.cpp
@@ -13,7 +13,7 @@
 #include <exception>
 #include <filesystem>
 #include <format>
-#include <iostream>
+#include <logging/Logging.hpp>
 #include <lslreader/LSLReader.hpp>
 #include <memory>
 #include <parser/Parser.hpp>
@@ -33,6 +33,8 @@ constexpr const char* kFallbackName = "experiment";
 // How often the window's events are handled while waiting for the EEG stream.
 constexpr auto kEventPollInterval = std::chrono::milliseconds(50);
 
+quill::Logger* logger() { return logging::logger(logging::Subsystem::Runtime); }
+
 std::string sdlError(const char* what) { return std::string(what) + ": " + SDL_GetError(); }
 
 // The experiment name comes from an authored protobuf file and ends up in a file
@@ -217,7 +219,8 @@ std::string Runtime::makeOutputPath() const {
 // True once samples are flowing; false if the window was closed or
 // requestStop() was called first.
 bool Runtime::awaitAcquisition() {
-    std::cerr << "Runtime: waiting for EEG stream '" << config.lsl.name << "'...\n";
+    LOG_INFO(logger(), "Waiting up to {} ms for EEG stream '{}'", acquisitionTimeout.count(),
+             config.lsl.name);
 
     const std::stop_token token    = stopSource.get_token();
     const auto            deadline = std::chrono::steady_clock::now() + acquisitionTimeout;
@@ -254,6 +257,7 @@ bool Runtime::awaitAcquisition() {
 void Runtime::startRecording() {
     outputFilePath = makeOutputPath();
     dataWriter->start(outputFilePath, eegQueue, markerQueue);
+    LOG_INFO(logger(), "Recording to '{}'", outputFilePath);
 }
 
 void Runtime::run() {
@@ -274,6 +278,8 @@ void Runtime::run() {
         if (awaitAcquisition()) {
             startRecording();
             renderer->render(stopSource.get_token());
+        } else {
+            LOG_INFO(logger(), "Stopped while waiting for the EEG stream; nothing was recorded");
         }
     } catch (...) {
         shutdown();
@@ -284,6 +290,7 @@ void Runtime::run() {
     if (lslReader->state() == AcquisitionState::Failed) {
         throwAcquisitionFailure("during the experiment; the recording was stopped");
     }
+    LOG_INFO(logger(), "Run finished");
 }
 
 void Runtime::requestStop() { stopSource.request_stop(); }
diff --git a/src/logging/CMakeLists.txt b/src/logging/CMakeLists.txt
new file mode 100644
index 0000000..91e2b6f
--- /dev/null
+++ b/src/logging/CMakeLists.txt
@@ -0,0 +1,7 @@
+add_library(logging OBJECT
+    Logging.cpp
+)
+
+target_include_directories(logging PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/../../include)
+
+target_link_libraries(logging PUBLIC quill::quill)
diff --git a/src/logging/Logging.cpp b/src/logging/Logging.cpp
new file mode 100644
index 0000000..16554ea
--- /dev/null
+++ b/src/logging/Logging.cpp
@@ -0,0 +1,133 @@
+#include <quill/Backend.h>
+#include <quill/Frontend.h>
+#include <quill/core/QuillError.h>
+#include <quill/sinks/ConsoleSink.h>
+
+#include <array>
+#include <chrono>
+#include <csignal>
+#include <cstddef>
+#include <cstdlib>
+#include <logging/Logging.hpp>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+
+namespace logging {
+namespace {
+constexpr const char*     kLevelVariable = "NEURONIDE_LOG_LEVEL";
+constexpr quill::LogLevel kDefaultLevel  = quill::LogLevel::Info;
+
+constexpr const char* kSinkName        = "stderr";
+constexpr const char* kPattern         = "%(time) %(log_level:<8) [%(logger)] %(message)";
+constexpr const char* kTimestampFormat = "%Y-%m-%d %H:%M:%S.%Qms";
+
+// Quill polls every 100 us by default. A run logs a handful of lines, so the
+// backend can sleep far longer instead of waking up next to the render thread.
+constexpr auto kBackendSleep = std::chrono::milliseconds(5);
+
+// logger() indexes its cache by enumerator value: list every one, in order.
+constexpr std::array kSubsystems{Subsystem::App, Subsystem::Runtime, Subsystem::LslReader,
+                                 Subsystem::Scene};
+
+const char* nameOf(Subsystem subsystem) {
+    switch (subsystem) {
+        case Subsystem::App:
+            return "app";
+        case Subsystem::Runtime:
+            return "runtime";
+        case Subsystem::LslReader:
+            return "lslreader";
+        case Subsystem::Scene:
+            return "scene";
+    }
+    return "unknown";
+}
+
+struct LevelSetting {
+    quill::LogLevel            level = kDefaultLevel;
+    std::optional<std::string> rejectedValue;
+};
+
+const LevelSetting& levelSetting() {
+    static const LevelSetting setting = [] {
+        LevelSetting result;
+        const char*  value = std::getenv(kLevelVariable);
+        if (value == nullptr) {
+            return result;
+        }
+        if (const std::optional<quill::LogLevel> level = parseLogLevel(value)) {
+            result.level = *level;
+        } else {
+            result.rejectedValue = value;
+        }
+        return result;
+    }();
+    return setting;
+}
+
+quill::Logger* createLogger(Subsystem subsystem) {
+    quill::ConsoleSinkConfig sinkConfig;
+    sinkConfig.set_stream("stderr");
+    auto sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>(kSinkName, sinkConfig);
+
+    // Log times are read by people next to wall-clock file names; the default
+    // TSC clock would only add calibration to get there.
+    quill::Logger* created = quill::Frontend::create_or_get_logger(
+        nameOf(subsystem), std::move(sink),
+        quill::PatternFormatterOptions{kPattern, kTimestampFormat, quill::Timezone::LocalTime},
+        quill::ClockSourceType::System);
+    created->set_log_level(levelSetting().level);
+    return created;
+}
+}  // namespace
+
+quill::Logger* logger(Subsystem subsystem) {
+    static const auto loggers = [] {
+        std::array<quill::Logger*, kSubsystems.size()> created{};
+        for (const Subsystem each : kSubsystems) {
+            created.at(static_cast<std::size_t>(each)) = createLogger(each);
+        }
+        return created;
+    }();
+    return loggers.at(static_cast<std::size_t>(subsystem));
+}
+
+std::optional<quill::LogLevel> parseLogLevel(std::string_view name) {
+    quill::LogLevel level{};
+    try {
+        level = quill::loglevel_from_string(std::string(name));
+    } catch (const quill::QuillError&) {
+        return std::nullopt;
+    }
+    // Quill reserves Backtrace for itself; set_log_level() throws on it.
+    if (level == quill::LogLevel::Backtrace) {
+        return std::nullopt;
+    }
+    return level;
+}
+
+Session::Session() {
+    quill::BackendOptions backendOptions;
+    backendOptions.sleep_duration = kBackendSleep;
+
+    // Crash signals only. Quill would end the process on SIGINT/SIGTERM, while SDL
+    // turns them into SDL_QUIT, so the run shuts down and closes its recording.
+    quill::SignalHandlerOptions signalOptions;
+    signalOptions.catchable_signals = {SIGABRT, SIGFPE, SIGILL, SIGSEGV};
+
+    quill::Backend::start<quill::FrontendOptions>(backendOptions, signalOptions);
+
+    if (const std::optional<std::string>& rejected = levelSetting().rejectedValue) {
+        LOG_WARNING(logger(Subsystem::App), "Ignoring {}='{}': not a log level, using the default",
+                    kLevelVariable, *rejected);
+    }
+}
+
+// stop() throws only when called from the backend thread itself, which never
+// runs this destructor.
+// NOLINTNEXTLINE(bugprone-exception-escape)
+Session::~Session() { quill::Backend::stop(); }
+
+}  // namespace logging
diff --git a/src/lslreader/CMakeLists.txt b/src/lslreader/CMakeLists.txt
index 0f88626..c094c7c 100644
--- a/src/lslreader/CMakeLists.txt
+++ b/src/lslreader/CMakeLists.txt
@@ -12,3 +12,5 @@ target_link_libraries(lslreader PUBLIC
     concurrentqueue
     config
 )
+
+target_link_libraries(lslreader PRIVATE logging)
diff --git a/src/lslreader/LSLReader.cpp b/src/lslreader/LSLReader.cpp
index 7e2c31c..a8d7d5c 100644
--- a/src/lslreader/LSLReader.cpp
+++ b/src/lslreader/LSLReader.cpp
@@ -5,7 +5,7 @@
 #include <cstddef>
 #include <data_structures/EEGData.hpp>
 #include <exception>
-#include <iostream>
+#include <logging/Logging.hpp>
 #include <mutex>
 #include <optional>
 #include <stdexcept>
@@ -25,6 +25,8 @@ constexpr int    kSenderChunkLength  = 0;    // 0: the sender decides chunk gran
 constexpr bool   kRecoverSilently     = false;
 constexpr double kSampleRateTolerance = 0.5;  // Hz
 
+quill::Logger* logger() { return logging::logger(logging::Subsystem::LslReader); }
+
 // Offsets of the enabled channels within a pulled sample, in the order the
 // config declares them. Validates the config first: the reader indexes into raw
 // samples with these offsets, so it cannot take the config's invariants on
@@ -101,6 +103,11 @@ std::optional<lsl::stream_info> resolveStream(const LSLConfig&       config,
     }
     return std::nullopt;
 }
+
+void logStreamingStarted(const lsl::stream_info& info, std::size_t forwardedChannels) {
+    LOG_INFO(logger(), "Streaming from '{}' at {} Hz, forwarding {} of {} channels", info.name(),
+             info.nominal_srate(), forwardedChannels, info.channel_count());
+}
 }  // namespace
 
 LSLReader::LSLReader(DeviceConfig deviceConfig)
@@ -128,7 +135,7 @@ void LSLReader::start(std::shared_ptr<moodycamel::ConcurrentQueue<EEGData>> eegQ
         try {
             readLoop(stopToken);
         } catch (const std::exception& e) {
-            std::cerr << "LSLReader: fatal error, stopping acquisition: " << e.what() << "\n";
+            LOG_ERROR(logger(), "Acquisition stopped: {}", e.what());
             fail(std::current_exception());
         }
     });
@@ -225,11 +232,11 @@ void LSLReader::readLoop(const std::stop_token& stopToken) {
                 if (!streaming) {
                     streaming = true;
                     setState(AcquisitionState::Streaming);
+                    logStreamingStarted(*info, enabledChannelIndices.size());
                 }
             }
         } catch (const lsl::lost_error& e) {
-            std::cerr << "LSLReader: stream '" << config.lsl.name << "' lost (" << e.what()
-                      << "), re-resolving\n";
+            LOG_WARNING(logger(), "Stream '{}' lost ({}); re-resolving", config.lsl.name, e.what());
         }
     }
 }
diff --git a/src/main.cpp b/src/main.cpp
index dc062db..ebd3234 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -1,22 +1,25 @@
 #include <Runtime.hpp>
 #include <cstddef>
+#include <cstdio>
 #include <exception>
 #include <iostream>
+#include <logging/Logging.hpp>
 #include <span>
 #include <string>
 
 namespace {
 constexpr const char* kDefaultConfigPath = "config.json";
 
+quill::Logger* logger() { return logging::logger(logging::Subsystem::App); }
+
 void printUsage(const char* program) {
     std::cerr << "Usage: " << program << " [config.json] <experiment.neuroz>\n"
               << "  config.json defaults to '" << kDefaultConfigPath
               << "' in the working directory.\n";
 }
-}  // namespace
 
-int main(int argc, char* argv[]) {
-    const std::span<char* const> args(argv, static_cast<std::size_t>(argc));
+int runApplication(std::span<char* const> args) {
+    const logging::Session loggingSession;
 
     RuntimePaths paths{.config = kDefaultConfigPath, .experiment = ""};
 
@@ -30,13 +33,31 @@ int main(int argc, char* argv[]) {
         return 1;
     }
 
+    LOG_INFO(logger(), "Starting with config '{}' and experiment '{}'", paths.config,
+             paths.experiment);
+
     try {
         Runtime runtime(paths);
         runtime.run();
     } catch (const std::exception& e) {
-        std::cerr << "NeuronIDE: fatal: " << e.what() << "\n";
+        LOG_CRITICAL(logger(), "Run aborted: {}", e.what());
         return 1;
     }
 
     return 0;
 }
+}  // namespace
+
+int main(int argc, char* argv[]) {
+    try {
+        return runApplication(std::span<char* const>(argv, static_cast<std::size_t>(argc)));
+    } catch (const std::exception& e) {
+        // Logging itself failed, so plain stderr is all that is left.
+        std::fputs("NeuronIDE: fatal: ", stderr);
+        std::fputs(e.what(), stderr);
+        std::fputs("\n", stderr);
+    } catch (...) {
+        std::fputs("NeuronIDE: fatal: unknown error\n", stderr);
+    }
+    return 1;
+}
diff --git a/src/parser/CMakeLists.txt b/src/parser/CMakeLists.txt
index f06dab3..fb355f1 100644
--- a/src/parser/CMakeLists.txt
+++ b/src/parser/CMakeLists.txt
@@ -4,4 +4,5 @@ add_library(parser OBJECT
 
 target_include_directories(parser PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/../../include/parser)
 
-target_link_libraries(parser PUBLIC scene)
\ No newline at end of file
+target_link_libraries(parser PUBLIC scene)
+target_link_libraries(parser PRIVATE logging)
\ No newline at end of file
diff --git a/src/parser/Parser.cpp b/src/parser/Parser.cpp
index 43413f6..52a27e4 100644
--- a/src/parser/Parser.cpp
+++ b/src/parser/Parser.cpp
@@ -1,6 +1,7 @@
 #include "parser/Parser.hpp"
 
 #include <fstream>
+#include <logging/Logging.hpp>
 #include <stdexcept>
 #include <unordered_set>
 
@@ -10,6 +11,10 @@
 #include "scene/components/Component.hpp"
 #include "scene/components/ComponentRegistry.hpp"
 
+namespace {
+quill::Logger* logger() { return logging::logger(logging::Subsystem::Scene); }
+}  // namespace
+
 std::shared_ptr<Scene> Parser::parse(const std::string& filePath) {
     std::ifstream file(filePath, std::ios::binary);
     if (!file.is_open()) {
@@ -40,11 +45,15 @@ std::shared_ptr<Scene> Parser::parseStream(std::istream& stream) {
 
     for (const auto& protoObj : protoScene.scene_objects()) {
         auto obj = buildSceneObject(protoObj);
+        LOG_DEBUG(logger(), "Loaded object '{}' ({} components)", obj->name,
+                  obj->components.size());
         scene->addObject(std::move(obj));
     }
 
     scene->onSceneReady();
 
+    LOG_INFO(logger(), "Loaded experiment '{}' ({} objects)", scene->getExperimentName(),
+             scene->getObjects().size());
     return scene;
 }
 
diff --git a/src/scene/SceneObject.cpp b/src/scene/SceneObject.cpp
index 5a6d948..0008678 100644
--- a/src/scene/SceneObject.cpp
+++ b/src/scene/SceneObject.cpp
@@ -4,9 +4,7 @@
 
 #include "scene/components/Component.hpp"
 
-SceneObject::SceneObject(std::string n, bool visible) : name(std::move(n)), isVisible(visible) {
-    std::cout << "  [SceneObject] Utworzono obiekt: " << name << "\n";
-}
+SceneObject::SceneObject(std::string n, bool visible) : name(std::move(n)), isVisible(visible) {}
 
 void SceneObject::setTransform(const Transform& transform) { this->transform = transform; }
 
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 840c37d..d312bc0 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -1,4 +1,8 @@
 include(GoogleTest)
 
+add_library(test_main OBJECT utils/TestMain.cpp)
+target_link_libraries(test_main PUBLIC gtest runtime_core)
+
 add_subdirectory(unit_tests)
-add_subdirectory(component_tests)
\ No newline at end of file
+add_subdirectory(component_tests)
+add_subdirectory(cli_tests)
\ No newline at end of file
diff --git a/tests/cli_tests/CMakeLists.txt b/tests/cli_tests/CMakeLists.txt
new file mode 100644
index 0000000..c747a74
--- /dev/null
+++ b/tests/cli_tests/CMakeLists.txt
@@ -0,0 +1,24 @@
+# Run the NeuronIDE binary the way the launcher does and check what it reports.
+# CTest ignores the exit code once PASS_REGULAR_EXPRESSION is set.
+
+add_test(NAME NeuronIDECli.PrintsUsageWithoutArguments COMMAND NeuronIDE)
+set_tests_properties(NeuronIDECli.PrintsUsageWithoutArguments PROPERTIES
+    LABELS "cli"
+    PASS_REGULAR_EXPRESSION "Usage: .* \\[config\\.json\\] <experiment\\.neuroz>"
+)
+
+add_test(NAME NeuronIDECli.LogsWhyARunAborted
+    COMMAND NeuronIDE no-such-config.json no-such-experiment.neuroz
+)
+set_tests_properties(NeuronIDECli.LogsWhyARunAborted PROPERTIES
+    LABELS "cli"
+    PASS_REGULAR_EXPRESSION
+        "CRITICAL +\\[app\\] Run aborted: ConfigParser: cannot open file: no-such-config\\.json"
+)
+
+add_test(NAME NeuronIDECli.WarnsAboutAnUnknownLogLevel COMMAND NeuronIDE)
+set_tests_properties(NeuronIDECli.WarnsAboutAnUnknownLogLevel PROPERTIES
+    LABELS "cli"
+    ENVIRONMENT "NEURONIDE_LOG_LEVEL=verbose"
+    PASS_REGULAR_EXPRESSION "WARNING +\\[app\\] Ignoring NEURONIDE_LOG_LEVEL='verbose'"
+)
diff --git a/tests/component_tests/CMakeLists.txt b/tests/component_tests/CMakeLists.txt
index 4ec7a3e..3979b7c 100644
--- a/tests/component_tests/CMakeLists.txt
+++ b/tests/component_tests/CMakeLists.txt
@@ -2,7 +2,7 @@ file(GLOB COMP_TEST_SOURCES "*.cpp")
 
 if(COMP_TEST_SOURCES)
     add_executable(component_tests ${COMP_TEST_SOURCES})
-    target_link_libraries(component_tests PRIVATE gtest_main runtime_core)
+    target_link_libraries(component_tests PRIVATE test_main runtime_core)
     target_include_directories(component_tests PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/..)
 
     gtest_discover_tests(component_tests PROPERTIES LABELS "component")
diff --git a/tests/unit_tests/CMakeLists.txt b/tests/unit_tests/CMakeLists.txt
index 040706c..a734c4e 100644
--- a/tests/unit_tests/CMakeLists.txt
+++ b/tests/unit_tests/CMakeLists.txt
@@ -2,7 +2,7 @@ file(GLOB UNIT_TEST_SOURCES "*.cpp")
 
 if(UNIT_TEST_SOURCES)
     add_executable(unit_tests ${UNIT_TEST_SOURCES})
-    target_link_libraries(unit_tests PRIVATE gtest_main runtime_core)
+    target_link_libraries(unit_tests PRIVATE test_main runtime_core)
     target_include_directories(unit_tests PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/..)
 
     gtest_discover_tests(unit_tests PROPERTIES LABELS "unit")
diff --git a/tests/unit_tests/logging_test.cpp b/tests/unit_tests/logging_test.cpp
new file mode 100644
index 0000000..cb414ac
--- /dev/null
+++ b/tests/unit_tests/logging_test.cpp
@@ -0,0 +1,49 @@
+#include <gtest/gtest.h>
+
+#include <array>
+#include <logging/Logging.hpp>
+#include <optional>
+#include <set>
+#include <string>
+#include <string_view>
+#include <utility>
+
+namespace {
+using logging::Subsystem;
+
+constexpr std::array<std::pair<Subsystem, std::string_view>, 4> kExpectedNames{{
+    {Subsystem::App, "app"},
+    {Subsystem::Runtime, "runtime"},
+    {Subsystem::LslReader, "lslreader"},
+    {Subsystem::Scene, "scene"},
+}};
+}  // namespace
+
+TEST(LoggingTest, EverySubsystemHasItsOwnNamedLogger) {
+    std::set<quill::Logger*> distinct;
+    for (const auto& [subsystem, name] : kExpectedNames) {
+        quill::Logger* logger = logging::logger(subsystem);
+        ASSERT_NE(logger, nullptr);
+        EXPECT_EQ(logger->get_logger_name(), name);
+        distinct.insert(logger);
+    }
+    EXPECT_EQ(distinct.size(), kExpectedNames.size());
+}
+
+TEST(LoggingTest, ReturnsTheSameLoggerOnEveryCall) {
+    EXPECT_EQ(logging::logger(Subsystem::Runtime), logging::logger(Subsystem::Runtime));
+}
+
+TEST(LoggingTest, ParsesLevelNamesIgnoringCase) {
+    EXPECT_EQ(logging::parseLogLevel("debug"), quill::LogLevel::Debug);
+    EXPECT_EQ(logging::parseLogLevel("Info"), quill::LogLevel::Info);
+    EXPECT_EQ(logging::parseLogLevel("WARNING"), quill::LogLevel::Warning);
+    EXPECT_EQ(logging::parseLogLevel("none"), quill::LogLevel::None);
+}
+
+TEST(LoggingTest, RejectsNamesThatAreNotSettableLevels) {
+    EXPECT_EQ(logging::parseLogLevel(""), std::nullopt);
+    EXPECT_EQ(logging::parseLogLevel("verbose"), std::nullopt);
+    EXPECT_EQ(logging::parseLogLevel("backtrace"), std::nullopt)
+        << "Quill throws when a logger is set to Backtrace";
+}
diff --git a/tests/unit_tests/lslreader_test.cpp b/tests/unit_tests/lslreader_test.cpp
index f2a3c9c..5f9ffc1 100644
--- a/tests/unit_tests/lslreader_test.cpp
+++ b/tests/unit_tests/lslreader_test.cpp
@@ -7,13 +7,11 @@
 #include <config/DeviceConfig.hpp>
 #include <cstddef>
 #include <data_structures/EEGData.hpp>
-#include <iostream>
+#include <exception>
 #include <lslreader/LSLReader.hpp>
 #include <memory>
-#include <sstream>
 #include <stdexcept>
 #include <stop_token>
-#include <streambuf>
 #include <string>
 #include <thread>
 #include <utility>
@@ -34,24 +32,7 @@ constexpr auto   kDrainWait            = std::chrono::milliseconds(300);
 constexpr auto   kSubscribePoll        = std::chrono::milliseconds(20);
 constexpr double kRecoveryValue        = 42.0;
 
-constexpr auto kValidationWait = std::chrono::milliseconds(1500);
-constexpr auto kStateWait      = std::chrono::seconds(10);
-
-class ScopedStreamRedirect {
-   public:
-    ScopedStreamRedirect(std::ostream& stream, std::streambuf* buffer)
-        : stream(stream), previous(stream.rdbuf(buffer)) {}
-    ~ScopedStreamRedirect() { stream.rdbuf(previous); }
-
-    ScopedStreamRedirect(const ScopedStreamRedirect&)            = delete;
-    ScopedStreamRedirect& operator=(const ScopedStreamRedirect&) = delete;
-    ScopedStreamRedirect(ScopedStreamRedirect&&)                 = delete;
-    ScopedStreamRedirect& operator=(ScopedStreamRedirect&&)      = delete;
-
-   private:
-    std::ostream&   stream;
-    std::streambuf* previous;
-};
+constexpr auto kStateWait = std::chrono::seconds(10);
 
 // All channels enabled, declared in stream order.
 std::vector<ChannelConfig> makeChannels() {
@@ -121,33 +102,24 @@ void pushSamples(lsl::stream_outlet& outlet, const std::vector<double>& sample,
     }
 }
 
-std::string runAndCaptureDiagnostics(const DeviceConfig& config, int channelCount,
-                                     double sampleRate) {
-    lsl::stream_outlet outlet   = makeOutletWithShape(config, channelCount, sampleRate);
-    auto               eegQueue = std::make_shared<moodycamel::ConcurrentQueue<EEGData>>();
-    LSLReader          reader(config);
-
-    std::ostringstream captured;
-    {
-        const ScopedStreamRedirect redirect(std::cerr, captured.rdbuf());
-        reader.start(eegQueue);
-        std::this_thread::sleep_for(kValidationWait);
-        reader.stop();
+// Polls, because LSLReader only offers to wait while it is Resolving.
+bool waitForState(const LSLReader& reader, AcquisitionState expected,
+                  std::chrono::steady_clock::duration timeout) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (reader.state() != expected) {
+        if (std::chrono::steady_clock::now() >= deadline) {
+            return false;
+        }
+        std::this_thread::sleep_for(kSubscribePoll);
     }
-
-    EEGData received;
-    EXPECT_FALSE(eegQueue->try_dequeue(received)) << "a rejected stream must yield no samples";
-    return captured.str();
+    return true;
 }
 
-// Starts the reader with its diagnostics silenced, waits while it resolves, and
-// stops it. Returns the state the wait ended on.
+// Starts the reader, waits while it resolves, and stops it. Returns the state
+// the wait ended on.
 AcquisitionState startWaitAndStop(
     LSLReader& reader, const std::shared_ptr<moodycamel::ConcurrentQueue<EEGData>>& eegQueue,
-    LSLReader::FailureCallback onFailure) {
-    std::ostringstream         captured;
-    const ScopedStreamRedirect redirect(std::cerr, captured.rdbuf());
-
+    LSLReader::FailureCallback onFailure = {}) {
     reader.start(eegQueue, std::move(onFailure));
     const std::stop_source neverStopped;
     const AcquisitionState reached = reader.waitWhileResolving(
@@ -156,6 +128,33 @@ AcquisitionState startWaitAndStop(
     return reached;
 }
 
+std::string failureMessage(const LSLReader& reader) {
+    const std::exception_ptr failure = reader.failure();
+    if (!failure) {
+        return {};
+    }
+    try {
+        std::rethrow_exception(failure);
+    } catch (const std::exception& e) {
+        return e.what();
+    } catch (...) {
+        return "non-standard exception";
+    }
+}
+
+// Offers the reader a stream of the given shape and returns why it rejected it.
+std::string rejectionReason(const DeviceConfig& config, int channelCount, double sampleRate) {
+    lsl::stream_outlet outlet   = makeOutletWithShape(config, channelCount, sampleRate);
+    auto               eegQueue = std::make_shared<moodycamel::ConcurrentQueue<EEGData>>();
+    LSLReader          reader(config);
+
+    EXPECT_EQ(startWaitAndStop(reader, eegQueue), AcquisitionState::Failed);
+
+    EEGData received;
+    EXPECT_FALSE(eegQueue->try_dequeue(received)) << "a rejected stream must yield no samples";
+    return failureMessage(reader);
+}
+
 // Keeps pushing a marked sample until one of them comes back through the queue,
 // so the check does not depend on when exactly the inlet reconnects. Samples
 // from before the drop carry other values and are discarded.
@@ -253,36 +252,35 @@ TEST(LSLReaderTest, ReResolvesStreamAfterItIsLost) {
     config.lsl.name     = "neuronide_test_lost_stream";
     config.lsl.sourceId = "neuronide-test-lost";
 
-    auto      eegQueue = std::make_shared<moodycamel::ConcurrentQueue<EEGData>>();
-    LSLReader reader(config);
+    auto                   eegQueue = std::make_shared<moodycamel::ConcurrentQueue<EEGData>>();
+    LSLReader              reader(config);
+    const std::stop_source neverStopped;
 
-    std::ostringstream captured;
     {
-        const ScopedStreamRedirect redirect(std::cerr, captured.rdbuf());
-
-        {
-            lsl::stream_outlet outlet = makeOutlet(config);
-            reader.start(eegQueue);
-            ASSERT_TRUE(waitForConsumer(outlet, kRecoveryWait))
-                << "LSLReader did not subscribe (needs loopback)";
-            pushSamples(outlet, makeSample(), kSamplesToPush);
-        }  // outlet gone: the inlet's pull must raise lsl::lost_error
+        lsl::stream_outlet outlet = makeOutlet(config);
+        reader.start(eegQueue);
+        ASSERT_TRUE(waitForConsumer(outlet, kRecoveryWait))
+            << "LSLReader did not subscribe (needs loopback)";
+        pushSamples(outlet, makeSample(), kSamplesToPush);
+        ASSERT_EQ(reader.waitWhileResolving(std::chrono::steady_clock::now() + kStateWait,
+                                            neverStopped.get_token()),
+                  AcquisitionState::Streaming);
+    }  // outlet gone: the inlet's pull must raise lsl::lost_error
 
-        lsl::stream_outlet revived = makeOutlet(config);
-        ASSERT_TRUE(waitForConsumer(revived, kRecoveryWait))
-            << "LSLReader did not re-resolve the stream after it was lost";
+    // Had liblsl recovered the inlet silently, the reader would still be Streaming.
+    EXPECT_TRUE(waitForState(reader, AcquisitionState::Resolving, kRecoveryWait))
+        << "the drop should surface as lsl::lost_error and be re-resolved";
 
-        EXPECT_TRUE(pushUntilReceived(revived, *eegQueue, kRecoveryValue, kRecoveryWait))
-            << "no samples arrived after the stream came back";
+    lsl::stream_outlet revived = makeOutlet(config);
+    ASSERT_TRUE(waitForConsumer(revived, kRecoveryWait))
+        << "LSLReader did not re-resolve the stream after it was lost";
 
-        reader.stop();
-    }
+    EXPECT_TRUE(pushUntilReceived(revived, *eegQueue, kRecoveryValue, kRecoveryWait))
+        << "no samples arrived after the stream came back";
 
-    const std::string log = captured.str();
-    EXPECT_NE(log.find("lost"), std::string::npos)
-        << "the drop should surface as lsl::lost_error and be re-resolved, got: " << log;
-    EXPECT_EQ(log.find("fatal error"), std::string::npos)
-        << "a dropped stream must not stop acquisition, got: " << log;
+    reader.stop();
+    EXPECT_EQ(reader.failure(), nullptr)
+        << "a dropped stream must not stop acquisition, got: " << failureMessage(reader);
 }
 
 TEST(LSLReaderTest, RejectsStreamWithMismatchedChannelCount) {
@@ -290,9 +288,9 @@ TEST(LSLReaderTest, RejectsStreamWithMismatchedChannelCount) {
     config.lsl.name     = "neuronide_test_chan_mismatch";
     config.lsl.sourceId = "neuronide-test-chan";
 
-    const std::string log = runAndCaptureDiagnostics(config, kMismatchedChannels, kSampleRate);
-    EXPECT_NE(log.find("channels"), std::string::npos)
-        << "expected a channel-count rejection, got: " << log;
+    const std::string reason = rejectionReason(config, kMismatchedChannels, kSampleRate);
+    EXPECT_NE(reason.find("channels"), std::string::npos)
+        << "expected a channel-count rejection, got: " << reason;
 }
 
 TEST(LSLReaderTest, RejectsStreamWithMismatchedSampleRate) {
@@ -300,9 +298,9 @@ TEST(LSLReaderTest, RejectsStreamWithMismatchedSampleRate) {
     config.lsl.name     = "neuronide_test_rate_mismatch";
     config.lsl.sourceId = "neuronide-test-rate";
 
-    const std::string log = runAndCaptureDiagnostics(config, kChannelCount, kMismatchedSampleRate);
-    EXPECT_NE(log.find("Hz"), std::string::npos)
-        << "expected a sample-rate rejection, got: " << log;
+    const std::string reason = rejectionReason(config, kChannelCount, kMismatchedSampleRate);
+    EXPECT_NE(reason.find("Hz"), std::string::npos)
+        << "expected a sample-rate rejection, got: " << reason;
 }
 
 TEST(LSLReaderTest, StopBeforeStreamResolvedExitsCleanly) {
diff --git a/tests/utils/TestMain.cpp b/tests/utils/TestMain.cpp
new file mode 100644
index 0000000..1e1474c
--- /dev/null
+++ b/tests/utils/TestMain.cpp
@@ -0,0 +1,9 @@
+#include <gtest/gtest.h>
+
+#include <logging/Logging.hpp>
+
+int main(int argc, char** argv) {
+    const logging::Session loggingSession;
+    testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}