Pretty powerful logging library in about 1000 lines of code
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.h> // Step1: include the header
static plog::SerialAppender<plog::TxtFormatter> serialAppender(Serial);
void setup(){
Serial.begin(115200);
plog::init(plog::debug, &serialAppender);// Step2: initialize the logger.
plog::TimeSync(DateTime(__DATE__, __TIME__), -7); // Step3: Synchronize the time
}
void loop(){
// Step4: 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
delay(1000);
}
And its output:
2015-05-18 23:12:43.921 DEBUG [21428] [loop@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!
windows.h
dependencyTo start using plog you need to make 3 simple steps.
At first your project needs to know about plog. For that you have to:
plog/include
to the project include paths#include <plog/Log.h>
into your cpp/h files (if you have precompiled headers it is a good place to add this include there)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
};
Note: messages with severity level none
will be always printed.
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 bytesmaxFiles
- a number of log files to keepIf 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.
The fastest and most portable time clock on Arduino is the millis() function, which tells you milliseconds since the microcontroller turned on or reset. It can count up to 50 days. However, it doesn't tell you actual time. To get actual time without an RTC, we use the compiled time as a reference. If you have an RTC attached to your Arduino, use that instead.
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.
This is the most used type of logging macros. They do unconditional logging.
PLOG_VERBOSE << "verbose";
PLOG_DEBUG << "debug";
PLOG_INFO << "info";
PLOG_WARNING << "warning";
PLOG_ERROR << "error";
PLOG_FATAL << "fatal";
PLOG_NONE << "none";
PLOGV << "verbose";
PLOGD << "debug";
PLOGI << "info";
PLOGW << "warning";
PLOGE << "error";
PLOGF << "fatal";
PLOGN << "none";
PLOG(severity) << "msg";
These macros are used to do a conditional logging. They accept a condition as a parameter and perform logging if the condition is true.
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";
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";
PLOG_IF(severity, cond) << "msg";
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_PLOG(severity)
Sample:
IF_PLOG(plog::debug) // we want to execute the following statements only at debug severity (and higher)
{
for (int i = 0; i < vec.size(); ++i)
{
PLOGD << "vec[" << i << "]: " << vec[i];
}
}
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);
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);
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 can be used simultaneously each with their own separate configuration. The Loggers differ by their instanceId (that is implemented as a template parameter). The default instanceId is zero. Initialization is done by the appropriate template plog::init
functions:
Logger<instanceId>& init<instanceId>(...);
To get a logger use plog::get
function (returns NULL
if the logger is not initialized):
Logger<instanceId>* get<instanceId>();
All logging macros have their special versions that accept an instanceId parameter. These kind of macros have an underscore at the end:
PLOGD_(instanceId) << "debug";
PLOGD_IF_(instanceId, condition) << "conditional debug";
IF_PLOG_(instanceId, severity)
Sample:
enum // Define log instanceIds. 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.
PLOGD << "Hello default log!";
// Write some messages to the 2nd log.
PLOGD_(SecondLog) << "Hello second log!";
return 0;
}
Refer to MultiInstance for a complete sample.
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()
{
PLOGI << "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.
PLOGD << "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.
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:
There are 5 functional parts:
The log data flow is shown below:
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 instanceId number. The default instanceId is 0.
template<int instanceId>
class Logger : public util::Singleton<Logger<instanceId> >, 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 stores all log data. It includes:
Note: Source file name isn't captured by default. To enable it define PLOG_CAPTURE_FILE.
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 char* file, const void* object);
//////////////////////////////////////////////////////////////////////////
// Stream output operators
Record& operator<<(char data);
Record& operator<<(wchar_t data);
template<typename T>
Record& operator<<(const T& data);
//////////////////////////////////////////////////////////////////////////
// Getters
virtual const util::Time& getTime() const;
virtual Severity getSeverity() const;
virtual unsigned int getTid() const;
virtual const void* getObject() const;
virtual size_t getLine() const;
virtual const util::nchar* getMessage() const;
virtual const char* getFunc() const;
virtual const char* getFile() const;
virtual int getInstanceId() const;
};
See Stream improvements over std::ostream.
Refer to Demo sample to see what can be written to the log stream.
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.
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] [main@22] fatal
2014-11-11 00:29:06.261 ERROR [4460] [main@23] error
2014-11-11 00:29:06.261 INFO [4460] [main@24] info
2014-11-11 00:29:06.261 WARN [4460] [main@25] warning
2014-11-11 00:29:06.261 DEBUG [4460] [main@26] debug
2014-11-11 00:29:06.261 INFO [4460] [main@32] This is a message with "quotes"!
2014-11-11 00:29:06.261 DEBUG [4460] [Object::Object@8]
2014-11-11 00:29:06.261 DEBUG [4460] [Object::~Object@13]
This is a variant of TxtFormatter that uses UTC time instead of local time.
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;main@22;"fatal"
2014/11/14;15:22:25.033;ERROR;4188;00000000;main@23;"error"
2014/11/14;15:22:25.033;INFO;4188;00000000;main@24;"info"
2014/11/14;15:22:25.033;WARN;4188;00000000;main@25;"warning"
2014/11/14;15:22:25.048;DEBUG;4188;00000000;main@26;"debug"
2014/11/14;15:22:25.048;INFO;4188;00000000;main@32;"This is a message with ""quotes""!"
2014/11/14;15:22:25.048;DEBUG;4188;002EF4E3;Object::Object@8;
2014/11/14;15:22:25.048;DEBUG;4188;002EF4E3;Object::~Object@13;
Note: message size is limited to 32000 chars.
This is a variant of CsvFormatter that uses UTC time instead of local time.
This format is designed to be used with appenders that provide their own timestamps (like AndroidAppender or linux syslog facility).
main@22: fatal
main@23: error
main@24: info
main@25: warning
main@26: debug
main@32: This is a message with "quotes"!
Object::Object@8:
Object::~Object@13:
Use this formatter when you're interested only in a log message.
fatal
error
info
warning
debug
This is a message with "quotes"!
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 is a default converter in plog. It converts string data to UTF-8 with BOM.
This converter converts <LF>
line endings to <CRLF>
on Windows and do nothing on everything else. As a template parameter it accepts another converter that is called next (by default UTF8Converter).
Sample:
plog::RollingFileAppender<plog::TxtFormatter, plog::NativeEOLConverter<> > fileAppender("NativeEOL.log");
Refer to NativeEOL for a complete sample.
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.
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 namemaxFileSize
- the maximum log file size in bytesmaxFiles
- a number of log files to keepIf maxFileSize
or maxFiles
is 0 then rolling behaviour is turned off.
The sample file names produced by this appender:
Note: the lowest maxFileSize
is 1000 bytes.
Note: a log file is created on the first log message.
This appender outputs log data to stdout
. As a template parameter it accepts Formatter.
ConsoleAppender<Formatter>::ConsoleAppender();
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 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);
This appender outputs log data to the windows event log. It can be viewed with the windows event log viewer. As a template parameter it accepts Formatter. The constructor parameter is the event source name - typically it is the name of the application or a subcomponent of the application. It must be unique for the whole system.
EventLogAppender<Formatter>::EventLogAppender(const wchar_t* sourceName);
EventLogAppender must be registered in the windows registry before use (before calling the constructor). There is a helper class for that:
bool EventLogAppenderRegistry::add(const wchar_t* sourceName, const wchar_t* logName = L"Application");
bool EventLogAppenderRegistry::exists(const wchar_t* sourceName, const wchar_t* logName = L"Application");
void EventLogAppenderRegistry::remove(const wchar_t* sourceName, const wchar_t* logName = L"Application");
Registry operations are system-wide and require administrator rights. Also they are persistent so can be performed only once (when the application is installed/uninstalled).
DebugOutputAppender sends log data to the debugger (works only on Windows). As a template parameter this appender accepts Formatter.
DebugOutputAppender<Formatter>::DebugOutputAppender();
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.
PLOGD << /* the following statements will be executed only when the logger severity is debug or higher */ ...
Stream output in plog has several improvements over the standard std::ostream
:
wchar_t
, wchar_t*
, std::wstring
NULL
values for C-strings: char*
and wchar_t*
std::string
and std::wstring
(if they have an appropriate cast operator)QString
and QStringRef
(you need to include Qt headers before plog)System::String^
'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. It's disabled by default (due to some compatibility issues with __if_exists
C++ extension), to enable it define PLOG_ENABLE_GET_THIS
.
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
.
Core components are:
Plog is unicode aware and wide string friendly. All messages are converted to a system native char type.
Internally plog uses nstring
, nstringstream
and nchar
('n' for native) that are defined as:
typedef String nstring;
typedef obufstream nstringstream;
typedef char nchar;
By default all log files are stored in UTF-8 with BOM thanks to UTF8Converter.
Whether wchar_t
, wchar_t*
, std::wstring
can be streamed to log messages or not is controlled by PLOG_ENABLE_WCHAR_INPUT
macro. Set it to a non-zero value to enable wide string support. By default wide string support is enabled for Windows and disabled for all non-Windows systems.
Note: wide string support requires linking to iconv
on macOS.
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.
Plog supports printf style formatting:
PLOGI.printf("%d %s", 42, "test");
PLOGI.printf(L"%d %S", 42, "test"); // wchar_t version
LOG_XXX
macro names may be in conflict with other libraries (for example syslog). In such cases you can disable LOG_XXX
macro by defining PLOG_OMIT_LOG_DEFINES
and use PLOG_XXX
.
Define PLOG_OMIT_LOG_DEFINES
before #include <plog/Log.h>
or in the project settings!
Plog can be easily extended to support new:
To output a custom data type to a log message implement the following function:
namespace plog
{
Record& operator<<(Record& record, const MyType& t);
}
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);
};
}
A formatter that is compatible with existing appenders must be a class with 2 static methods:
header
- returns a header for a new logformat
- formats Record to a stringnamespace plog
{
class MyFormatter
{
public:
static util::nstring header();
static util::nstring format(const Record& record);
};
}
A converter must be a class with 2 static methods:
header
- converts a header for a new logconvert
- converts log messagesnamespace plog
{
class MyConverter
{
public:
static std::string header(const util::nstring& str);
static std::string convert(const util::nstring& str);
};
}
Plog is licensed under the MPL version 2.0. You can freely use it in your commercial or opensource software.