update docs

Author: apozzer305

docs/backend_options.rst

@@ -3,10 +3,43 @@
 Backend Options
 ===============
 
-The backend options allow you to customize the behavior of the backend thread and are applied at runtime. To utilize these options, you need to create an object and pass it when starting the backend thread. Most options come with default values, but they can be tailored to meet the specific needs of your application. Refer to :cpp:struct:`BackendOptions` for detailed information.
+The backend options allow you to customize the behavior of the backend thread and are applied at runtime. To utilize these options, you need to create an object and pass it when starting the backend thread. Most options come with carefully tuned default values for general use, but they can be adjusted to meet the specific performance and latency requirements of your application. Refer to :cpp:struct:`BackendOptions` for detailed information.
+
+Example Usage
+-------------
 
 For example, to pin the backend worker thread to a specific CPU, you can use the following code:
 
 .. literalinclude:: examples/quill_docs_example_backend_options.cpp
    :language: cpp
    :linenos:
+
+Character Sanitization
+-----------------------
+
+By default, Quill filters log messages to ensure they contain only printable characters before writing them to sinks. This safety feature converts non-printable characters (including non-ASCII characters like Chinese, Japanese, or other Unicode text) to their hexadecimal representation (e.g., ``\xE4\xB8\xAD`` for Chinese characters).
+
+The default printable character range is limited to ASCII characters from space (``' '``) to tilde (``'~'``), plus newline (``'\n'``).
+
+**Disabling Character Sanitization for UTF-8 Logging**
+
+If you need to log UTF-8 or other non-ASCII text (such as Chinese, etc.), you can disable character sanitization:
+
+.. code-block:: cpp
+
+   quill::BackendOptions backend_options;
+   backend_options.check_printable_char = {};  // Disable sanitization
+   quill::Backend::start(backend_options);
+
+**Custom Character Filtering**
+
+You can also define custom printable character rules:
+
+.. code-block:: cpp
+
+   quill::BackendOptions backend_options;
+   backend_options.check_printable_char = [](char c) {
+       // Allow ASCII printable + newline + common UTF-8 byte ranges
+       return (c >= ' ' && c <= '~') || (c == '\n') || (static_cast<unsigned char>(c) >= 128);
+   };
+   quill::Backend::start(backend_options);

docs/cheat_sheet.rst

@@ -190,7 +190,7 @@ Outputs:
 
 Logging Strings Without Additional Copy
 ---------------------------------------
-By default, the logger takes a deep copy of any string. To log an immutable string with a valid lifetime without copying, use ``quill::utility::StringRef``.
+By default, the logger takes a deep copy of any string for thread safety. To log an immutable string with a valid lifetime without copying (e.g., string literals, static strings), use ``quill::utility::StringRef``.
 
 .. code:: cpp
 
@@ -302,7 +302,7 @@ To log user-defined types, you need to define how they should be serialized or c
        - If the type is **not trivially copyable**, it should have both a **copy constructor** and a **move constructor**.
 
     2. **Use DirectFormatCodec**
-       Suitable for objects that are not safe to copy across threads or for cases where formatting occurs in the slow path. This method converts the object to a string immediately in the hot path using `fmt::format`.
+       Suitable for objects that are not safe to copy across threads (e.g., contain raw pointers, references, or non-copyable resources). This method converts the object to a string immediately in the hot path using `fmt::format`, which increases hot-path latency.
 
     3. **Implement a Custom Codec**
        For maximum flexibility, you can define a custom codec to specify exactly how the object should be serialized and deserialized.
@@ -480,7 +480,7 @@ Writing Custom Codec
 Serialising Non Trivially Copyable User Defined Types With Public Members
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Note that it is possible to pass STL types to ``compute_total_encoded_size``, ``encode_members``, and ``decode_members`` as long as the relevant header file from ``quill/std/`` for that type is included.
+Note that STL types can be used in custom codecs by passing them to ``compute_total_encoded_size``, ``encode_members``, and ``decode_members``, provided you include the relevant header from ``quill/std/`` for each STL type used.
 
 .. code:: cpp
 

docs/filters.rst

