#Plog - portable and simple log for C++ Pretty powerful log in less than 1000 lines of code Build Status Build status

#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 automatic ‘this’ pointer capture.

Here is a minimal hello log sample:

#include <plog/Log.h> // Step1: include the header.

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.

    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] [[email protected]] Hello log!
2015-05-18 23:12:43.968 DEBUG [21428] [[email protected]] Hello log!
2015-05-18 23:12:43.968 DEBUG [21428] [[email protected]] Hello log!

##Features - Very small (less than 1000 LOC) - Easy to use - Headers only - No 3rd-party dependencies - Cross-platform: Windows, Linux, Mac OS X, Android (gcc, clang, msvc, mingw, mingw-w64) - Thread and type safe - Formatters: TXT, CSV, FuncMessage - Appenders: RollingFile, Console, ColorConsole, Android - Automatic ‘this’ pointer capture (supported only on msvc) - Lazy stream evaluation - Unicode aware, files are stored in UTF8 - Doesn’t require C++11 - Extendable

#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/inlcude 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 The next step is to initialize the Logger. This is done by the following plog::init function:

Logger& init(Severity maxSeverity, const char/wchar_t* fileName, size_t maxFileSize = 0, int maxFiles = 0);

maxSeverity is the logger severity upper limit. All log messages have its own severity and if it is higher than the limit those messages are dropped. Plog defines the following severity levels:

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

The log format is determined automatically by fileName file extension:

The rolling behavior is controlled by maxFileSize and maxFiles parameters:

  • maxFileSize - the maximum log file size in bytes
  • maxFiles - a number of log files to keep

If one of them is zero then log rolling is disabled.

Sample:

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.

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:

LOG_VERBOSE << "verbose";
LOG_DEBUG << "debug";
LOG_INFO << "info";
LOG_WARNING << "warning";
LOG_ERROR << "error";
LOG_FATAL << "fatal";

####Short macros:

LOGV << "verbose";
LOGD << "debug";
LOGI << "info";
LOGW << "warning";
LOGE << "error";
LOGF << "fatal";

####Function-style macros:

LOG(severity) << "msg";

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

####Long macros:

LOG_VERBOSE_IF(cond) << "verbose";
LOG_DEBUG_IF(cond) << "debug";
LOG_INFO_IF(cond) << "info";
LOG_WARNING_IF(cond) << "warning";
LOG_ERROR_IF(cond) << "error";
LOG_FATAL_IF(cond) << "fatal";

####Short macros:

LOGV_IF(cond) << "verbose";
LOGD_IF(cond) << "debug";
LOGI_IF(cond) << "info";
LOGW_IF(cond) << "warning";
LOGE_IF(cond) << "error";
LOGF_IF(cond) << "fatal";

####Function-style macros:

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

IF_LOG(severity)

Sample:

IF_LOG(plog::debug) // we want to execute the following statements only at debug severity (and higher)
{
    for (int i = 0; i < vec.size(); ++i)
    {
        LOGD << "vec[" << i << "]: " << vec[i];
    }
}

#Advanced usage

##Changing severity at runtime It is possible to set the maximum severity not only at the logger initialization time but at any time later. There are special accessor methods:

Severity Logger::getMaxSeverity() const;
Logger::setMaxSeverity(Severity severity);

To get the logger use plog::get function:

Logger* get();

Sample:

plog::get()->setMaxSeverity(plog::debug);

##Custom initialization Non-typical log cases require the use of custom initialization. It is done by the following plog::init function:

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

You have to construct an Appender parameterized with a Formatter and pass it to the plog::init function.

Note: a lifetime of the appender should be static!

Sample:

static plog::ConsoleAppender<plog::TxtFormatter> consoleAppender;
plog::init(plog::debug, &consoleAppender);

##Multiple appenders It is possible to have multiple Appenders within a single Logger. In such case log message will be written to all of them. Use the following method to accomplish that:

Logger& Logger::addAppender(IAppender* appender);

Sample:

static plog::RollingFileAppender<plog::CsvFormatter> fileAppender("MultiAppender.csv", 8000, 3); // Create the 1st appender.
static plog::ConsoleAppender<plog::TxtFormatter> consoleAppender; // Create the 2nd appender.
plog::init(plog::debug, &fileAppender).addAppender(&consoleAppender); // Initialize the logger with the both appenders.

