Repository files navigation

Quill

Asynchronous Low Latency C++ Logging Library

📚 Documentation ·⚡ Cheat Sheet ·🐛 Report Bug ·💡 Request Feature

• Introduction
• Quick Start
• Features
• Performance
• Usage
• Design
• Caveats
• License

Quill is ahigh-performance asynchronous logging library written inC++. It is designed for low-latency, performance-critical applications where every microsecond counts.

• Performance-Focused: Quill consistently outperforms many popular logging libraries.
• Feature-Rich: Packed with advanced features to meet diverse logging needs.
• Battle-Tested: Proven in demanding production environments.
• Extensive Documentation: Comprehensive guides and examples available.
• Community-Driven: Open to contributions, feedback, and feature requests.

Try it onCompiler Explorer

Getting started is easy and straightforward. Follow these steps to integrate the library into your project:

You can install Quill using the package manager of your choice:

Once installed, you can start using Quill with the following code:

#include"quill/Backend.h"#include"quill/Frontend.h"#include"quill/LogMacros.h"#include"quill/Logger.h"#include"quill/sinks/ConsoleSink.h"#include<string_view>intmain(){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"});}

• High-Performance: Ultra-low latency performance. ViewBenchmarks
• Asynchronous Processing: Background thread handles formatting and I/O, keeping your main thread responsive.
• Minimal Header Includes:
  • Frontend: OnlyLogger.h andLogMacros.h needed for logging. Lightweight with minimal dependencies.
  • Backend: Single.cpp file inclusion. No backend code injection into other translation units.
• Compile-Time Optimization: Eliminate specific log levels at compile time.
• Custom Formatters: Define your own log output patterns.SeeFormatters.
• Timestamp-Ordered Logs: Simplify debugging of multithreaded applications with chronologically ordered logs.
• Flexible Timestamps: Support forrdtsc,chrono, orcustom clocks - ideal for simulations and more.
• Backtrace Logging: Store messages in a ring buffer for on-demand display.SeeBacktrace Logging
• Multiple Output Sinks: Console (with color), files (with rotation), JSON, ability to create custom sinks and more.
• Log Filtering: Process only relevant messages.SeeFilters.
• JSON Logging: Structured log output.SeeJSON Logging
• Configurable Queue Modes:bounded/unbounded andblocking/dropping options with monitoring on dropped messages,queue reallocations, and blocked hot threads.
• Crash Handling: Built-in signal handler for log preservation during crashes.
• Huge Pages Support (Linux): Leverage huge pages on the hot path for optimized performance.
• Wide Character Support (Windows): Compatible with ASCII-encoded wide strings and STL containers consisting of widestrings.
• Exception-Free Option: Configurable builds with or without exception handling.
• Clean Codebase: Maintained to high standards, warning-free even at strict levels.
• Type-Safe API: Built on{fmt} library.

• OS: Linux RHEL 9.4

• CPU: Intel Core i5-12600 (12th Gen) @ 4.8 GHz

• Compiler: GCC 13.1

• Benchmark-Tuned System: The system is specifically tuned for benchmarking.

• Command Line Parameters:

  $ cat /proc/cmdlineBOOT_IMAGE=(hd0,gpt2)/vmlinuz-5.14.0-427.13.1.el9_4.x86_64 root=/dev/mapper/rhel-root ro crashkernel=1G-4G:192M,4G-64G:256M,64G-:512M resume=/dev/mapper/rhel-swap rd.lvm.lv=rhel/root rd.lvm.lv=rhel/swap rhgb quiet nohz=on nohz_full=1-5 rcu_nocbs=1-5 isolcpus=1-5 mitigations=off transparent_hugepage=never intel_pstate=disable nosoftlockup irqaffinity=0 processor.max_cstate=1 nosoftirqd sched_tick_offload=0 spec_store_bypass_disable=off spectre_v2=off iommu=pt

You can find the benchmark code on thelogger_benchmarks repository.

The results presented in the tables below are measured innanoseconds (ns).

The tables are sorted by the 95th percentile

LOG_INFO(logger, "Logging int: {}, int: {}, double: {}", i, j, d).

Loggingstd::string over 35 characters to prevent the short string optimization.

LOG_INFO(logger, "Logging int: {}, int: {}, string: {}", i, j, large_string).

Loggingstd::vector<std::string> containing 16 large strings, each ranging from 50 to 60 characters.

Note: some of the previous loggers do not support passing astd::vector as an argument.

LOG_INFO(logger, "Logging int: {}, int: {}, vector: {}", i, j, v).