@@ -9,7 +9,7 @@ Each :cpp:class:`Sink` can be associated with one or multiple :cpp:class:`Filter
 
 By default, a logger sends all log messages to its ``Sinks``. Filters provide a way to intercept and selectively process log records before they are outputted.
 
-A filter is implemented as a callable object that evaluates each log statement and returns a boolean value. This boolean value determines whether the log statement should be forwarded to the ``Sink`` or filtered out.
+A filter is implemented as a callable object that evaluates each log statement on the backend thread and returns a boolean value. When the filter returns ``true``, the log statement is forwarded to the ``Sink``; when ``false``, the log statement is discarded.
 
 Filtering Logs with the Built-In Filter
 ---------------------------------------

docs/formatters.rst

@@ -96,4 +96,90 @@ Customizing Log Message Formats
 
 .. literalinclude:: examples/quill_docs_example_custom_format.cpp
    :language: cpp
-   :linenos:
+   :linenos:
+
+Advanced Pattern Formatter Configuration
+-----------------------------------------
+
+The :cpp:class:`PatternFormatterOptions` class provides additional configuration options beyond the basic format pattern:
+
+**Source Location Path Customization**
+
+You can customize how source file paths are displayed when using the ``%(source_location)`` attribute (full path + line number):
+
+.. code-block:: cpp
+
+   quill::PatternFormatterOptions options;
+   
+   // Strip common path prefixes to shorten source locations
+   options.source_location_path_strip_prefix = "/home/user/project/";
+   // "/home/user/project/src/main.cpp:42" becomes "src/main.cpp:42"
+   
+   // Remove relative path components like "../"
+   options.source_location_remove_relative_paths = true;
+   // "../../src/utils/../main.cpp:15" becomes "src/main.cpp:15"
+
+.. note::
+   These options only affect the ``%(source_location)`` attribute, which shows the full file path. The ``%(short_source_location)`` attribute (filename only + line number) is not affected by these settings.
+
+**Custom Function Name Processing**
+
+By default, the ``%(caller_function)`` attribute shows basic function names. However, you can enable detailed function signatures by defining ``QUILL_DETAILED_FUNCTION_NAME`` before including Quill headers or as a compiler flag:
+
+.. code-block:: cpp
+
+   #define QUILL_DETAILED_FUNCTION_NAME
+   #include "quill/LogMacros.h"
+   
+   // Or compile with: -DQUILL_DETAILED_FUNCTION_NAME
+
+When ``QUILL_DETAILED_FUNCTION_NAME`` is enabled, the logger uses compiler-specific macros (like ``__PRETTY_FUNCTION__``) to provide full function signatures including return types, namespaces, class names, and parameter types. Since these detailed signatures can be verbose and compiler-specific, you can provide a custom processing function to format them:
+
+.. code-block:: cpp
+
+   quill::PatternFormatterOptions options;
+   
+   // Custom function to extract just the function name from detailed signatures
+   options.process_function_name = [](const char* detailed_name) -> std::string_view {
+       // Example: Extract "myFunction" from "void MyClass::myFunction(int, const std::string&)"
+       // Implementation depends on your compiler and requirements
+       std::string_view name(detailed_name);
+       // ... custom parsing logic to extract just the function name ...
+       return name;
+   };
+
+.. note::
+   The ``process_function_name`` callback is only used when ``QUILL_DETAILED_FUNCTION_NAME`` is enabled. Without this define, ``%(caller_function)`` shows simple function names and this callback is ignored.
+
+**Timestamp Configuration**
+
+Control timestamp timezone and format:
+
+.. code-block:: cpp
+
+   quill::PatternFormatterOptions options;
+   
+   // Use GMT timezone instead of local time
+   options.timestamp_timezone = quill::Timezone::GmtTime;
+   
+   // Customize timestamp format (same as strftime + fractional specifiers)
+   options.timestamp_pattern = "%Y-%m-%d %H:%M:%S.%Qms";  // Include date and milliseconds
+
+**Multi-line Message Handling**
+
+Control whether metadata is added to each line of multi-line log messages:
+
+.. code-block:: cpp
+
+   quill::PatternFormatterOptions options;
+   
+   // Disable metadata on continuation lines for cleaner multi-line output
+   options.add_metadata_to_multi_line_logs = false;
+   
+   // With add_metadata_to_multi_line_logs = true (default):
+   // 2024-01-15 10:30:45.123 [1234] main.cpp:42 LOG_INFO     MyLogger Line 1
+   // 2024-01-15 10:30:45.123 [1234] main.cpp:42 LOG_INFO     MyLogger Line 2
+   
+   // With add_metadata_to_multi_line_logs = false:
+   // 2024-01-15 10:30:45.123 [1234] main.cpp:42 LOG_INFO     MyLogger Line 1
+   //                                                                   Line 2

docs/frontend_options.rst

@@ -3,13 +3,13 @@
 Frontend Options
 ================
 
-The frontend options provide a flexible way to configure hot path settings. These options are compile time options and allow for the customisation of queue types, as well as the use of huge pages on Linux systems.
+The frontend options provide a flexible way to configure hot path settings at compile time. These options allow for the customisation of queue types and memory allocation strategies, including the use of huge pages on Linux systems for improved performance.
 
 Each frontend thread operates with its own queue, which can be configured with one of the following options:
 
-- **UnboundedBlocking**: Starts with a small initial capacity. The queue reallocates up to `FrontendOptions::unbounded_queue_max_capacity` and then blocks further log messages.
+- **UnboundedBlocking**: Starts with a small initial capacity. The queue reallocates up to `FrontendOptions::unbounded_queue_max_capacity` and then blocks the calling thread until space becomes available.
 - **UnboundedDropping**: Starts with a small initial capacity. The queue reallocates up to `FrontendOptions::unbounded_queue_max_capacity` and then discards log messages.
-- **BoundedBlocking**: Has a fixed capacity and never reallocates. It blocks log messages when the limit is reached.
+- **BoundedBlocking**: Has a fixed capacity and never reallocates. It blocks the calling thread when the limit is reached until space becomes available.
 - **BoundedDropping**: Has a fixed capacity and never reallocates. It discards log messages when the limit is reached.
 
 Even though each thread has its own queue, a single queue type must be defined for the entire application. By default the `UnboundedBlocking` queue type is used.
@@ -18,6 +18,82 @@ To modify the queue type, you should define your own :cpp:struct:`FrontendOption
 
 It is important to consistently use your custom types throughout the application, instead of the default ones.
 
