fmtlog

Because fmtlog is asynchronous, log statements only push data into a queue. To ensure logs are actually written to their destination, you have two options:

1. Manual Polling: Call fmtlog::poll() periodically in your application. This gives you full control over when flushing occurs. Note that only one thread should call fmtlog::poll().
2. Background Polling Thread: Call fmtlog::startPollingThread(interval) to let fmtlog manage a background thread that polls at the specified interval. Warning: If a background polling thread is running, you cannot call fmtlog::poll() manually.

You can also force an immediate flush by calling fmtlog::poll(true).

// Manual polling approach
logi("Message 1\n");
fmtlog::poll();

logi("Message 2\n");
fmtlog::poll();

// Background thread approach
fmtlog::startPollingThread(1000); // Poll every 1000ms
// Do NOT call fmtlog::poll() manually while this thread is running

You can log messages using the FMTLOG macro or convenient shortcut macros.

Shortcut Macros:

• logd: Debug level (DBG)
• logi: Info level (INF)
• logw: Warning level (WRN)
• loge: Error level (ERR)

Note on Asynchronicity: fmtlog is asynchronous. Log messages are pushed into a queue and are not written to the file/console immediately. You must call fmtlog::poll() to process the queue and write the logs. You can also use fmtlog::startPollingThread(interval) to create a background thread that handles polling automatically, but if you do this, you must not call fmtlog::poll() manually.

#include "fmtlog/fmtlog.h"

int main() 
{
  // Using the main macro
  FMTLOG(fmtlog::INF, "The answer is {}.\n", 42);

  // Using shortcut macros
  logi("A info msg\n");
  logd("This msg will not be logged as the default log level is INF\n");
  
  fmtlog::setLogLevel(fmtlog::DBG);
  logd("Now debug msg is shown\n");

  // IMPORTANT: Must poll to see output
  fmtlog::poll();
  return 0;
}

By default, fmtlog outputs to stdout. To write to a file, use fmtlog::setLogFile(filename, truncate).

Flushing Behavior: fmtlog buffers data for performance. The buffer is flushed to the file when:

1. The buffer size exceeds 8 KB (configurable via fmtlog::setFlushBufSize(bytes)).
2. The oldest data in the buffer exceeds a specific duration (default 3s, configurable via fmtlog::setFlushDelay(ns)).
3. A log message reaches a specific level (configurable via fmtlog::flushOn(logLevel)).
4. The user calls fmtlog::poll(true).

Advanced File Management:

• You can pass an existing FILE* to fmtlog::setLogFile(fp, manageFp). If manageFp is false, fmtlog will not buffer (e.g., fmtlog::setLogFile(stderr, false) for unbuffered stderr logging).
• Use fmtlog::closeLogFile() to stop logging to the file.

// Set log file with truncation
fmtlog::setLogFile("app.log", true);

// Set custom flush buffer size (e.g., 16KB)
fmtlog::setFlushBufSize(16 * 1024);

// Set flush delay to 1 second
fmtlog::setFlushDelay(1000000000);

// Flush immediately on ERROR logs
fmtlog::flushOn(fmtlog::ERR);

You can register a callback function to handle log messages in real-time (e.g., for alerting) using fmtlog::setLogCB(cb, minCBLogLevel). Unlike the file output, callbacks are not buffered and can be triggered even if the log file is closed.

Callback Signature:

typedef void (*LogCBFn)(int64_t ns, LogLevel level, fmt::string_view location, size_t basePos, 
                          fmt::string_view threadName, fmt::string_view msg, size_t bodyPos, size_t logFilePos);

Parameters:

• ns: Nanosecond timestamp.
• level: The log level.
• location: Full file path with line number.
• basePos: File base index in the location.
• threadName: Thread ID or name set via setThreadName().
• msg: Full log message including the header.
• bodyPos: Index where the log body starts in msg.
• logFilePos: Log file position of this message.

void my_callback(int64_t ns, fmtlog::LogLevel level, fmt::string_view location, size_t basePos,
                 fmt::string_view threadName, fmt::string_view msg, size_t bodyPos, size_t logFilePos) {
    if (level >= fmtlog::WRN) {
        // Handle warning or error (e.g., send to an alerting system)
    }
}

// Register the callback
fmtlog::setLogCB(my_callback, fmtlog::WRN);

fmtlog uses the fmt library for formatting. It supports most fmtlib features, including named arguments, ranges, tuples, and user-defined types (though color support is excluded).

Pointer Support for Performance: To avoid copy overhead in an asynchronous environment, you can pass pointers (including std::shared_ptr and std::unique_ptr) to arguments. This is useful if the lifetime of the object is guaranteed to last until the next poll(). For example, passing a std::string* will only copy the pointer, whereas passing a std::string copies the entire content.

#include "fmtlog/fmtlog.h"
#include "fmt/ranges.h"

void example() {
  // Standard fmtlib formatting
  logi("Hello, {}!\n", "World");
  
  // Using ranges
  std::vector<int> v = {1, 2, 3};
  logi("vector: {}\n", v);

  // Passing pointers to avoid copies (ensure lifetime until poll())
  std::string str = "important data";
  logi("Pointer log: {}\n", &str);
  fmtlog::poll();
}

You can customize the prefix of every log line using fmtlog::setHeaderPattern(format_string). The pattern uses fmtlib named arguments.

Default Pattern: {HMSf} {s:<16} {l}[{t:<6}]

Available Named Arguments:

Tip: Using concatenated arguments like {YmdHMS} is more efficient than {Y}-{m}-{d} {H}:{M}:{S}.

// Example: Customizing header to show date and time
fmtlog::setHeaderPattern("{Ymd HMSf} [{l}] {s}\n");