add PatternFormatterOptions

CHANGELOG.md

@@ -98,10 +98,30 @@
   output. To restore the previous behavior, set this option to false when creating a `Logger`
   using `Frontend::create_or_get_logger(...)`. Note that this option is ignored when logging JSON using named arguments
   in the format message. ([#534](https://github.com/odygrd/quill/pull/534))
-- The functions `Frontend::create_or_get_logger(...)` now takes an additional
-  parameter, `add_metadata_to_multi_line_logs`.
 - `JSON` sinks now automatically remove any `\n` characters from format messages, ensuring the emission of valid `JSON`
   messages even when `\n` is present in the format.
+- The `Frontend::create_or_get_logger(...)` function now accepts a `PatternFormatterOptions` parameter, simplifying the
+  API. This is a breaking change. To migrate quickly, wrap the existing formatting parameters in a
+  `PatternFormatterOptions` object.
+
+  **Before:**
+  ```c++
+    quill::Logger* logger =
+      quill::Frontend::create_or_get_logger("root", std::move(file_sink),
+                                            "%(time) [%(thread_id)] %(short_source_location:<28) "
+                                            "LOG_%(log_level:<9) %(logger:<12) %(message)",
+                                            "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+  ```
+
+  **After:**
+
+  ```c++
+    quill::Logger* logger =
+      quill::Frontend::create_or_get_logger("root", std::move(file_sink), quill::PatternFormatterOptions {
+                                            "%(time) [%(thread_id)] %(short_source_location:<28) "
+                                            "LOG_%(log_level:<9) %(logger:<12) %(message)",
+                                            "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
+  ```
 
 ## v6.1.2
 

CMakeLists.txt

@@ -199,6 +199,7 @@ set(HEADER_FILES
         include/quill/core/LogLevel.h
         include/quill/core/MacroMetadata.h
         include/quill/core/MathUtils.h
+        include/quill/core/PatternFormatterOptions.h
         include/quill/core/QuillError.h
         include/quill/core/Rdtsc.h
         include/quill/core/SinkManager.h

benchmarks/backend_throughput/quill_backend_throughput.cpp

@@ -37,8 +37,9 @@ int main()
 
   quill::Logger* logger = quill::Frontend::create_or_get_logger(
     "bench_logger", std::move(file_sink),
-    "%(time) [%(thread_id)] %(short_source_location) %(log_level) %(message)", "%H:%M:%S.%Qns",
-    quill::Timezone::LocalTime, false);
+    quill::PatternFormatterOptions{
+      "%(time) [%(thread_id)] %(short_source_location) %(log_level) %(message)", "%H:%M:%S.%Qns",
+      quill::Timezone::LocalTime, false});
 
   quill::Frontend::preallocate();
 

benchmarks/backend_throughput/quill_backend_throughput_no_buffering.cpp

@@ -38,8 +38,9 @@ int main()
 
   quill::Logger* logger = quill::Frontend::create_or_get_logger(
     "bench_logger", std::move(file_sink),
-    "%(time) [%(thread_id)] %(short_source_location) %(log_level) %(message)", "%H:%M:%S.%Qns",
-    quill::Timezone::LocalTime, false);
+    quill::PatternFormatterOptions{
+      "%(time) [%(thread_id)] %(short_source_location) %(log_level) %(message)", "%H:%M:%S.%Qns",
+      quill::Timezone::LocalTime, false});
   ;
 
   quill::Frontend::preallocate();

benchmarks/compile_time/qwrapper/include/qwrapper/qwrapper.cpp

@@ -11,8 +11,9 @@ void setup_quill(char const* log_file)
 
   auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>("s1");
 
-  quill::Frontend::create_or_get_logger("root", std::move(console_sink),
-                                        "%(time) [%(thread_id)] %(short_source_location:<28) "
+  quill::Frontend::create_or_get_logger(
+    "root", std::move(console_sink),
+    quill::PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
                                         "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                        "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+                                   "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 }

benchmarks/hot_path_latency/quill_hot_path_rdtsc_clock.cpp

@@ -56,8 +56,9 @@ void quill_benchmark(std::vector<uint16_t> const& thread_count_array,
 
   Logger* logger = Frontend::create_or_get_logger(
     "bench_logger", std::move(file_sink),
-    "%(time) [%(thread_id)] %(short_source_location) %(log_level) %(message)", "%H:%M:%S.%Qns",
-    quill::Timezone::LocalTime, false);
+    quill::PatternFormatterOptions{
+      "%(time) [%(thread_id)] %(short_source_location) %(log_level) %(message)", "%H:%M:%S.%Qns",
+      quill::Timezone::LocalTime, false});
 
   /** LOGGING THREAD FUNCTIONS - on_start, on_exit, log_func must be implemented **/
   /** those run on a several thread(s). It can be one or multiple threads based on THREAD_LIST_COUNT config */

benchmarks/hot_path_latency/quill_hot_path_system_clock.cpp

@@ -56,8 +56,10 @@ void quill_benchmark(std::vector<uint16_t> const& thread_count_array,
 
   Logger* logger = Frontend::create_or_get_logger(
     "bench_logger", std::move(file_sink),
-    "%(time) [%(thread_id)] %(short_source_location) %(log_level) %(message)", "%H:%M:%S.%Qns",
-    quill::Timezone::LocalTime, false, quill::ClockSourceType::System);
+    quill::PatternFormatterOptions{
+      "%(time) [%(thread_id)] %(short_source_location) %(log_level) %(message)", "%H:%M:%S.%Qns",
+      quill::Timezone::LocalTime, false},
+    quill::ClockSourceType::System);
 
   /** LOGGING THREAD FUNCTIONS - on_start, on_exit, log_func must be implemented **/
   /** those run on a several thread(s). It can be one or multiple threads based on THREAD_LIST_COUNT config */

docs/examples.rst

@@ -92,9 +92,9 @@ Logging to file
 
       quill::Logger* logger =
         quill::Frontend::create_or_get_logger("root", std::move(file_sink),
-                                              "%(time) [%(thread_id)] %(short_source_location:<28) "
+                                              quill::PatternFormatterOptions { "%(time) [%(thread_id)] %(short_source_location:<28) "
                                               "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                              "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+                                              "%H:%M:%S.%Qns", quill::Timezone::GmtTime });
 
       // set the log level of the logger to debug (default is info)
       logger->set_log_level(quill::LogLevel::Debug);

docs/formatters.rst

@@ -96,6 +96,6 @@ Customizing Log Message Formats
 
   quill::Logger* logger =
     quill::Frontend::create_or_get_logger("root", std::move(sink),
-                                          "%(time) [%(thread_id)] %(short_source_location:<28) "
+                                          quill::PatternFormatterOptions { "%(time) [%(thread_id)] %(short_source_location:<28) "
                                           "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                          "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+                                          "%H:%M:%S.%Qns", quill::Timezone::GmtTime });

docs/json_logging.rst

@@ -30,7 +30,7 @@ Logging Json to Console
 
       // When logging json, it is ideal to set the logging pattern to empty to avoid unnecessary message formatting.
       quill::Logger* logger = quill::Frontend::create_or_get_logger(
-        "json_logger", std::move(json_sink), "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+        "json_logger", std::move(json_sink), quill::PatternFormatterOptions { "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime });
 
       int var_a = 123;
       std::string var_b = "test";
@@ -70,7 +70,7 @@ Logging Json to File
 
       // When logging json, it is ideal to set the logging pattern to empty to avoid unnecessary message formatting.
       quill::Logger* logger = quill::Frontend::create_or_get_logger(
-        "json_logger", std::move(json_sink), "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+        "json_logger", std::move(json_sink), quill::PatternFormatterOptions { "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime });
 
       int var_a = 123;
       std::string var_b = "test";
@@ -117,8 +117,8 @@ Combining JSON and Standard Log Patterns
       // We set a custom format pattern here to also include the named_args
       quill::Logger* hybrid_logger = quill::Frontend::create_or_get_logger(
         "hybrid_logger", {std::move(json_sink), std::move(console_sink)},
-        "%(time) [%(thread_id)] %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<20) "
-        "%(message) [%(named_args)]");
+        quill::PatternFormatterOptions { "%(time) [%(thread_id)] %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<20) "
+        "%(message) [%(named_args)]" });
 
       for (int i = 2; i < 4; ++i)
       {

docs/log_tagging.rst

@@ -41,9 +41,9 @@ To include tags in your log statements, use the `_TAGS` macros. You will also ne
 
       quill::Logger* logger = quill::Frontend::create_or_get_logger(
         "root", std::move(console_sink),
-        "%(time) [%(thread_id)] %(short_source_location:<28) %(log_level:<9) "
+        quill::PatternFormatterOptions { "%(time) [%(thread_id)] %(short_source_location:<28) %(log_level:<9) "
         "%(tags)%(message)",
-        "%Y-%m-%d %H:%M:%S.%Qms", quill::Timezone::GmtTime);
+        "%Y-%m-%d %H:%M:%S.%Qms", quill::Timezone::GmtTime });
 
       LOG_INFO_TAGS(logger, TAGS("random"), "Debug with tags");
       LOG_INFO_TAGS(logger, TAGS(TAG_2), "Info with tags");