+Error Notifications
+-------------------
+
+The library provides error notifications through the :cpp:member:`BackendOptions::error_notifier` callback:
+
+- **Unbounded queues**: Notify when queue reallocations occur
+- **Bounded queues**: Notify when messages are dropped due to full queues, including a count of dropped messages
+
+These notifications are processed by the backend thread and can help monitor queue behavior in production.
+
+Queue Memory Management
+-----------------------
+
+**Queue Shrinking**
+
+For unbounded queues, you can explicitly reduce memory usage on specific threads using :cpp:func:`Frontend::shrink_thread_local_queue`. This is particularly useful in thread pool scenarios where some threads may experience logging bursts that cause queue growth, but subsequent tasks don't require the large capacity:
+
+.. code-block:: cpp
+
+    // After a logging-intensive task completes, shrink the queue
+    quill::Frontend::shrink_thread_local_queue(512 * 1024);  // Shrink to 512KB
+
+**Monitoring Queue Allocations**
+
+By default, Quill automatically reports queue allocation events to stderr through :cpp:member:`BackendOptions::error_notifier`. You'll see messages like:
+
+.. code-block:: shell
+
+    Allocated a new SPSC queue with a capacity of 256 KiB (previously 128 KiB) from thread 3764
+
+These allocation messages are informational, not errors, indicating the queue is dynamically resizing to handle traffic spikes. To customize this behavior, you can override the error notifier:
+
+.. code-block:: cpp
+
+    quill::BackendOptions backend_options{
+        .error_notifier = [](const std::string& error_message) {
+            // Custom handling - log to your preferred destination
+            my_logger.info("Quill: {}", error_message);
+        }
+    };
+
+To completely disable these notifications, set the error notifier to an empty function:
+
+.. code-block:: cpp
+
+    quill::BackendOptions backend_options{
+        .error_notifier = {}  // Disable notifications
+    };
+
+**Mixed Hot/Cold Path Optimization**
+
+For applications with both hot path (performance-critical) and cold path (less frequent) logging threads, you can optimize memory allocation by using a larger initial queue size globally, then selectively shrinking queues on cold path threads:
+
+.. code-block:: cpp
+
+    // Configure large initial capacity to avoid hot path allocations
+    struct MyFrontendOptions : quill::FrontendOptions 
+    {
+        static constexpr size_t initial_queue_capacity = 64 * 1024 * 1024;  // 64MB
+        // ... other options
+    };
+    
+    // Hot path threads: Use the large queue (no shrinking needed)
+    // LOG_INFO(hot_path_logger, "High frequency logging...");
+    
+    // Cold path threads: Shrink to smaller size after initialization
+    void cold_path_thread_init() {
+        quill::Frontend::shrink_thread_local_queue(128 * 1024);  // Shrink to 128KB
+        // LOG_INFO(cold_path_logger, "Infrequent logging...");
+    }
+
+This approach prevents runtime allocations on performance-critical threads while conserving memory on threads with lighter logging workloads.
+
+Example Usage
+-------------
+
 For example, to use a `BoundedDropping` queue with a fixed capacity of `131'072`, you can follow the steps below:
 
 .. literalinclude:: ../examples/custom_frontend_options.cpp

docs/json_logging.rst

@@ -3,7 +3,7 @@
 JSON Logging
 ============
 