Here the logger is initialized in the way when log messages are written to both a file and a console.

Refer to MultiAppender for a complete sample.

##Multiple loggers Multiple Loggers can be used simultaneously each with their own separate configuration. The Loggers differ by their instance number (that is implemented as a template parameter). The default instance is zero. Initialization is done by the appropriate template plog::init functions:

Logger<instance>& init<instance>(...);

To get a logger use plog::get function (returns NULL if the logger is not initialized):

Logger<instance>* get<instance>();

All logging macros have their special versions that accept an instance parameter. These kind of macros have an underscore at the end:

LOGD_(instance) << "debug";
LOGD_IF_(instance, condition) << "conditional debug";
IF_LOG_(instance, severity)

Sample:

enum // Define log instances. Default is 0 and is omitted from this enum.
{
    SecondLog = 1
};

int main()
{
    plog::init(plog::debug, "MultiInstance-default.txt"); // Initialize the default logger instance.
    plog::init<SecondLog>(plog::debug, "MultiInstance-second.txt"); // Initialize the 2nd logger instance.

    // Write some messages to the default log.
    LOGD << "Hello default log!";

    // Write some messages to the 2nd log.
    LOGD_(SecondLog) << "Hello second log!";

    return 0;
}

Refer to MultiInstance for a complete sample.

##Chained loggers A Logger can work as an Appender for another Logger. So you can chain several loggers together. This is useful for streaming log messages from a shared library to the main application binary.

Sample:

// shared library

// Function that initializes the logger in the shared library. 
extern "C" void EXPORT initialize(plog::Severity severity, plog::IAppender* appender)
{
    plog::init(severity, appender); // Initialize the shared library logger.
}

// Function that produces a log message.
extern "C" void EXPORT foo()
{
    LOGI << "Hello from shared lib!";
}
// main app

// Functions imported form the shared library.
extern "C" void initialize(plog::Severity severity, plog::IAppender* appender);
extern "C" void foo();

int main()
{
    plog::init(plog::debug, "ChainedApp.txt"); // Initialize the main logger.

    LOGD << "Hello from app!"; // Write a log message.

    initialize(plog::debug, plog::get()); // Initialize the logger in the shared library. Note that it has its own severity.
    foo(); // Call a function from the shared library that produces a log message.

    return 0;
}

Refer to Chained for a complete sample.

#Architecture

##Overview Plog is designed to be small but flexible, so it prefers templates to interface inheritance. All main entities are shown on the following UML diagram:

Plog class diagram <!– @startuml interface IAppender { +write(); }

class Logger <> { +addAppender(); +getMaxSeverity(); +setMaxSeverity(); +checkSeverity(); -maxSeverity; -appenders; }

class RollingFileAppender class ConsoleAppender class ColorConsoleAppender class AndroidAppender

ConsoleAppender <|– ColorConsoleAppender IAppender <|-u- Logger IAppender <|– RollingFileAppender IAppender <|– ConsoleAppender IAppender <|– AndroidAppender

Logger “1” o– “0..n” IAppender

class CsvFormatter { {static} header(); {static} format(); }

class TxtFormatter { {static} header(); {static} format(); }

class FuncMessageFormatter { {static} header(); {static} format(); }

class UTF8Converter { {static} header(); {static} convert(); }

enum Severity { none, fatal, error, warning, info, debug, verbose }

class Record { +operator<<(); -time; -severity; -tid; -object; -line; -message; -func; }

hide empty members hide empty fields @enduml –>

There are 5 functional parts:

  • Logger - the main object, implemented as singleton
  • Record - keeps log data: time, message, etc
  • Appender - represents a log data destination: file, console, etc
  • Formatter - formats log data into a string
  • Converter - converts formatter output into a raw buffer

The log data flow is shown below:

Log data flow

##Logger Logger is a center object of the whole logging system. It is a singleton and thus it forms a known single entry point for configuration and processing log data. Logger can act as Appender for another Logger because it implements IAppender interface. Also there can be several independent loggers that are parameterized by an integer instance number. The default instance is 0.