docs/sink_types.rst

@@ -98,7 +98,7 @@ The :cpp:class:`quill::JsonFileSink` and :cpp:class:`quill::JsonConsoleSink` ena
 
       // When using the JsonFileSink, it is ideal to set the logging pattern to empty to avoid unnecessary message formatting.
       quill::Logger* json_logger = quill::Frontend::create_or_get_logger(
-        "json_logger", std::move(json_sink), "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+        "json_logger", std::move(json_sink), quill::PatternFormatterOptions { "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime });
 
       for (int i = 0; i < 2; ++i)
       {
@@ -113,8 +113,8 @@ The :cpp:class:`quill::JsonFileSink` and :cpp:class:`quill::JsonConsoleSink` ena
       // We set a custom format pattern here to also include the named_args
       quill::Logger* hybrid_logger = quill::Frontend::create_or_get_logger(
         "hybrid_logger", {std::move(json_sink_2), std::move(console_sink)},
-        "%(time) [%(thread_id)] %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<20) "
-        "%(message) [%(named_args)]");
+        quill::PatternFormatterOptions { "%(time) [%(thread_id)] %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<20) "
+        "%(message) [%(named_args)]" });
 
       for (int i = 0; i < 2; ++i)
       {

docs/timestamp_types.rst

@@ -83,8 +83,8 @@ Providing a Custom Timestamp
       auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1");
       quill::Logger* logger = quill::Frontend::create_or_get_logger(
         "root", std::move(console_sink),
-        "%(time) %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<12) %(message)",
-        "%D %H:%M:%S.%Qns", quill::Timezone::LocalTime, quill::ClockSourceType::User, &simulated_clock);
+        quill::PatternFormatterOptions { "%(time) %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<12) %(message)",
+        "%D %H:%M:%S.%Qns", quill::Timezone::LocalTime }, quill::ClockSourceType::User, &simulated_clock);
 
       // Set our timestamp to Sunday 12 June 2022
       simulated_clock.set_timestamp(std::chrono::seconds{1655007309});
