Fast RTPS includes an extensible logging system with the following class hierarchy:
Log is the entry point of the Logging system.
It exposes three macro definitions to ease its usage:
logInfo(INFO_MSG, "This is an info message"); logWarning(WARN_MSG, "This is a warning message"); logError(ERROR_MSG, "This is an error message");
In all cases,
ERROR_MSG will be used as category for the log entry as
a preprocessor string, so you can use define any category inline.
logInfo(NEW_CATEGORY, "This log message belong to NEW_CATEGORY category.");
You can control the verbosity of the log system and filter it by category:
Log::SetVerbosity(Log::Kind::Warning); std::regex my_regex("NEW_CATEGORY"); Log::SetCategoryFilter(my_regex);
The possible verbosity levels are
When selecting one of them, you also select the ones with more priority.
Log::Kind::Error, you will only receive error messages.
Log::Kind::Infowill select all of them
To filter by category, you must provide a valid
std::regex expression that will be applied to the category.
The categories that matches the expression, will be logged.
By default, the verbosity is set to
Log::Kind::Error and without category filtering.
There are some others configurable parameters:
//! Enables the reporting of filenames in log entries. Disabled by default. RTPS_DllAPI static void ReportFilenames(bool); //! Enables the reporting of function names in log entries. Enabled by default when supported. RTPS_DllAPI static void ReportFunctions(bool); //! Sets the verbosity level, allowing for messages equal or under that priority to be logged. RTPS_DllAPI static void SetVerbosity(Log::Kind); //! Returns the current verbosity level. RTPS_DllAPI static Log::Kind GetVerbosity(); //! Sets a filter that will pattern-match against log categories, dropping any unmatched categories. RTPS_DllAPI static void SetCategoryFilter (const std::regex&); //! Sets a filter that will pattern-match against filenames, dropping any unmatched categories. RTPS_DllAPI static void SetFilenameFilter (const std::regex&); //! Sets a filter that will pattern-match against the provided error string, dropping any unmatched categories. RTPS_DllAPI static void SetErrorStringFilter (const std::regex&);
LogConsumers are classes that implement how to manage the log information. They must be registered into the Log system to be called with the log messages (after filtering).
Currently there are two LogConsumer implementations:
Default consumer, it prints the logging messages to the standard output. It has no configuration available.
It prints the logging messages to a file. It has two configuration parameters:
filenamethat defines the file where the consumer will write the log messages.
appendthat indicates to the consumer if the output file must be opened to append new content.
filenameis output.log and
appendis equals to false.
If you want to add a consumer to manage the logs, you must call the
RegisterConsumer method of the Log.
To remove all consumers, including the default one, you should call the
If you want to reset the Log configuration to its defaults, including recovering the default consumer, you can call to
Log::ClearConsumers(); // Deactivate StdoutConsumer // Add FileConsumer consumer std::unique_ptr<FileConsumer> fileConsumer(new FileConsumer("append.log", true)); Log::RegisterConsumer(std::move(fileConsumer)); // Back to its defaults: StdoutConsumer will be enable and FileConsumer removed. Log::Reset();
8.2. XML Log configuration¶
You can configure the logging system through xml with the tag
<log> under the
<dds> tag, or as an
standalone file (without the
<dds> tag, just
<log> as root).
You can set
<use_default> and a set of
<consumer> is defined by its
<class> and a set of
<log> <use_default>FALSE</use_default> <consumer> <class>FileConsumer</class> <property> <name>filename</name> <value>test1.log</value> </property> <property> <name>append</name> <value>TRUE</value> </property> </consumer> </log>
<use_default> indicates if we want to use the default consumer
<consumer> defines a consumer that will be added to the consumers list of the Log.
<class> indicates which consumer class to instantiate and the set of
<property> configures it.
StdoutConsumer has no properties to be configured, but
This marks the end of this document. We recommend you to take a look at the Doxygen API reference and the embedded examples that come with the distribution. If you need more help, send us an email to firstname.lastname@example.org.