template<int instance>
class Logger : public util::Singleton<Logger<instance> >, public IAppender
{
public:
    Logger(Severity maxSeverity = none);
    
    Logger& addAppender(IAppender* appender);
    
    Severity getMaxSeverity() const;
    void setMaxSeverity(Severity severity);
    bool checkSeverity(Severity severity) const;
    
    virtual void write(const Record& record);
    void operator+=(const Record& record);
};

##Record Record stores all log data. It includes:

  • time
  • severity
  • thread id
  • ‘this’ pointer (if a log message is written from within an object)
  • source line
  • function name
  • message

Also Record has a number of overloaded stream output operators to construct a message.

class Record
{
public:
    Record(Severity severity, const char* func, size_t line, const void* object);
    
    //////////////////////////////////////////////////////////////////////////
    // Stream output operators
        
    Record& operator<<(char data);
    Record& operator<<(wchar_t data);
    
    template<typename T>
    Record& operator<<(const T& data);
    
    //////////////////////////////////////////////////////////////////////////
    // Getters
    
    const util::Time& getTime() const;
    Severity getSeverity() const;
    unsigned int getTid() const;
    const void* getObject() const;
    size_t getLine() const;
    const util::nstring getMessage() const;
    std::string getFunc() const;
};

See Stream improvements over std::ostream.

Refer to Demo sample to see what can be written to the log stream.

##Formatter Formatter is responsible for formatting log data from Record into various string representations (binary forms can be used too). There is no base class for formatters, they are implemented as classes with static functions format and header:

class Formatter
{
public:
    static util::nstring header();
    static util::nstring format(const Record& record);
};

See How to implement a custom formatter.

###TxtFormatter This is a classic log format available in almost any log library. It is good for console output and it is easy to read without any tools.

2014-11-11 00:29:06.245 FATAL [4460] [[email protected]] fatal
2014-11-11 00:29:06.261 ERROR [4460] [[email protected]] error
2014-11-11 00:29:06.261 INFO  [4460] [[email protected]] info
2014-11-11 00:29:06.261 WARN  [4460] [[email protected]] warning
2014-11-11 00:29:06.261 DEBUG [4460] [[email protected]] debug
2014-11-11 00:29:06.261 INFO  [4460] [[email protected]] This is a message with "quotes"!
2014-11-11 00:29:06.261 DEBUG [4460] [Object::[email protected]] 
2014-11-11 00:29:06.261 DEBUG [4460] [Object::[email protected]] 

###CsvFormatter This is the most powerful log format. It can be easily read without any tools (but slighlty harder than TXT format) and can be heavily analyzed if it is opened with a CSV-aware tool (like Excel). One rows can be highlighted according to their cell values, another rows can be hidden, columns can be manipulated and you can even run SQL queries on log data! This is a recommended format if logs are big and require heavy analysis. Also ‘this’ pointer is shown so object instances can be told apart.

Date;Time;Severity;TID;This;Function;Message
2014/11/14;15:22:25.033;FATAL;4188;00000000;[email protected];"fatal"
2014/11/14;15:22:25.033;ERROR;4188;00000000;[email protected];"error"
2014/11/14;15:22:25.033;INFO;4188;00000000;[email protected];"info"
2014/11/14;15:22:25.033;WARN;4188;00000000;[email protected];"warning"
2014/11/14;15:22:25.048;DEBUG;4188;00000000;[email protected];"debug"
2014/11/14;15:22:25.048;INFO;4188;00000000;[email protected];"This is a message with ""quotes""!"
2014/11/14;15:22:25.048;DEBUG;4188;002EF4E3;Object::[email protected];
2014/11/14;15:22:25.048;DEBUG;4188;002EF4E3;Object::[email protected];

Note: message size is limited to 32000 chars.

###FuncMessageFormatter This format is designed to be used with appenders that provide their own timestamps (like AndroidAppender or linux syslog facility).

[email protected]: fatal
[email protected]3: error
[email protected]: info
[email protected]: warning
[email protected]: debug
[email protected]: This is a message with "quotes"!
Object::[email protected]: 
Object::[email protected]: 

