8. Logging

Fast RTPS includes an extensible logging system with the following class hierarchy:

../../_images/logging.png

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, INFO_MSG, WARN_MSG and 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 Log::Kind::Info, Log::Kind::Warning and Log::Kind::Error.

When selecting one of them, you also select the ones with more priority.

  • Selecting Log::Kind::Error, you will only receive error messages.

  • Selecting Log::Kind::Warning you select Log::Kind::Error too.

  • Selecting Log::Kind::Info will 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&);

8.1. LogConsumers

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:

  • StdoutConsumer:

    Default consumer, it prints the logging messages to the standard output. It has no configuration available.

  • FileConsumer:

    It prints the logging messages to a file. It has two configuration parameters:

    • filename that defines the file where the consumer will write the log messages.

    • append that indicates to the consumer if the output file must be opened to append new content.

    By default, filename is output.log and append is 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 ClearConsumers method. If you want to reset the Log configuration to its defaults, including recovering the default consumer, you can call to its Reset method.

    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>. Each <consumer> is defined by its <class> and a set of <property>.

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

Each <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 FileConsumer has filename and append.

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 support@eprosima.com.