v8

CHANGELOG.md

@@ -1,3 +1,4 @@
+- [v8.0.0](#v800)
 - [v7.5.0](#v750)
 - [v7.4.0](#v740)
 - [v7.3.0](#v730)
@@ -80,6 +81,21 @@
 - [v1.1.0](#v110)
 - [v1.0.0](#v100)
 
+## v8.0.0
+
+- Unified `JsonFileSink.h` and `JsonConsoleSink.h` into a single header, `JsonSink.h`, with both classes now sharing a
+  common implementation
+- Users can now inherit from `JsonFileSink` or `JsonConsoleSink` and override the `generate_json_message(...)` function
+  to implement their own custom JSON log formats
+- Removed `JsonFileSinkConfig`. Please rename it to `FileSinkConfig`, which retains the same API and is fully
+  compatible.
+- Added `RotatingJsonFileSink`. Functions like `RotatingFileSink`, but specifically designed for rotating JSON log
+  files.
+- Simplified `ConsoleSink` by applying ANSI colour codes universally across all platforms, including Windows. The
+  previous Windows-specific implementation has been removed. Note that `quill::ConsoleColours` has been replaced with
+  `quill::ConsoleSink::Colours`, and `quill::ConsoleColours::ColourMode` has been renamed to
+  `quill::ConsoleSink::ColourMode`.
+
 ## TBD
 
 - Suppress `-Wredundant-decls` warning in GCC builds.
@@ -112,7 +128,7 @@
 - Fixed a build issue when compiling with `-fno-rtti`. This ensures compatibility with projects that disable
   `RTTI`. ([#604](https://github.com/odygrd/quill/issues/604))
 - Fixed an incorrectly triggered assertion in debug builds when `BackendOptions::log_timestamp_ordering_grace_period` is
-  set to 0. ([#605](https://github.com/odygrd/quill/issues/605))
+  set to 0 ([#605](https://github.com/odygrd/quill/issues/605))
 - Fixed a compile-time error in `CsvWriter` that occurred when passing a custom `FrontendOptions` type as a template
   parameter. ([#609](https://github.com/odygrd/quill/issues/609))
 - Added accessors to `Logger` for sinks, user clock source, clock source type, and pattern formatter options that can be
@@ -125,6 +141,7 @@
   ```cpp
     quill::Frontend::create_or_get_sink<quill::ConsoleSink>(
       "sink_id_1", quill::ConsoleColours::ColourMode::Automatic);
+   ```
 
 ## v7.3.0
 

CMakeLists.txt

@@ -216,10 +216,11 @@ set(HEADER_FILES
 
         include/quill/sinks/ConsoleSink.h
         include/quill/sinks/FileSink.h
-        include/quill/sinks/JsonConsoleSink.h
-        include/quill/sinks/JsonFileSink.h
+        include/quill/sinks/JsonSink.h
         include/quill/sinks/NullSink.h
         include/quill/sinks/RotatingFileSink.h
+        include/quill/sinks/RotatingJsonFileSink.h
+        include/quill/sinks/RotatingSink.h
         include/quill/sinks/Sink.h
         include/quill/sinks/StreamSink.h
 

MODULE.bazel

@@ -1,6 +1,6 @@
 module(
     name = "quill",
-    version = "7.5.0",
+    version = "8.0.0",
     compatibility_level = 1,
 )
 

docs/conf.py

@@ -35,7 +35,7 @@ def configureDoxyfile(input_dir, output_dir):
 project = 'Quill'
 copyright = '2024, Odysseas Georgoudis'
 author = 'Odysseas Georgoudis'
-release = 'v7.5.0'
+release = 'v8.0.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/json_logging.rst

@@ -18,7 +18,7 @@ Logging Json to Console
     #include "quill/Frontend.h"
     #include "quill/LogMacros.h"
     #include "quill/Logger.h"
-    #include "quill/sinks/JsonConsoleSink.h"
+    #include "quill/sinks/JsonSink.h"
     #include <string>
 
     int main()
@@ -28,7 +28,8 @@ Logging Json to Console
 
       auto json_sink = quill::Frontend::create_or_get_sink<quill::JsonConsoleSink>("json_sink_1");
 
-      // When logging json, it is ideal to set the logging pattern to empty to avoid unnecessary message formatting.
+      // PatternFormatter is only used for non-structured logs formatting
+      // When logging only 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), quill::PatternFormatterOptions { "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime });
 
@@ -51,7 +52,7 @@ Logging Json to File
     #include "quill/Frontend.h"
     #include "quill/LogMacros.h"
     #include "quill/Logger.h"
-    #include "quill/sinks/JsonFileSink.h"
+    #include "quill/sinks/JsonSink.h"
     #include <string>
 
     int main()
@@ -68,7 +69,8 @@ Logging Json to File
                                                                                   return config;
                                                                                 }());
 
-      // When logging json, it is ideal to set the logging pattern to empty to avoid unnecessary message formatting.
+      // PatternFormatter is only used for non-structured logs formatting
+      // When logging only 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), quill::PatternFormatterOptions { "", "%H:%M:%S.%Qns", quill::Timezone::GmtTime });
 
@@ -82,6 +84,74 @@ Logging Json to File
       LOG_INFO(logger, "A json message with {var_1} and {var_2}", var_a, var_b);
     }
 
+Customising Json Format
+-----------------------
+
+To customize the JSON format, define a custom sink that derives from one of the following classes:
+
+- :cpp:class:`JsonFileSink`
+- :cpp:class:`JsonConsoleSink`
+- :cpp:class:`RotatingJsonFileSink`
+
+.. code:: cpp
+
+    #include "quill/Backend.h"
+    #include "quill/Frontend.h"
+    #include "quill/LogMacros.h"
+    #include "quill/Logger.h"
+    #include "quill/sinks/JsonSink.h"
+
+    class MyJsonConsoleSink : public quill::JsonConsoleSink
+    {
+      void generate_json_message(quill::MacroMetadata const* /** log_metadata **/, uint64_t log_timestamp,
+                                 std::string_view /** thread_id **/, std::string_view /** thread_name **/,
+                                 std::string const& /** process_id **/, std::string_view /** logger_name **/,
+                                 quill::LogLevel /** log_level **/, std::string_view log_level_description,
+                                 std::string_view /** log_level_short_code **/,
+                                 std::vector<std::pair<std::string, std::string>> const* named_args,
+                                 std::string_view /** log_message **/,
+                                 std::string_view /** log_statement **/, char const* message_format) override
+      {
+        // format json as desired
+        _json_message.append(fmtquill::format(R"({{"timestamp":"{}","log_level":"{}","message":"{}")",
+                                              std::to_string(log_timestamp), log_level_description, message_format));
+
+        // add log statement arguments as key-values to the json
+        if (named_args)
+        {
+          for (auto const& [key, value] : *named_args)
+          {
+            _json_message.append(std::string_view{",\""});
+            _json_message.append(key);
+            _json_message.append(std::string_view{"\":\""});
+            _json_message.append(value);
+            _json_message.append(std::string_view{"\""});
+          }
+        }
+      }
+    };
+
+    int main()
+    {
+      // Start the backend thread
+      quill::BackendOptions backend_options;
+      quill::Backend::start(backend_options);
+
+      // Frontend
+      auto json_sink = quill::Frontend::create_or_get_sink<MyJsonConsoleSink>("json_sink_1");
+
+      // PatternFormatter is only used for non-structured logs formatting
+      // When logging only 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),
+        quill::PatternFormatterOptions{"", "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
+
+      int var_a = 123;
+      std::string var_b = "test";
+
+      LOG_INFO(logger, "A json message with {var_1} and {var_2}", var_a, var_b);
+    }
+
 Combining JSON and Standard Log Patterns
 ----------------------------------------
 
@@ -92,7 +162,7 @@ Combining JSON and Standard Log Patterns
     #include "quill/LogMacros.h"
     #include "quill/Logger.h"
     #include "quill/sinks/ConsoleSink.h"
-    #include "quill/sinks/JsonFileSink.h"
+    #include "quill/sinks/JsonSink.h"
     #include <utility>
 
     int main()
@@ -105,7 +175,7 @@ Combining JSON and Standard Log Patterns
         "example_json.log",
         []()
         {
-          quill::JsonFileSinkConfig cfg;
+          quill::FileSinkConfig cfg;
           cfg.set_open_mode('w');
           cfg.set_filename_append_option(quill::FilenameAppendOption::None);
           return cfg;

docs/sink_types.rst

@@ -89,7 +89,7 @@ The :cpp:class:`JsonFileSink` and :cpp:class:`JsonConsoleSink` enable the creati
         "json_sink_logging.log",
         []()
         {
-          quill::JsonFileSinkConfig cfg;
+          quill::FileSinkConfig cfg;
           cfg.set_open_mode('w');
           cfg.set_filename_append_option(quill::FilenameAppendOption::StartDateTime);
           return cfg;
@@ -119,4 +119,9 @@ The :cpp:class:`JsonFileSink` and :cpp:class:`JsonConsoleSink` enable the creati
       for (int i = 0; i < 2; ++i)
       {
         LOG_INFO(hybrid_logger, "{method} to {endpoint} took {elapsed} ms", "POST", "http://", 10 * i);
-      }
+      }
+
+RotatingJsonFileSink
+~~~~~~~~~~~~~~~~~~~~
+
+The :cpp:class:`RotatingJsonFileSink` is built on top of the `JsonFileSink` and provides log file rotation based on specified time intervals, file sizes, or daily schedules.

docs/users-api.rst

@@ -86,6 +86,12 @@ FileSink Class
 .. doxygenclass:: FileSink
    :members:
 
+RotatingSink Class
+----------------------------
+
+.. doxygenclass:: RotatingSink
+   :members:
+
 RotatingFileSinkConfig Class
 ----------------------------
 
@@ -110,6 +116,12 @@ JsonConsoleSink Class
 .. doxygenclass:: JsonConsoleSink
    :members:
 
+RotatingJsonFileSink Class
+----------------------------
+
+.. doxygenclass:: RotatingJsonFileSink
+   :members:
+
 CsvWriter Class
 ---------------
 

examples/CMakeLists.txt

@@ -12,6 +12,8 @@ set(EXAMPLE_TARGETS
         quill_example_console_logging
         quill_example_custom_console_colours
         quill_example_rotating_file_logging
+        quill_example_rotating_json_file_logging
+        quill_example_rotating_json_file_logging_custom_json
         quill_example_signal_handler
         quill_example_logger_removal_with_file_event_notifier
         quill_example_custom_frontend_options
@@ -23,6 +25,7 @@ set(EXAMPLE_TARGETS
         quill_example_user_defined_sink
         quill_example_tags_logging
         quill_example_json_console_logging
+        quill_example_json_console_logging_custom_json
         quill_example_csv_writing
         quill_example_json_file_logging
         quill_example_user_defined_types_logging

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

@@ -17,6 +17,6 @@ void setup_quill(char const* log_file)
   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)",
+                                   "LOG_%(log_level:<9) %(logger:<12) %(message)",
                                    "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 }

examples/backend_tsc_clock.cpp

@@ -52,7 +52,7 @@ int main()
   auto const tsc_start_seconds = std::chrono::duration_cast<std::chrono::seconds>(
                                    quill::BackendTscClock::to_time_point(tsc_start).time_since_epoch())
                                    .count();
-  
+
   auto const tsc_end_seconds = std::chrono::duration_cast<std::chrono::seconds>(
                                  quill::BackendTscClock::to_time_point(tsc_end).time_since_epoch())
                                  .count();

examples/console_logging.cpp

@@ -25,7 +25,7 @@ int main()
 
   // Frontend
   auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>(
-    "sink_id_1", quill::ConsoleColours::ColourMode::Automatic);
+    "sink_id_1", quill::ConsoleSink::ColourMode::Automatic);
 
   quill::Logger* logger = quill::Frontend::create_or_get_logger("root", std::move(console_sink));
 

examples/custom_console_colours.cpp

@@ -18,13 +18,12 @@ int main()
   quill::Backend::start(backend_options);
 
   // Frontend
-  quill::ConsoleColours custom_console_colours;
-  custom_console_colours.set_default_colours();
-  custom_console_colours.set_colour(quill::LogLevel::Info, quill::ConsoleColours::blue); // overwrite the colour for INFO
+  quill::ConsoleSink::Colours colours;
+  colours.apply_default_colours();
+  colours.assign_colour_to_log_level(quill::LogLevel::Info, quill::ConsoleSink::Colours::blue); // overwrite the colour for INFO
 
   // Create the sink
-  auto console_sink =
-    quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1", custom_console_colours);
+  auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1", colours);
 
   quill::Logger* logger = quill::Frontend::create_or_get_logger("root", std::move(console_sink));
 

examples/file_logging.cpp

@@ -47,7 +47,7 @@ int main()
   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)",
+                                   "LOG_%(log_level:<9) %(logger:<12) %(message)",
                                    "%H:%M:%S.%Qns", quill::Timezone::GmtTime});
 
   // set the log level of the logger to debug (default is info)

examples/json_console_logging.cpp

@@ -2,7 +2,7 @@
 #include "quill/Frontend.h"
 #include "quill/LogMacros.h"
 #include "quill/Logger.h"
-#include "quill/sinks/JsonConsoleSink.h"
+#include "quill/sinks/JsonSink.h"
 
 #include <string>
 
@@ -16,8 +16,9 @@ int main()
 
   // Create a json sink
   auto json_sink = quill::Frontend::create_or_get_sink<quill::JsonConsoleSink>("json_sink_1");
-
-  // When logging json, it is ideal to set the logging pattern to empty to avoid unnecessary message formatting.
+
+  // PatternFormatter is only used for non-structured logs formatting
+  // When logging only 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),
     quill::PatternFormatterOptions{"", "%H:%M:%S.%Qns", quill::Timezone::GmtTime});