##Converter Converter is responsible for conversion of Formatter output data to a raw buffer (represented as std::string). It is used by RollingFileAppender to perform a conversion before writing to a file. There is no base class for converters, they are implemented as classes with static functions convert and header:

class Converter
{
public:
    static std::string header(const util::nstring& str);
    static std::string convert(const util::nstring& str);
};

See How to implement a custom converter.

###UTF8Converter UTF8Converter is the only converter available in plog out of the box. It converts string data to UTF-8 with BOM.

##Appender Appender uses Formatter and Converter to get a desired representation of log data and outputs (appends) it to a file/console/etc. All appenders must implement IAppender interface (the only interface in plog):

class IAppender
{
public:
    virtual ~IAppender();
    virtual void write(const Record& record) = 0;
};

See How to implement a custom appender.

###RollingFileAppender This appender outputs log data to a file with rolling behaviour. As template parameters it accepts both Formatter and Converter.

RollingFileAppender<Formatter, Converter>::RollingFileAppender(const util::nchar* fileName, size_t maxFileSize = 0, int maxFiles = 0);
  • fileName - a log file name
  • maxFileSize - the maximum log file size in bytes
  • maxFiles - a number of log files to keep

If maxFileSize or maxFiles is 0 then rolling behaviour is turned off.

The sample file names produced by this appender:

  • mylog.log <== current log file (size < maxFileSize)
  • mylog.1.log <== previous log file (size >= maxFileSize)
  • mylog.2.log <== previous log file (size >= maxFileSize)

Note: the lowest maxFileSize is 1000 bytes.

Note: a log file is created on the first log message.

###ConsoleAppender This appender outputs log data to stdout. As a template parameter it accepts Formatter.

ConsoleAppender<Formatter>::ConsoleAppender();

###ColorConsoleAppender This appender outputs log data to stdout using colors that depends on a log message severity level. As a template parameter it accepts Formatter.

ColorConsoleAppender<Formatter>::ColorConsoleAppender();

###AndroidAppender AndroidAppender uses Android logging system to output log data. It can be viewed with logcat or in a log window of Android IDEs. As a template parameter this appender accepts Formatter (usually FuncMessageFormatter).

AndroidAppender<Formatter>::AndroidAppender(const char* tag);

#Miscellaneous notes

##Lazy stream evaluation Log messages are constructed using lazy stream evaluation. It means that if a log message will be dropped (because of its severity) then stream output operators are not executed. Thus performance penalty of unprinted log messages is negligible.

LOGD << /* the following statements will be executed only when the logger severity is debug or higher */ ...

##Stream improvements over std::ostream Stream output in plog has several improvements over the standard std::ostream:

  • handles wide chars/strings: wchar_t, wchar_t*, std::wstring
  • handles NULL values for C-strings: char* and wchar_t*
  • implicitly casts objects to: std::string and std::wstring (if they have an appropriate cast operator)

##Automatic ‘this’ pointer capture ‘This’ pointer is captured automatically to log data and can be printed by CsvFormatter. Unfortunately this feature is supported only on msvc 2010 and higher.

##Headers to include The core plog functionality is provided by inclusion of plog/Log.h file. Extra components require inclusion of corresponding extra headers after plog/Log.h.

Plog core and extra components

##Unicode Plog is unicode aware and wide string friendly. All messages are converted to a system native char type:

  • wchar_t - on Windows
  • char - on all other systems

Also char is treated as:

  • active code page - on Windows
  • UTF-8 - on all other systems

Internally plog uses nstring, nstringstream and nchar (‘n’ for native) that are defined as:

#ifdef _WIN32
    typedef std::wstring nstring;
    typedef std::wstringstream nstringstream;
    typedef wchar_t nchar;
#else
    typedef std::string nstring;
    typedef std::stringstream nstringstream;
    typedef char nchar;
#endif

By default all log files are stored in UTF-8 with BOM thanks to UTF8Converter.

Note: on Android wide string support in plog is disabled.

##Performance Plog is not using any asynchronous techniques so it may slow down your application on large volumes of log messages.

Producing a single log message takes the following amount of time:

