Formatters¶

Use this page to customize the layout of log lines, timestamps, and source-location display.

The PatternFormatter specifies the layout of log records in the final output.

Each LoggerImpl object has a PatternFormatter object. This means that each Logger can be customised to output in a different format.

Customising the format output can only be done during the creation of the logger via PatternFormatterOptions.

If no custom format is set, each newly created logger uses the default formatting pattern.

The format output can be customised by providing a string of certain attributes.

Customising the timestamp¶

The timestamp is customisable through:

• Format. Same format specifiers as strftime(...) format with the additional %Qms %Qus %Qns arguments.

• Local timezone or GMT timezone. Local timezone is used by default.

• Fractional second precision. Using the additional fractional second specifiers in the timestamp format string.

By default "%H:%M:%S.%Qns" is used.

Use %% to write a literal percent sign in timestamp patterns, including escaped forms such as %%Qms or %%T. The escaped text is passed through as a literal instead of being interpreted as Quill’s fractional-second extension or as a cached time modifier.

Customizing Log Message Formats¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

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

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"),
    quill::PatternFormatterOptions{"%(time) [%(thread_id)] %(short_source_location:<28) "
                                   "LOG_%(log_level:<9) %(logger:<12) %(message)",
                                   "%H:%M:%S.%Qns", quill::Timezone::GmtTime});

  LOG_INFO(logger, "This is a log info example {}", 123);
}

Advanced Pattern Formatter Configuration¶

The 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):

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"

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:

#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:

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

Timestamp Configuration

Control timestamp timezone and format:

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:

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