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.

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 2GB and then blocks further log messages.

  • UnboundedDropping: Starts with a small initial capacity. The queue reallocates up to 2GB and then discards log messages.

  • UnboundedUnlimited: Starts with a small initial capacity and reallocates without limit. This queue never blocks or drops log messages.

  • BoundedBlocking: Has a fixed capacity and never reallocates. It blocks log messages when the limit is reached.

  • 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.

To modify the queue type, you should define your own FrontendOptions and use it to create a custom FrontendImpl and LoggerImpl.

It is important to consistently use your custom types throughout the application, instead of the default ones.

For example, to use a BoundedDropping queue with a fixed capacity of 131’072, you can follow the steps below:

 1#include "quill/Backend.h"
 2#include "quill/Frontend.h"
 3#include "quill/sinks/ConsoleSink.h"
 4#include "quill/LogMacros.h"
 5#include "quill/Logger.h"
 6
 7/**
 8 * This example demonstrates defining and utilizing custom FrontendOptions.
 9 * It's useful when you need to modify the queue type or capacity.
10 * FrontendOptions are compile-time options and must be passed as a template argument.
11 */
12
13// define your own FrontendOptions, see "core/FrontendOptions.h" for details
14struct CustomFrontendOptions
15{
16  static constexpr quill::QueueType queue_type = quill::QueueType::BoundedDropping;
17  static constexpr uint32_t initial_queue_capacity = 131'072;
18  static constexpr uint32_t blocking_queue_retry_interval_ns = 800;
19  static constexpr quill::HugePagesPolicy huge_pages_policy = quill::HugePagesPolicy::Never;
20};
21
22// To utilize our custom FrontendOptions, we define a Frontend class using CustomFrontendOptions
23using CustomFrontend = quill::FrontendImpl<CustomFrontendOptions>;
24
25// The Logger type must also be defined
26using CustomLogger = quill::LoggerImpl<CustomFrontendOptions>;
27
28int main()
29{
30  // Start the backend thread
31  quill::BackendOptions backend_options;
32  quill::Backend::start(backend_options); // or quill::Backend::start<CustomFrontendOptions>(backend_options, signal_handler_options);
33
34  // All frontend operations must utilize CustomFrontend instead of quill::Frontend
35  auto console_sink = CustomFrontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1");
36  CustomLogger* logger = CustomFrontend::create_or_get_logger("root", std::move(console_sink));
37
38  // log something
39  LOG_INFO(logger, "This is a log info example {}", 123);
40  LOG_WARNING(logger, "This is a log warning example {}", 123);
41}