CppLogging

C++ Logging Library provides functionality to log different events with a high throughput in multithreaded environment into different sinks (console, files, rolling files, syslog, etc.). Logging configuration is very flexible and gives functionality to build flexible logger hierarchy with combination of logging processors (sync, async), filters, layouts (binary, hash, text) and appenders.

CppLogging API reference

Contents

• Features
• Requirements
• How to build?
• Logging examples
  • Example 1: Default logger
  • Example 2: Format with logger
  • Example 3: Configure custom logger with text layout and console appender
  • Example 4: Configure custom logger with text layout and syslog appender
  • Example 5: Configure custom logger with binary layout and file appender
  • Example 6: Configure custom logger with hash layout and file appender
  • Example 7: Configure logger with custom text layout pattern
  • Example 8: Configure rolling file appender with time-based policy
  • Example 9: Configure rolling file appender with size-based policy
  • Example 10: Multithreaded logging with synchronous processor
  • Example 11: Multithreaded logging with asynchronous processor
• Logging benchmarks
  • Benchmark 1: Null appender
  • Benchmark 2: File appender
  • Benchmark 3: Synchronous processor with null appender
  • Benchmark 4: Asynchronous processor with null appender
  • Benchmark 5: Synchronous processor with file appender
  • Benchmark 6: Asynchronous processor with file appender
  • Benchmark 7: Format in logging thread vs binary serialization without format
  • Benchmark 8: Binary layout vs hash layout vs text layout
  • Benchmark 9: Format vs store format
• Tools
  • Binary log reader
  • Hash log reader
  • Hash log builder

Features

• Cross platform (Linux, MacOS, Windows)
• Optimized for performance
• Binary, hash & text layouts
• Synchronous logging
• Asynchronous logging
• Flexible configuration and logger processing hierarchy
• Appenders collection (null, memory, console, file, rolling file, ostream, syslog)
• Logging levels (debug, info, warning, error, fatal)
• Logging filters (by level, by logger name, by message pattern)
• Format logging records using {fmt} library
• Hash layout using 32-bit FNV-1a string hashing
• Log files rolling policies (time-based, size-bases)
• Log files Zip archivation

Requirements

• Linux
• MacOS
• Windows
• cmake
• gcc
• git
• gil
• python3

Optional: * clang * CLion * Cygwin * MSYS2 * MinGW * Visual Studio

How to build?

Linux: install required packages

sudo apt-get install -y binutils-dev uuid-dev

Install gil (git links) tool

pip3 install gil

Setup repository

git clone https://github.com/chronoxor/CppLogging.git
cd CppLogging
gil update

Linux

cd build
./unix.sh

MacOS

cd build
./unix.sh

Windows (Cygwin)

cd build
unix.bat

Windows (MSYS2)

cd build
unix.bat

Windows (MinGW)

cd build
mingw.bat

Windows (Visual Studio)

cd build
vs.bat

Logging examples

Example 1: Default logger

This is the simple example of using default logger. Just link it with CppLogging library and you'll get default logger functionality with text layout and console appender:

#include "logging/logger.h"

int main(int argc, char** argv)
{
    // Create default logger
    CppLogging::Logger logger;

    // Log some messages with different level
    logger.Debug("Debug message");
    logger.Info("Info message");
    logger.Warn("Warning message");
    logger.Error("Error message");
    logger.Fatal("Fatal message");

    return 0;
}

Example will create the following log in console:

Example 2: Format with logger

CppLogging library provides powerful logging format API based on the {fmt} library:

#include "logging/logger.h"

class Date
{
public:
    Date(int year, int month, int day) : _year(year), _month(month), _day(day) {}

    friend std::ostream& operator<<(std::ostream& os, const Date& date)
    { return os << date._year << '-' << date._month << '-' << date._day; }

    friend CppLogging::Record& operator<<(CppLogging::Record& record, const Date& date)
    { return record.StoreCustomFormat("{}-{}-{}", date._year, date._month, date._day); }

private:
    int _year, _month, _day;
};

class DateTime
{
public:
    DateTime(Date date, int hours, int minutes, int seconds) : _date(date), _hours(hours), _minutes(minutes), _seconds(seconds) {}

    friend std::ostream& operator<<(std::ostream& os, const DateTime& datetime)
    { return os << datetime._date << " " << datetime._hours << ':' << datetime._minutes << ':' << datetime._seconds; }

    friend CppLogging::Record& operator<<(CppLogging::Record& record, const DateTime& datetime)
    {
        const size_t begin = record.StoreListBegin();
        record.StoreList(datetime._date);
        record.StoreList(' ');
        record.StoreList(datetime._hours);
        record.StoreList(':');
        record.StoreList(datetime._minutes);
        record.StoreList(':');
        record.StoreList(datetime._seconds);
        return record.StoreListEnd(begin);
    }

private:
    Date _date;
    int _hours, _minutes, _seconds;
};