The benchmark methodology involves logging 20 messages in a loop, calculating and storing the average latency for those20 messages, then waiting around ~2 milliseconds, and repeating this process for a specified number of iterations.

In theQuill Bounded Dropping benchmarks, the dropping queue size is set to262,144 bytes, which is double thedefault size of131,072 bytes.

Throughput is measured by calculating the maximum number of log messages the backend logging thread can write to a logfile per second.

The tests were run on the same system used for the latency benchmarks.

Although Quill’s primary focus is not on maximizing throughput, it efficiently manages log messages across multiplethreads. Benchmarking throughput of asynchronous logging libraries presents certain challenges. Some libraries may droplog messages, leading to smaller-than-expected log files, while others only provide asynchronous flushing, making itdifficult to verify when the backend thread has fully processed all messages.

For comparison, we benchmark against other asynchronous logging libraries that offer guaranteed logging with aflush-and-wait mechanism.

Note thatMS BinLog writes log data to a binary file, which requires offline formatting with an additionalprogram—this makes it an unfair comparison, but it is included for reference.

Similarly,BqLog (binary log) uses the compressed binary log appender, and its log files are not human-readable unlessprocessed offline. However, it is included for reference. The other version ofBqLog is using a text appender andproduces human-readable log files.

In the same way,Platformlab Nanolog also outputs binary logs and is expected to deliver high throughput. However, forreasons unexplained, the benchmark runs significantly slower (10x longer) than the other libraries, so it is excludedfrom the table.

Logging 4 million times the message"Iteration: {} int: {} double: {}"

Compile times are measured usingclang 15 and forRelease build.

Below, you can find the additional headers that the library will include when you need to log, followingtherecommended_usageexample

There is also a compile-time benchmark measuring the compilation time of 2000 auto-generated log statements withvarious arguments. You can findithere. It takesapproximately 30 seconds to compile.

Quill excels in hot path latency benchmarks and supports high throughput, offering a rich set of features that outshinesother logging libraries.

The human-readable log files facilitate easier debugging and analysis. While initially larger, they compressefficiently, with the size difference between human-readable and binary logs becoming minimal once zipped.

For example, for the same amount of messages:

ms_binlog_backend_total_time.blog (binary log): 177 MBms_binlog_backend_total_time.zip (zipped binary log): 35 MB

quill_backend_total_time.log (human-readable log): 448 MBquill_backend_total_time.zip (zipped human-readable log): 47 MB

If Quill were not available, MS BinLog would be a strong alternative. It delivers great latency on the hot path andgenerates smaller binary log files. However, the binary logs necessitate offline processing with additional tools, whichcan be less convenient.

Also, see theQuick Start Guide for a brief introduction.

#include"quill/Backend.h"#include"quill/Frontend.h"#include"quill/LogMacros.h"#include"quill/Logger.h"#include"quill/sinks/ConsoleSink.h"#include"quill/std/Array.h"#include<string>#include<utility>intmain(){// Backend  quill::BackendOptions backend_options;quill::Backend::start(backend_options);// Frontendauto 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));// Change the LogLevel to print everything  logger->set_log_level(quill::LogLevel::TraceL3);// A log message with number 123int a =123;  std::string l ="log";LOG_INFO(logger,"A {} message with number {}", l, a);// libfmt formatting language is supported 3.14e+00doublepi =3.141592653589793;LOG_INFO(logger,"libfmt formatting language is supported {:.2e}",pi);// Logging STD types is supported [1, 2, 3]  std::array<int,3> arr = {1,2,3};LOG_INFO(logger,"Logging STD types is supported {}", arr);// Logging STD types is supported [arr: [1, 2, 3]]LOGV_INFO(logger,"Logging STD types is supported", arr);// A message with two variables [a: 123, b: 3.17]double b =3.17;LOGV_INFO(logger,"A message with two variables", a, b);for (uint32_t i =0; i <10; ++i)  {// Will only log the message once per secondLOG_INFO_LIMIT(std::chrono::seconds{1}, logger,"A {} message with number {}", l, a);LOGV_INFO_LIMIT(std::chrono::seconds{1}, logger,"A message with two variables", a, b);  }LOG_TRACE_L3(logger,"Support for floats {:03.2f}",1.23456);LOG_TRACE_L2(logger,"Positional arguments are {1} {0}","too","supported");LOG_TRACE_L1(logger,"{:>30}", std::string_view {"right aligned"});LOG_DEBUG(logger,"Debugging foo {}",1234);LOG_INFO(logger,"Welcome to Quill!");LOG_WARNING(logger,"A warning message.");LOG_ERROR(logger,"An error message. error code {}",123);LOG_CRITICAL(logger,"A critical error.");}