-The library supports outputting JSON-structured logs to either the console or a file. To utilize this feature, you need to use named arguments within the format string, specifically inside the ``{}`` placeholders, when invoking the ``LOG_`` macros.
+The library supports outputting structured JSON logs to either the console or a file. To utilize this feature, you must use named arguments within the format string placeholders (e.g., ``{name}`` instead of ``{}``) when invoking the ``LOG_`` macros.
 
 For convenience, the ``LOGJ_`` macros offer an alternative method for logging l-values, automatically including the argument names in the placeholders. These macros support up to 20 arguments.
 

docs/log_tagging.rst

@@ -3,7 +3,7 @@
 Log Tagging
 ===========
 
-In addition to creating multiple `Logger` instances, each with a unique name, which can be used as a runtime tag to filter and search logs using `%(logger)` in the `PatternFormatter` format, you can also add static compile-time tags to your log messages. This enhances your ability to search, monitor, categorize, and understand events in your software.
+In addition to creating multiple `Logger` instances, each with a unique name, you can add static compile-time tags to your log messages. These tags are embedded directly into the log message format at compile time, providing zero runtime overhead for categorization. This enhances your ability to search, monitor, categorize, and understand events in your software.
 
 These static tags are included as hashtag-style keywords within your log messages, making it easier to filter and categorize logs based on these predefined tags.
 

docs/overview.rst

@@ -41,11 +41,11 @@ using :cpp:func:`LoggerImpl::flush_log`. The calling thread will **block** until
 Synchronized Logs for Debugging
 -------------------------------
 
-Sometimes, synchronized logging is necessary during application debugging. This can be achieved by configuring the logger to invoke :cpp:func:`LoggerImpl::flush_log` with each log statement using the `QUILL_IMMEDIATE_FLUSH` preprocessor variable.
+Sometimes, synchronized logging is necessary during application debugging. This can be achieved by calling :cpp:func:`LoggerImpl::set_immediate_flush` to enable immediate flushing for a specific logger instance.
 
-Enabling `QUILL_IMMEDIATE_FLUSH` causes the calling thread to pause until the log is processed and written to the log file by the backend thread before proceeding, which may have a notable impact on performance.
+This causes the calling thread to pause until the log is processed and written to the log file by the backend thread before proceeding, which may have a notable impact on performance.
 
-To enable this behavior, define `QUILL_IMMEDIATE_FLUSH` before including `LogMacros.h` or pass it as a compiler flag.
+Note that the immediate flush feature can be completely disabled at compile time by defining `QUILL_ENABLE_IMMEDIATE_FLUSH=0`, which eliminates the conditional branch from the hot path for better performance when immediate flushing is never needed.
 
 Handling Application Crashes
 ----------------------------

docs/quick_start.rst

@@ -5,9 +5,9 @@ Quick Start
 
 The library is header only and consists of two main components: the frontend and the backend.
 
-The **frontend** captures a copy of the log arguments and metadata from each ``LOG_*`` statement and places them in a thread-local SPSC queue buffer.
+The **frontend** captures a copy of the log arguments and metadata from each ``LOG_*`` statement and places them in a thread-local SPSC (Single Producer Single Consumer) queue buffer. Each frontend thread has its own lock-free queue, ensuring no contention between logging threads.
 
-The **backend** runs in a separate thread, spawned by the library, asynchronously consuming messages from the frontend, formatting them, and writing them to the configured sinks.
+The **backend** runs in a separate thread, spawned by the library, asynchronously consuming messages from all frontend queues, formatting them, and writing them to the configured sinks.
 
 To use the library, you need to start the backend thread in your application. Then, set up one or more output ``Sinks`` and a ``Logger``.
 

docs/sink_types.rst

@@ -49,6 +49,26 @@ SyslogSink
 
 The :cpp:class:`SyslogSink` leverages the syslog API to send messages.
 
+SystemdSink
+~~~~~~~~~~~
+
+The :cpp:class:`SystemdSink` sends log messages to systemd's journal using the systemd journal API, providing structured logging with systemd metadata.
+
+StreamSink
+~~~~~~~~~~
+
+The :cpp:class:`StreamSink` allows logging to any output stream derived from `std::ostream`, providing flexibility for custom output destinations.
+
+AndroidSink
+~~~~~~~~~~~
+
+The :cpp:class:`AndroidSink` sends log messages to the Android logging system using the Android NDK logging API.
+
+NullSink
+~~~~~~~~
+
+The :cpp:class:`NullSink` discards all log messages, useful for performance testing or disabling specific logger output without removing logging calls.
+
 .. note:: Macro Collision Notice
 
    When including ``syslog.h`` via :cpp:class:`SyslogSink`, the header defines macros such as ``LOG_INFO``