Plog - portable, simple and extensible C++ logging library

Pretty powerful logging library in about 1000 lines of code

• Introduction
  • Hello log!
  • Features
• Integration
  • Copy the source
  • Git submodule
  • CMake integration
    • add_subdirectory
    • FetchContent
  • Package managers
• Usage
  • Step 1: Adding includes
  • Step 2: Initialization
    • RollingFileInitializer
    • ConsoleInitializer
    • Manual initialization (Init.h)
  • Step 3: Logging
    • Basic logging macros
    • Conditional logging macros
    • Logger severity checker
• Advanced usage
  • Changing severity at runtime
  • Custom initialization
  • Multiple appenders
  • Multiple loggers
  • Share log instances across modules (exe, dll, so, dylib)
  • Chained loggers
• Architecture
  • Overview
  • Logger
  • Record
  • Formatter
    • TxtFormatter
    • TxtFormatterUtcTime
    • CsvFormatter
    • CsvFormatterUtcTime
    • FuncMessageFormatter
    • MessageOnlyFormatter
  • Converter
    • UTF8Converter
    • NativeEOLConverter
  • Appender
    • RollingFileAppender
    • ConsoleAppender
    • ColorConsoleAppender
    • AndroidAppender
    • EventLogAppender
    • DebugOutputAppender
    • ArduinoAppender
    • DynamicAppender
• Miscellaneous notes
  • Lazy stream evaluation
  • Stream improvements over std::ostream
  • Automatic 'this' pointer capture
  • Headers to include
  • Unicode
  • Wide string support
  • Performance
  • Printf style formatting
  • LOG_XXX macro name clashes
  • Disable logging to reduce binary size
  • PLOG_MESSAGE_PREFIX
• Extending
  • Custom data type
  • Custom appender
  • Custom formatter
  • Custom converter
• Samples
• License
• Version history

Introduction

Hello log!

Plog is a C++ logging library that is designed to be as simple, small and flexible as possible. It is created as an alternative to existing large libraries and provides some unique features as CSV log format and wide string support.

Here is a minimal hello log sample:

#include <plog/Log.h> // Step1: include the headers
#include "plog/Initializers/RollingFileInitializer.h"

int main()
{
    plog::init(plog::debug, "Hello.txt"); // Step2: initialize the logger

    // Step3: write log messages using a special macro
    // There are several log macros, use the macro you liked the most

    PLOGD << "Hello log!"; // short macro
    PLOG_DEBUG << "Hello log!"; // long macro
    PLOG(plog::debug) << "Hello log!"; // function-style macro

    // Also you can use LOG_XXX macro but it may clash with other logging libraries
    LOGD << "Hello log!"; // short macro
    LOG_DEBUG << "Hello log!"; // long macro
    LOG(plog::debug) << "Hello log!"; // function-style macro

    return 0;
}

And its output:

2015-05-18 23:12:43.921 DEBUG [21428] [main@13] Hello log!
2015-05-18 23:12:43.968 DEBUG [21428] [main@14] Hello log!
2015-05-18 23:12:43.968 DEBUG [21428] [main@15] Hello log!

Features

• Very small (slightly more than 1000 LOC)
• Easy to use
• Headers only
• No 3rd-party dependencies
• Cross-platform: Windows, Linux, FreeBSD, macOS, Android, RTEMS, FreeRTOS (gcc, clang, msvc, mingw, mingw-w64, icc, c++builder)
• Thread and type safe
• Formatters: TXT, CSV, FuncMessage, MessageOnly
• Appenders: RollingFile, Console, ColorConsole, Android, EventLog, DebugOutput, DynamicAppender
• Automatic 'this' pointer capture (supported only on msvc)
• Lazy stream evaluation
• Unicode aware, files are stored in UTF-8, supports Utf8Everywhere
• Doesn't require C++11
• Extendable
• No windows.h dependency
• Can use UTC or local time
• Can print buffers in HEX or ASCII
• Can print std containers
• Uses modern CMake

Integration

Plog is a header-only C++ library, making it extremely easy to integrate into any project. You do not need to build or link any binaries — just add the headers to your include path. Here are several recommended ways to add Plog to your project:

Copy the source

Simply copy the plog directory into your source tree. For example:

.                           <-- root of your solution
├── README.md
└── src
    ├── 3rd-party           <-- directory for all 3rd-party dependencies
    │   └── plog            <-- plog is copied there
    │       ├── include     <-- add this to your include search path
    │       │   └── plog
    │       ├── LICENSE
    │       └── README.md
    ├── proj1
    └── proj2

Then, add src/3rd-party/plog/include to your project's include directories.

Git submodule

Add Plog as a git submodule to keep it up to date and track its version:

git submodule add https://github.com/SergiusTheBest/plog.git src/3rd-party/plog
git commit -m "Add plog as a submodule"

This approach allows you to easily update Plog and manage its version. Remember to add src/3rd-party/plog/include to your include path.

CMake integration

add_subdirectory

If you use CMake, you can add Plog directly to your build:

add_subdirectory(3rd-party/plog) # Adds plog to your CMake project

add_executable(myproj main.cpp)
target_link_libraries(myproj plog::plog) # Links and sets include path

FetchContent

Alternatively, use CMake's FetchContent to automatically download Plog at configure time:

include(FetchContent)

