Purpose

The pid-log package implement the runtime logging facility of PID. By logging we mean generating messages that inform about the state of a running program. These messages can be read from standard outputs or files and may be useful to notify some tools of interesting events, to provide debug information to developpers, or traces of program execution.

pid-log intend to provide a powerful but easy to configure logging tool for developpers with features:

• possibility to deactivate logs for a the whole program. Useful when you want to get real-time compatible performance and log is not required.
• filtering log messages either according to their severity or depending on their emitting place (component, package, framework).
• generating various log outputs from the same global log trace in a program. For instance usefull to discriminate errors or debug traces from other information.
• formatting of log messages is standardized and can be configured to get various information such as: calling site information (line in source file, calling function), runtime trace generation (date, thread) or PID related information (framework, package, component of the emitting component).
• easy configuration of logger system at global level. This way libraries can be completely agnostic from the way logs they generate are finally managed.

Overview

Basically, to use logging system of PID, a package (let’s call ot my-package) needs to depend on the pid-log package. In root CMakeLists.txt of the package:

...
PID_Dependency(pid-log VERSION 3.1)
# or PID_Dependency(pid-log) to get latest version
...

Then for a component my-component that needs to generate log traces, in the adequate CMakeLists.txt:

...
PID_Component(  my-component
                ... 
                LOGGABLE)
...

The LOGGABLE argument tells PID to generate a specific header file (in the current example pid/log/my-package_my-component.h) that is included in public headers of my-component.

Then in my-component source code:

...
#include <pid/log/my-package_my-component.h>
...
void my_function(){
	int error_number=0;
	...
	if(bad_situation){
		pid_log << pid::error << "error number: " << error_number <<pid::flush;
	}
	...
	if(strange_case_to_test > 0.0){
		pid_log << pid::debug << "bad situation "<< strange_case_to_test << pid::flush;
	}
}

The pid_log object is used to access logging system: it is used as a stream operator to generate log trace, with first input being the severity (e.g. pid::error). The log trace is generated when pid::flush is inserted in this stream, allowing trace construction on multiple lines of code if needed.

Now let’s suppose that component my-application depends on my-component, it can control log traces generated by the library

#include <my/component.h>//global header for my-component
#include <pid/log.h>

int main(int argc, char * argv[]){
    ...
	PID_LOGGER.configure("pid_log/only_errors_logs.yaml");
    //or pid::logger().configure("pid_log/only_errors_logs.yaml");
	...
}

In this example only traces generated with pid::error or pid::critical modifiers will be printed to standard output. The PID_LOGGER macro gives you the access to the global logger object. If the logger is not configured explicilty of if the program use the "pid_log/default_logs.yaml" then everything except debug traces will be printed to standard output. There are a few base configurations for the logger but you can define new ones (writing to specific file, standard error, filtering traces coming from specific libraries, etc.).

With default configruation, output in terminal would look like (no debug trace printed):

[error] error number: 0
[error] error number: 1
...

Otherwise, you may want to deactivate all logs:

#include <my/component.h>//global header for my-component
#include <pid/log.h>

int main(int argc, char * argv[]){
    ...
	PID_LOGGER.disable();
    //or PID_LOGGER.configure("pid_log/deactivated_logs.yaml");
	...
}

And nothing will be printed in console.

There are a few things to learn to use all the power of pid-log system, please read the online tutorial for more details.