@@ -122,9 +122,9 @@ To achieve this, you can use the :cpp:class:`quill::BackendTscClock`. See the ex
       // Ensure at least one logger with quill::ClockSourceType::Tsc is created for BackendTscClock to function
       quill::Logger* logger = quill::Frontend::create_or_get_logger(
         "root", std::move(console_sink),
-        "%(time) [%(thread_id)] %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<12) "
+        quill::PatternFormatterOptions { "%(time) [%(thread_id)] %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<12) "
         "%(message)",
-        "%H:%M:%S.%Qns", quill::Timezone::LocalTime, quill::ClockSourceType::Tsc);
+        "%H:%M:%S.%Qns", quill::Timezone::LocalTime }, quill::ClockSourceType::Tsc);
 
       // Log an informational message which will also init the backend RdtscClock
       LOG_INFO(logger, "This is a log info example with number {}", 123);

examples/advanced/quill_wrapper/include/quill_wrapper/quill_wrapper.cpp

@@ -14,8 +14,9 @@ void setup_quill(char const* log_file)
   auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>("console_sink");
 
   // Create and store the logger
-  quill::Frontend::create_or_get_logger("root", std::move(console_sink),
-                                        "%(time) [%(thread_id)] %(short_source_location:<28) "
+  quill::Frontend::create_or_get_logger(
+    "root", std::move(console_sink),
+    quill::PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
                                         "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                        "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+                                   "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 }

examples/file_logging.cpp

@@ -44,11 +44,11 @@ int main()
     }(),
     quill::FileEventNotifier{});
 