CPU OS Time per a log call, microsec
AMD Phenom II 1055T @3.5GHz Windows 2008 R2 12
AMD Phenom II 1055T @3.5GHz Linux Mint 17.1 8
Intel Core i3-3120M @2.5GHz Windows 2012 R2 25
Intel Core i5-2500K @4.2GHz Windows 2008 R2 8
Intel Atom N270 @1.6GHz Windows 2003 68

Assume 20 microsec per a log call then 500 log calls per a second will slow down an application by 1%. It is acceptable for the most use cases.

Refer to Performance for a complete sample.

#Extending Plog can be easily extended to support new:

##Custom data type To output a custom data type to a log message implement the following function:

namespace plog
{
    Record& operator<<(Record& record, const MyType& t);
}

Refer to CustomType for a complete sample.

##Custom appender A custom appender must implement IAppender interface. Also it may accept Formatter and Converter as template parameters however this is optional.

namespace plog
{
    template<class Formatter>
    class MyAppender : public IAppender
    {
    public:
        virtual void write(const Record& record);
    };
}

Refer to CustomAppender for a complete sample.

##Custom formatter A formatter that is compatible with existing appenders must be a class with 2 static methods:

  • header - returns a header for a new log
  • format - formats Record to a string
namespace plog
{
    class MyFormatter
    {
    public:
        static util::nstring header();
        static util::nstring format(const Record& record);
    };
}

Refer to CustomFormatter for a complete sample.

##Custom converter A converter must be a class with 2 static methods:

  • header - converts a header for a new log
  • convert - converts log messages
namespace plog
{
    class MyConverter
    {
    public:
        static std::string header(const util::nstring& str);
        static std::string convert(const util::nstring& str);
    };
}

Refer to CustomConverter for a complete sample.

#Samples There are a number of samples that demonstrate various aspects of using plog. They can be found in the samples folder:

Sample Description
Android Shows how to use the android-specific appender.
Chained Shows how to chain a logger in a shared library with the main logger (route messages).
Library Shows plog usage in static libraries.
Hello A minimal introduction sample, shows the basic 3 steps to start using plog.
MultiAppender Shows how to use multiple appenders with the same logger.
MultiInstance Shows how to use multiple logger instances, each instance has its own independent configuration.
ObjectiveC Shows that plog can be used in ObjectiveC++.
Demo Demonstrates log stream abilities, prints various types of messages.
ColorConsole Shows how to use a color console appender.
CustomAppender Shows how to implement a custom appender that stores log messages in memory.
CustomFormatter Shows how to implement a custom formatter.
CustomConverter Shows how to implement a custom converter that encrypts log messages.
CustomType Shows how to print a custom type to the log stream.
Facilities Shows how to use logging per facilities via multiple logger instances (useful for big projects).
Performance Measures time per a log call.

#References

##Competing C++ log libraries

##Tools and useful info

#License Plog is licensed under the MPL version 2.0. You can freely use it in your commercial or opensource software.

#Version history

##Version 1.0.1 (01 Nov 2015) - New: Added ColorConsoleAppender - Fixed #6: Compatibility with Mingw-w64 - Fixed #7: Log file not created if file name contains Unicode characters in Windows - Fixed #4: Flush stdout - Fixed #3: IntelliSense error: expected an identifier

##Version 1.0.0 (19 May 2015) - Initial public release

Related Repositories

plog

plog

Portable, simple and extensible C++ logging library ...

Plog

Plog

...

plog

plog

a lighweight, flexible, extendable php log system ...

plog

plog

Ruby on Rails production log statistics generator. by Kazuyoshi Tlacaelel. ...

Android-PLog

Android-PLog

Android 专用日志封装库,轻巧易用,高扩展性。An log library focused on high extensibility, powerful enough but easy to use. ...


Top Contributors

SergiusTheBest christophschlosser rhd bastianseeleib

Releases

-   1.0.1 zip tar
-   1.0.0 zip tar
-   0.6.2 zip tar
-   0.6.1 zip tar
-   0.6.0 zip tar
-   0.5.9 zip tar
-   0.5.8 zip tar
-   0.5.7 zip tar
-   0.5.6 zip tar
-   0.5.5 zip tar
-   0.5.4 zip tar
-   0.5.3 zip tar
-   0.5.2 zip tar
-   0.5.1 zip tar
-   0.5.0 zip tar