FetchContent_Declare(
    plog
    GIT_REPOSITORY https://github.com/SergiusTheBest/plog
    GIT_TAG        1.1.10
    GIT_SHALLOW    true
)
FetchContent_MakeAvailable(plog) # Downloads and adds plog to your CMake project

add_executable(myproj main.cpp)
target_link_libraries(myproj plog::plog) # Links and sets include path

Package managers

Plog is also available via popular C++ package managers:

• vcpkg
  vcpkg install plog
• Conan
  conan install plog
• NuGet
  nuget install plog

Refer to each package manager's documentation for the latest installation instructions and version details.

Usage

To start using plog you need to make 3 simple steps.

Step 1: Adding includes

At first your project needs to know about plog. For that you have to:

1. Add plog/include to the project include paths
2. Add #include <plog/Log.h> into your cpp/h files (if you have precompiled headers it is a good place to add this include there)

Step 2: Initialization

To use plog, you must initialize the logger by including the appropriate header and calling the corresponding plog::init overload:

Logger& init(Severity maxSeverity, ...

maxSeverity is the logger severity upper limit. Log messages with a severity value higher (less severe) than the limit are dropped.

Plog defines the following severity levels:

enum Severity
{
    none = 0,
    fatal = 1,
    error = 2,
    warning = 3,
    info = 4,
    debug = 5,
    verbose = 6
};

Note Messages with severity level none will always be printed.

Plog provides several convenient initializer functions to simplify logger setup for common use cases. These initializers configure the logger with typical appenders and formatters, so you can get started quickly without manually specifying all template parameters.

RollingFileInitializer

Use this when you want to log to a file with automatic rolling (rotation) based on size and count. Add #include <plog/Initializers/RollingFileInitializer.h> and call init:

Logger& init(Severity maxSeverity, const util::nchar* fileName, size_t maxFileSize = 0, int maxFiles = 0);

• The log format is determined by the file extension:
  • .csv → CSV format
  • anything else → TXT format
• You can override the format by specifying a formatter as a template parameter, e.g. plog::init<plog::CsvFormatter>(...).
• Rolling is controlled by maxFileSize (bytes) and maxFiles (number of files to keep). If either is zero, rolling is disabled.

Example:

#include <plog/Log.h>
#include <plog/Initializers/RollingFileInitializer.h>

plog::init(plog::warning, "c:\\logs\\log.csv", 1000000, 5);

Here the logger is initialized to write all messages with up to warning severity to a file in csv format. Maximum log file size is set to 1'000'000 bytes and 5 log files are kept.

ConsoleInitializer

Use this to log to the console (stdout or stderr) with color output. Add #include <plog/Initializers/ConsoleInitializer.h> and call init:

Logger& init(Severity maxSeverity, OutputStream outputStream)

• By default it uses TXT format but it can be overriden by specifying a formatter as a template parameter, e.g. plog::init<plog::CsvFormatter>(...).
• outputStream chooses the output stream: plog::streamStdOut or plog::streamStdErr.

Example:

#include <plog/Log.h>
#include <plog/Initializers/ConsoleInitializer.h>

plog::init<plog::TxtFormatter>(plog::error, plog::streamStdErr); // logs error and above to stderr

Manual initialization (Init.h)

For advanced or custom setups add #include <plog/Init.h> and call init:

Logger& init(Severity maxSeverity = none, IAppender* appender = NULL);

You must construct and manage the appender yourself.

Example:

#include <plog/Log.h>
#include <plog/Init.h>

static plog::ConsoleAppender<plog::TxtFormatter> appender;
plog::init(plog::info, &appender); // logs info and above to the specified appender

Note See Custom initialization for advanced usage.

Step 3: Logging

Logging is performed with the help of special macros. A log message is constructed using stream output operators <<. Thus it is type-safe and extendable in contrast to a format string output.

Basic logging macros

This is the most used type of logging macros. They do unconditional logging.

Long macros:

PLOG_VERBOSE << "verbose";
PLOG_DEBUG << "debug";
PLOG_INFO << "info";
PLOG_WARNING << "warning";
PLOG_ERROR << "error";
PLOG_FATAL << "fatal";
PLOG_NONE << "none";

Short macros:

PLOGV << "verbose";
PLOGD << "debug";
PLOGI << "info";
PLOGW << "warning";
PLOGE << "error";
PLOGF << "fatal";
PLOGN << "none";

Function-style macros:

PLOG(severity) << "msg";

Conditional logging macros

These macros are used to do conditional logging. They accept a condition as a parameter and perform logging if the condition is true.

Long macros:

PLOG_VERBOSE_IF(cond) << "verbose";
PLOG_DEBUG_IF(cond) << "debug";
PLOG_INFO_IF(cond) << "info";
PLOG_WARNING_IF(cond) << "warning";
PLOG_ERROR_IF(cond) << "error";
PLOG_FATAL_IF(cond) << "fatal";
PLOG_NONE_IF(cond) << "none";

Short macros:

PLOGV_IF(cond) << "verbose";
PLOGD_IF(cond) << "debug";
PLOGI_IF(cond) << "info";
PLOGW_IF(cond) << "warning";
PLOGE_IF(cond) << "error";
PLOGF_IF(cond) << "fatal";
PLOGN_IF(cond) << "none";

Function-style macros:

PLOG_IF(severity, cond) << "msg";

Logger severity checker

In some cases there is a need to perform a group of actions depending on the current logger severity level. There is a special macro for that. It helps to minimize performance penalty when the logger is inactive.

```cpp IF_PL