-  quill::Logger* logger =
-    quill::Frontend::create_or_get_logger("root", std::move(file_sink),
-                                          "%(time) [%(thread_id)] %(short_source_location:<28) "
+  quill::Logger* logger = quill::Frontend::create_or_get_logger(
+    "root", std::move(file_sink),
+    quill::PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
                                           "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                          "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+                                   "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 
   // set the log level of the logger to debug (default is info)
   logger->set_log_level(quill::LogLevel::Debug);

examples/json_console_logging.cpp

@@ -19,7 +19,8 @@ int main()
 
   // When logging json, it is ideal to set the logging pattern to empty to avoid unnecessary message formatting.
   quill::Logger* logger = quill::Frontend::create_or_get_logger(
-    "json_logger", std::move(json_sink), "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+    "json_logger", std::move(json_sink),
+    quill::PatternFormatterOptions{"", "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 
   int var_a = 123;
   std::string var_b = "test";

examples/json_file_logging.cpp

@@ -38,7 +38,8 @@ int main()
 
   // When using the JsonFileSink, it is ideal to set the logging pattern to empty to avoid unnecessary message formatting.
   quill::Logger* json_logger = quill::Frontend::create_or_get_logger(
-    "json_logger", std::move(json_sink), "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+    "json_logger", std::move(json_sink),
+    quill::PatternFormatterOptions{"", "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 
   for (int i = 0; i < 2; ++i)
   {
@@ -53,8 +54,9 @@ int main()
   // We set a custom format pattern here to also include the named_args
   quill::Logger* hybrid_logger = quill::Frontend::create_or_get_logger(
     "hybrid_logger", {std::move(json_sink_2), std::move(console_sink)},
-    "%(time) [%(thread_id)] %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<20) "
-    "%(message) [%(named_args)]");
+    quill::PatternFormatterOptions{
+      "%(time) [%(thread_id)] %(short_source_location:<28) LOG_%(log_level:<9) %(logger:<20) "
+      "%(message) [%(named_args)]"});
 
   for (int i = 2; i < 4; ++i)
   {

examples/recommended_usage/quill_wrapper/include/quill_wrapper/quill_wrapper.cpp

@@ -27,9 +27,9 @@ void setup_quill(char const* log_file)
     quill::FileEventNotifier{});
 
   // Create and store the logger
-  global_logger_a =
-    quill::Frontend::create_or_get_logger("root", std::move(file_sink),
-                                          "%(time) [%(thread_id)] %(short_source_location:<28) "
+  global_logger_a = quill::Frontend::create_or_get_logger(
+    "root", std::move(file_sink),
+    quill::PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
                                           "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                          "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+                                   "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 }

examples/rotating_file_logging.cpp

@@ -31,11 +31,11 @@ int main()
       return cfg;
     }());
 
-  quill::Logger* logger =
-    quill::Frontend::create_or_get_logger("root", std::move(rotating_file_sink),
-                                          "%(time) [%(thread_id)] %(short_source_location:<28) "
+  quill::Logger* logger = quill::Frontend::create_or_get_logger(
+    "root", std::move(rotating_file_sink),
+    quill::PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
                                           "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                          "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+                                   "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 
   for (int i = 0; i < 20; ++i)
   {

examples/shared_library/quill_wrapper_shared/include/quill_wrapper_shared/quill_wrapper_shared.cpp

@@ -17,9 +17,9 @@ void setup_quill()
   auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1");
 
   // Create and store the logger
-  global_logger_a =
-    quill::Frontend::create_or_get_logger("root", std::move(console_sink),
-                                          "%(time) [%(thread_id)] %(short_source_location:<28) "
+  global_logger_a = quill::Frontend::create_or_get_logger(
+    "root", std::move(console_sink),
+    quill::PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
                                           "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                          "%H:%M:%S.%Qns", quill::Timezone::GmtTime);
+                                   "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 }

examples/single_logger_multiple_sink_formats/ConsoleSinkWithFormatter.h

@@ -12,10 +12,9 @@
 class ConsoleSinkWithFormatter : public quill::ConsoleSink
 {
 public:
-  ConsoleSinkWithFormatter(std::string const& format_pattern, std::string const& time_format,
-                           quill::Timezone timestamp_timezone = quill::Timezone::LocalTime,
+  ConsoleSinkWithFormatter(quill::PatternFormatterOptions const& pattern_formater_options,
                            bool enable_colours = true, std::string const& stream = "stdout")
-    : quill::ConsoleSink(enable_colours, stream), _formatter(format_pattern, time_format, timestamp_timezone)
+    : quill::ConsoleSink(enable_colours, stream), _formatter(pattern_formater_options)
   {
   }
 

examples/single_logger_multiple_sink_formats/RotatingFileSinkWithFormatter.h

@@ -13,11 +13,9 @@ class RotatingFileSinkWithFormatter : public quill::RotatingFileSink
 {
 public:
   RotatingFileSinkWithFormatter(quill::fs::path const& filename, quill::RotatingFileSinkConfig const& config,
-                                std::string const& format_pattern, std::string const& time_format,
-                                quill::Timezone timestamp_timezone = quill::Timezone::LocalTime,
+                                quill::PatternFormatterOptions const& pattern_formatter_options,
                                 quill::FileEventNotifier file_event_notifier = quill::FileEventNotifier{})
-    : quill::RotatingFileSink(filename, config, file_event_notifier),
-      _formatter(format_pattern, time_format, timestamp_timezone)
+    : quill::RotatingFileSink(filename, config, file_event_notifier), _formatter(pattern_formatter_options)
   {
   }
 

examples/single_logger_multiple_sink_formats/single_logger_multiple_sink_formats_1.cpp

@@ -38,14 +38,16 @@ int main()
       cfg.set_rotation_max_file_size(1024 * 1024);
       return cfg;
     }(),
-    file_log_pattern, file_time_format);
+    quill::PatternFormatterOptions{file_log_pattern, file_time_format});
+
   rotating_file_sink->set_log_level_filter(quill::LogLevel::Info);
 
   // The Logger is using the console_log_pattern by default
   // To output our custom format to the file we use our own RotatingFileSinkWithFormatter that is
   // overwriting the default format
   quill::Logger* logger = quill::Frontend::create_or_get_logger(
-    "root", {std::move(console_sink), std::move(rotating_file_sink)}, console_log_pattern, console_time_format);
+    "root", {std::move(console_sink), std::move(rotating_file_sink)},
+    quill::PatternFormatterOptions{console_log_pattern, console_time_format});
 
   logger->set_log_level(quill::LogLevel::Debug);