quill

Quill is a header-only library consisting of two main components:

• Frontend: Captures log arguments and metadata from LOG_* statements and places them in a thread-local SPSC (Single Producer Single Consumer) lock-free queue. This ensures no contention between different logging threads.
• Backend: A separate thread spawned by the library that asynchronously consumes messages from all frontend queues, formats them, and writes them to the configured sinks.

Quill uses a split architecture to minimize latency on the hot path:

• Frontend (Caller Thread): Uses a lock-free SPSC queue. LOG_* macros binary-serialize arguments directly into the queue. This avoids shared state, contention, and formatting work on the caller thread.
• Backend (Worker Thread): Drains the SPSC queues, reconstructs log events, performs {fmt} formatting and PatternFormatter processing, and writes to the attached Sinks.

The Quill backend operates using a single dedicated backend thread. This thread is responsible for:

• Formatting log statements.
• Forwarding metric samples.
• Performing I/O operations to files.
• Consuming events from the Single-Producer Single-Consumer (SPSC) queue.
• Retrieving necessary metadata for each event.
• Forwarding formatted log messages or metric samples (via Sink::write_metric) to all Sinks associated with the Logger.

Quill allows publishing metric samples through the same backend worker used for logs. This ensures that hot threads do not pay for metric formatting or export.

Metric-capable sinks (like the bundled PrometheusSink) receive samples via Sink::write_metric. Metric metadata is registered once and reused via pointer on each publish call to keep the hot path compact.

For explicit control over backend options, logger names, sinks, or formatters, use the quill::Backend and quill::Frontend APIs. You must call quill::Backend::start() to initialize the asynchronous backend.

#include "quill/Backend.h"
#include "quill/Frontend.h"
#include "quill/LogMacros.h"
#include "quill/Logger.h"
#include "quill/sinks/ConsoleSink.h"
#include <string_view>

int main()
{
  quill::Backend::start();

  quill::Logger* logger = quill::Frontend::create_or_get_logger(
    "root", quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1"));

  LOG_INFO(logger, "Hello from {}!", std::string_view{"Quill"});
}

To log user-defined types, you must provide formatting and serialization:

• Formatting: Specialize fmtquill::formatter<T> or provide a free format_as(T) function.
• Serialization: Provide quill::Codec<T> or use Quill's helper macros/codecs.

Logging STL Containers: To log containers (like std::vector) containing your custom types, define the formatter/codec for the custom type and include the relevant STL container header from quill/std/.

By default, Quill filters log messages to ensure they contain only printable ASCII characters (space to tilde, plus \n, \t, and \r). Non-printable or non-ASCII characters (like Chinese or Japanese Unicode text) are converted to their hexadecimal representation.

To allow raw UTF-8 or non-ASCII text, disable sanitization by setting check_printable_char to an empty lambda in BackendOptions.

quill::BackendOptions backend_options;
backend_options.check_printable_char = {};  // Disable sanitization
quill::Backend::start(backend_options);

You cannot instantiate quill::Logger objects directly. Instead, you must use the quill::Frontend to create them with a specified name, Sinks, and a Formatter. Once created, the logger's configuration is immutable due to the library's asynchronous design.

To modify a logger (e.g., adding or removing sinks), you must remove the existing logger, wait for its removal, and then recreate it with the same name. Note that a newly created logger will have a different memory address, so you must update any stored Logger* references.

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));

LOG_INFO(logger, "Hello from {}", "library foo");