docs and improvements

Author: odygrd

CHANGELOG.md

@@ -103,16 +103,13 @@
   preprocessor will eliminate the `if` branch from the hotpath and disable this feature regardless of the
   value of `logger->set_immediate_flush(true)`.
 
-- `QUILL_LOG_RUNTIME_METADATA` macro signature has changed from
-  `QUILL_LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, fmt, ...)` to
-  `QUILL_LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, tags, fmt, ...)`. It now accepts one
-  additional argument: `tags`. When upgrading to the new version, you will have to add this argument; you can use `""`
-  for empty tags.
-
-- Internally refactored how runtime metadata are handled to provide more flexibility. There are now three macros that
-  can also be used by users allowing to log runtime metadata:
-  - `QUILL_LOG_RUNTIME_METADATA` - Will take a deep copy of `fmt`, `file`, `function` and `tags`. This is the most
-    flexible one; it can be used, for example, to forward logs from another logging library to quill.
+- The `QUILL_LOG_RUNTIME_METADATA` macro requires `file`, `function` and `fmt` to be passed as `char const*` and
+  `line_number` as `uint32_t`. This is a breaking change from the previous version.
+
+- Internally, refactored how runtime metadata are handled for more flexibility, providing three macros for logging with
+  runtime metadata:
+  - `QUILL_LOG_RUNTIME_METADATA_DEEP` - Takes a deep copy of `fmt`, `file`, `function` and `tags`. Most flexible
+    option, useful for forwarding logs from another logging library.
   - `QUILL_LOG_RUNTIME_METADATA_HYBRID` - Will take a deep copy of `fmt` and `tags` and will take `file` and
     `function` as reference. This is used for the new macro-free mode.
   - `QUILL_LOG_RUNTIME_METADATA_SHALLOW` - Will take everything as reference. This is used when logging with

docs/logging_macros.rst

@@ -343,7 +343,12 @@ Runtime Metadata Logging Macro
 By default, the library creates and stores metadata information (e.g., source location) for each log statement at compile time.
 It is also possible to supply this metadata at runtime along with a log message. While this provides runtime flexibility,
 it introduces some overhead compared to compile-time metadata macros. Therefore, it is recommended to prefer using
-the compile-time metadata macros whenever possible. This runtime option can be particularly useful when forwarding logs
-received from another logging library to Quill.
+the compile-time metadata macros whenever possible. Quill provides three specialized macros for working with runtime metadata, each offering different trade-offs between flexibility and performance:
 
-- :c:macro:`LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, fmt, ...)`
+- :c:macro:`QUILL_LOG_RUNTIME_METADATA_DEEP` - Takes a deep copy of ``fmt``, ``file``, ``function`` and ``tags``. Most flexible option, suitable for forwarding logs from another logging library to Quill.
+
+- :c:macro:`QUILL_LOG_RUNTIME_METADATA_HYBRID` - Takes a deep copy of ``fmt`` and ``tags``, while referencing ``file`` and ``function``. Used for the macro-free mode.
+
+- :c:macro:`QUILL_LOG_RUNTIME_METADATA_SHALLOW` - Takes everything as reference. Most efficient option when using compile-time metadata with dynamic log levels like ``LOG_DYNAMIC``.
+
+Note that ``QUILL_LOG_RUNTIME_METADATA`` is equivalent to ``QUILL_LOG_RUNTIME_METADATA_DEEP`` but without the ``tags`` parameter.

include/quill/LogMacros.h

@@ -964,8 +964,12 @@
     }                                                                                                          \
   } while (0)
 