int main(int argc, char** argv)
{
    // Create default logger
    CppLogging::Logger logger;

    // Log some messages with format
    logger.Info("argc: {}, argv: {}", argc, (void*)argv);
    logger.Info("no arguments");
    logger.Info("{0}, {1}, {2}", -1, 0, 1);
    logger.Info("{0}, {1}, {2}", 'a', 'b', 'c');
    logger.Info("{}, {}, {}", 'a', 'b', 'c');
    logger.Info("{2}, {1}, {0}", 'a', 'b', 'c');
    logger.Info("{0}{1}{0}", "abra", "cad");
    logger.Info("{:<30}", "left aligned");
    logger.Info("{:>30}", "right aligned");
    logger.Info("{:^30}", "centered");
    logger.Info("{:*^30}", "centered");
    logger.Info("{:+f}; {:+f}", 3.14, -3.14);
    logger.Info("{: f}; {: f}", 3.14, -3.14);
    logger.Info("{:-f}; {:-f}", 3.14, -3.14);
    logger.Info("int: {0:d};  hex: {0:x};  oct: {0:o}; bin: {0:b}", 42);
    logger.Info("int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}", 42);
    logger.Info("The date is {}", Date(2012, 12, 9));
    logger.Info("The datetime is {}", DateTime(Date(2012, 12, 9), 13, 15, 57));
    logger.Info("Elapsed time: {s:.2f} seconds", "s"_a = 1.23);
    logger.Info("The answer is {}"_format(42));

    return 0;
}

Example will create the following log:

2019-03-27T12:04:19.881Z [0x0000FFB8] INFO   - argc: 1, argv: 0x1ff83563210
2019-03-27T12:04:19.882Z [0x0000FFB8] INFO   - no arguments
2019-03-27T12:04:19.883Z [0x0000FFB8] INFO   - -1, 0, 1
2019-03-27T12:04:19.884Z [0x0000FFB8] INFO   - a, b, c
2019-03-27T12:04:19.884Z [0x0000FFB8] INFO   - a, b, c
2019-03-27T12:04:19.884Z [0x0000FFB8] INFO   - c, b, a
2019-03-27T12:04:19.884Z [0x0000FFB8] INFO   - abracadabra
2019-03-27T12:04:19.885Z [0x0000FFB8] INFO   - left aligned
2019-03-27T12:04:19.885Z [0x0000FFB8] INFO   -                  right aligned
2019-03-27T12:04:19.885Z [0x0000FFB8] INFO   -            centered
2019-03-27T12:04:19.886Z [0x0000FFB8] INFO   - ***********centered***********
2019-03-27T12:04:19.886Z [0x0000FFB8] INFO   - +3.140000; -3.140000
2019-03-27T12:04:19.887Z [0x0000FFB8] INFO   -  3.140000; -3.140000
2019-03-27T12:04:19.887Z [0x0000FFB8] INFO   - 3.140000; -3.140000
2019-03-27T12:04:19.887Z [0x0000FFB8] INFO   - int: 42;  hex: 2a;  oct: 52; bin: 101010
2019-03-27T12:04:19.888Z [0x0000FFB8] INFO   - int: 42;  hex: 0x2a;  oct: 052;  bin: 0b101010
2019-03-27T12:04:19.888Z [0x0000FFB8] INFO   - The date is 2012-12-9
2019-03-27T12:04:19.888Z [0x0000FFB8] INFO   - The datetime is 2012-12-9 13:15:57
2019-03-27T12:04:19.889Z [0x0000FFB8] INFO   - Elapsed time: 1.23 seconds
2019-03-27T12:04:19.889Z [0x0000FFB8] INFO   - The answer is 42

Example 3: Configure custom logger with text layout and console appender

This example shows how to configure a custom logger with a given name to perform logging with a text layout and console appender sink:

#include "logging/config.h"
#include "logging/logger.h"

void ConfigureLogger()
{
    // Create default logging sink processor with a text layout
    auto sink = std::make_shared<CppLogging::Processor>(std::make_shared<CppLogging::TextLayout>());
    // Add console appender
    sink->appenders().push_back(std::make_shared<CppLogging::ConsoleAppender>());

    // Configure example logger
    CppLogging::Config::ConfigLogger("example", sink);
}

int main(int argc, char** argv)
{
    // Configure logger
    ConfigureLogger();

    // Create example logger
    CppLogging::Logger logger("example");

    // Log some messages with different level
    logger.Debug("Debug message");
    logger.Info("Info message");
    logger.Warn("Warning message");
    logger.Error("Error message");
    logger.Fatal("Fatal message");

    return 0;
}

Example 4: Configure custom logger with text layout and syslog appender

Syslog appender is available only in Unix platforms and does nothing in Windows!

This example shows how to configure a custom logger with a given name to perform logging with a text layout and syslog appender sink:

#include "logging/config.h"
#include "logging/logger.h"

void ConfigureLogger()
{
    // Create default logging sink processor with a text layout
    auto sink = std::make_shared<CppLogging::Processor>(std::make_shared<CppLogging::TextLayout>());
    // Add syslog appender
    sink->appenders().push_back(std::make_shared<CppLogging::SyslogAppender>());

    // Configure example logger
    CppLogging::Config::ConfigLogger("example", sink);
}

int main(int argc, char** argv)
{
    // Configure logger
    ConfigureLogger();

    // Create example logger
    CppLogging::Logger logger("example");

    // Log some messages with different level
    logger.Debug("Debug message");
    logger.Info("Info message");
    logger.Warn("Warning message");
    logger.Error("Error message");
    logger.Fatal("Fatal message");

    return 0;
}

Example 5: Configure custom logger with binary layout and file appender

This example shows how to configure a custom logger with a given name to perform logging with a binary layout and file appender sink:

```c++

include "logging/config.h"

include "logging/logger.h"

void ConfigureLogger() { // Create default logging sink processor with