To get started with Quill, clone the repository and install it using CMake:

git clone http://github.com/odygrd/quill.gitmkdir cmake_buildcd cmake_buildcmake ..make install

• Custom Installation: Specify a custom directory with-DCMAKE_INSTALL_PREFIX=/path/to/install/dir.
• Build Examples: Include examples with-DQUILL_BUILD_EXAMPLES=ON.

Next, add Quill to your project usingfind_package():

find_package(quill REQUIRED)target_link_libraries(your_targetPUBLIC quill::quill)

Organize your project directory like this:

my_project/├── CMakeLists.txt├── main.cpp

Here’s a sampleCMakeLists.txt to get you started:

# If Quill is in a non-standard directory, specify its path.set(CMAKE_PREFIX_PATH /path/to/quill)# Find and link the Quill library.find_package(quill REQUIRED)add_executable(example main.cpp)target_link_libraries(examplePUBLIC quill::quill)

For a more integrated approach, embed Quill directly into your project:

my_project/├── quill/            # Quill repo folder├── CMakeLists.txt├── main.cpp

Use thisCMakeLists.txt to include Quill directly:

cmake_minimum_required(VERSION 3.1.0)project(my_project)set(CMAKE_CXX_STANDARD 17)set(CMAKE_CXX_STANDARD_REQUIREDON)add_subdirectory(quill)add_executable(my_project main.cpp)target_link_libraries(my_projectPUBLIC quill::quill)

When building Quill for Android, you might need to add this flag during configuration, but in most cases, it works without it:

-DQUILL_NO_THREAD_NAME_SUPPORT:BOOL=ON

For timestamps, usequill::ClockSourceType::System. Quill also includes anAndroidSink, which integrates with Android's logging system.

quill::Backend::start();auto sink = quill::Frontend::create_or_get_sink<quill::AndroidSink>("app", [](){    quill::AndroidSinkConfig asc;    asc.set_tag("app");    asc.set_format_message(true);return asc;}());auto logger = quill::Frontend::create_or_get_logger("root", std::move(sink),                                                    quill::PatternFormatterOptions {},                                                     quill::ClockSourceType::System);LOG_INFO(logger,"Test {}",123);

Easily integrate Quill with Meson’swrapdb:

meson wrap install quill

Copy the repository contents to yoursubprojects directory and add the following to yourmeson.build:

quill=subproject('quill')quill_dep= quill.get_variable('quill_dep')my_build_target=executable('name','main.cpp',dependencies: [quill_dep],install:true)

Quill is available onBLZMOD for easy integration.

For manual setup, add Quill to yourBUILD.bazel file like this:

cc_binary(name="app",srcs= ["main.cpp"],deps= ["//quill_path:quill"])

When invoking aLOG_ macro:

1. Creates a static constexpr metadata object to storeMetadata such as the format string and source location.

2. Pushes the data SPSC lock-free queue. For each log message, the following variables are pushed

Consumes each message from the SPSC queue, retrieves all the necessary information and then formats the message.Subsequently, forwards the log message to all Sinks associated with the Logger.

Quill may not work well withfork() since it spawns a background thread andfork() doesn't work well withmultithreading.

If your application usesfork() and you want to log in the child processes as well, you should callquill::start()after thefork() call. Additionally, you should ensure that you write to different files in the parent and childprocesses to avoid conflicts.

For example :

#include"quill/Backend.h"#include"quill/Frontend.h"#include"quill/LogMacros.h"#include"quill/Logger.h"#include"quill/sinks/FileSink.h"intmain(){// DO NOT CALL THIS BEFORE FORK// quill::Backend::start();if (fork() ==0)  {quill::Backend::start();// Get or create a handler to the file - Write to a different fileauto file_sink = quill::Frontend::create_or_get_sink<quill::FileSink>("child.log");        quill::Logger* logger =quill::Frontend::create_or_get_logger("root",std::move(file_sink));QUILL_LOG_INFO(logger,"Hello from Child {}",123);  }else  {quill::Backend::start();// Get or create a handler to the file - Write to a different fileauto file_sink = quill::Frontend::create_or_get_sink<quill::FileSink>("parent.log");        quill::Logger* logger =quill::Frontend::create_or_get_logger("root",std::move(file_sink));QUILL_LOG_INFO(logger,"Hello from Parent {}",123);  }}

Quill is licensed under theMIT License

Quill depends on third party libraries with separate copyright notices and license terms.Your use of the source code for these subcomponents is subject to the terms and conditions of the following licenses.

• (MIT License){fmt}
• (MIT License)doctest