-#define QUILL_LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, tags, fmt, ...)     \
+#define QUILL_LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, fmt, ...)           \
   QUILL_LOG_RUNTIME_METADATA_CALL(quill::MacroMetadata::Event::LogWithRuntimeMetadataDeepCopy, logger, \
+                                  log_level, file, line_number, function, "", fmt, ##__VA_ARGS__)
+
+#define QUILL_LOG_RUNTIME_METADATA_DEEP(logger, log_level, file, line_number, function, tags, fmt, ...) \
+  QUILL_LOG_RUNTIME_METADATA_CALL(quill::MacroMetadata::Event::LogWithRuntimeMetadataDeepCopy, logger,  \
                                   log_level, file, line_number, function, tags, fmt, ##__VA_ARGS__)
 
 #define QUILL_LOG_RUNTIME_METADATA_HYBRID(logger, log_level, file, line_number, function, tags, fmt, ...) \
@@ -1192,8 +1196,11 @@
   #define LOGJ_CRITICAL_TAGS(logger, tags, fmt, ...)                                               \
     QUILL_LOGJ_CRITICAL_TAGS(logger, tags, fmt, ##__VA_ARGS__)
 
-  #define LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, tags, fmt, ...)     \
-    QUILL_LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, tags, fmt, ##__VA_ARGS__)
+  #define LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, fmt, ...)           \
+    QUILL_LOG_RUNTIME_METADATA(logger, log_level, file, line_number, function, fmt, ##__VA_ARGS__)
+
+  #define LOG_RUNTIME_METADATA_DEEP(logger, log_level, file, line_number, function, tags, fmt, ...) \
+    QUILL_LOG_RUNTIME_METADATA_DEEP(logger, log_level, file, line_number, function, tags, fmt, ##__VA_ARGS__)
 
   #define LOG_RUNTIME_METADATA_HYBRID(logger, log_level, file, line_number, function, tags, fmt, ...) \
     QUILL_LOG_RUNTIME_METADATA_HYBRID(logger, log_level, file, line_number, function, tags, fmt, ##__VA_ARGS__)

test/integration_tests/MacrosTest.cpp

@@ -12,32 +12,30 @@
 #include <string_view>
 #include <vector>
 
-using namespace quill;
-
 /***/
 TEST_CASE("macros")
 {
   static constexpr char const* filename = "macros.log";
   static std::string const logger_name = "logger";
 
-  Backend::start();
+  quill::Backend::start();
 
   // Set writing logging to a file
-  auto file_sink = Frontend::create_or_get_sink<FileSink>(
+  auto file_sink = quill::Frontend::create_or_get_sink<quill::FileSink>(
     filename,
     []()
     {
-      FileSinkConfig cfg;
+      quill::FileSinkConfig cfg;
       cfg.set_open_mode('w');
       return cfg;
     }(),
-    FileEventNotifier{});
+    quill::FileEventNotifier{});
 
-  Logger* logger = Frontend::create_or_get_logger(
+  quill::Logger* logger = quill::Frontend::create_or_get_logger(
     logger_name, std::move(file_sink),
-    PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
-                            "%(log_level_short_code) LOG_%(log_level:<9) "
-                            "%(logger:<12) %(message) [ %(tags)] [%(named_args)]"});
+    quill::PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
+                                   "%(log_level_short_code) LOG_%(log_level:<9) "
+                                   "%(logger:<12) %(message) [ %(tags)] [%(named_args)]"});
   logger->init_backtrace(1, quill::LogLevel::Error);
   logger->set_log_level(quill::LogLevel::TraceL3);
 
@@ -85,14 +83,14 @@ TEST_CASE("macros")
   LOG_BACKTRACE_TAGS(logger, TAGS("tag"), "C BT: {}", 255);
   LOG_DYNAMIC_TAGS(logger, quill::LogLevel::Critical, TAGS("tag"), "C DYN: {}", 420);
 
-  LOG_RUNTIME_METADATA(logger, quill::LogLevel::Info, "MacrosTest.cpp", 1234, "function()", "",
+  LOG_RUNTIME_METADATA(logger, quill::LogLevel::Info, "MacrosTest.cpp", 1234, "function()",
                        "CA INF_{}", 11);
   LOG_RUNTIME_METADATA_SHALLOW(logger, quill::LogLevel::Info, "MacrosTest.cpp", 1234, "function()",
                                "", "CA INF_{}", 0);
   LOG_RUNTIME_METADATA_HYBRID(logger, quill::LogLevel::Debug, "MacrosTest.cpp", 1234, "function()",
                               "", "CA DBG_0");
-  LOG_RUNTIME_METADATA(logger, quill::LogLevel::Debug, "MacrosTest.cpp", 123, "function()", "#TEST",
-                       "CA DBG_21");
+  LOG_RUNTIME_METADATA_DEEP(logger, quill::LogLevel::Debug, "MacrosTest.cpp", 123, "function()",
+                            "#TEST", "CA DBG_21");
 
   int var{1337};
   LOGV_TRACE_L3(logger, "D L3", var);
@@ -180,10 +178,10 @@ TEST_CASE("macros")
   LOGJ_CRITICAL_TAGS(logger, TAGS("tag"), "K CRT", var);
 
   logger->flush_log();
-  Frontend::remove_logger(logger);
+  quill::Frontend::remove_logger(logger);
 
   // Wait until the backend thread stops for test stability
-  Backend::stop();
+  quill::Backend::stop();
 
   // Read file and check
   std::vector<std::string> const file_contents = quill::testing::file_contents(filename);
@@ -414,5 +412,5 @@ TEST_CASE("macros")
   REQUIRE(quill::testing::file_contains(
     file_contents, std::string{"C LOG_CRITICAL  logger       K CRT 1337 [ #tag ] [var: 1337]"}));
 
-  testing::remove_file(filename);
+  quill::testing::remove_file(filename);
 }

test/integration_tests/RuntimeMetadataTest.cpp

@@ -15,7 +15,7 @@ using namespace quill;
 void log_runtime_message(quill::Logger* quill_logger, quill::LogLevel log_level,
                          char const* filename, uint32_t lineno, std::string_view arg)
 {
-  QUILL_LOG_RUNTIME_METADATA(quill_logger, log_level, filename, lineno, "", "", "{}", arg);
+  QUILL_LOG_RUNTIME_METADATA(quill_logger, log_level, filename, lineno, "", "{}", arg);
 }
 
 /***/
@@ -43,17 +43,17 @@ TEST_CASE("runtime_metadata")
       "%(message)"});
 
   LOG_RUNTIME_METADATA(logger, quill::LogLevel::Info, "RuntimeMetadataTest.cpp", 1234, "function_1",
-                       nullptr, "test message");
+                       "{}", "test message");
 
   LOG_RUNTIME_METADATA(logger, quill::LogLevel::Warning, "RuntimeMetadataTest.cpp", 1234,
-                       "function_1", nullptr, "test message");
+                       "function_1", "{}", "test message");
 
   LOG_RUNTIME_METADATA(logger, quill::LogLevel::Info, "RuntimeMetadataTest.cpp", 1234, "foo()",
-                       nullptr, "test message");
+                       "{}", "test message");
 
   LOG_INFO(logger, "standard message {} {}", 123, 456);
 
-  LOG_RUNTIME_METADATA(logger, quill::LogLevel::Info, "app.cpp", 98, "foo()", nullptr,
+  LOG_RUNTIME_METADATA(logger, quill::LogLevel::Info, "app.cpp", 98, "foo()",
                        "Runtime metadata with {} {}", 2, 3);
 
   std::string file_name = "RuntimeMetadataTest.cpp";
@@ -62,7 +62,7 @@ TEST_CASE("runtime_metadata")
   uint32_t a = 1;
   uint32_t b = 2;
   LOG_RUNTIME_METADATA(logger, quill::LogLevel::Info, file_name.data(), line_number,
-                       function_name.data(), nullptr, "a={} and b={}", a, b);
+                       function_name.data(), "a={} and b={}", a, b);
 
   log_runtime_message(logger, quill::LogLevel::Info, "app.cpp", 1234, "test message");