9.5. Module Configuration

The logging module offers a variety of configuration options. The different components of a log entry (see Log Entry Specification) can be configured as explained in Log Entry. Furthermore, the logging module allows for registering several log consumer, allowing applications to direct the logging output to different destinations (see Register Consumers). In addition, some of the logging features can be configured using eProsima Fast DDS XML configuration files (see XML Configuration).

9.5.1. Log Entry

All the different components of a log entry are summarized in the following table (please refer to each component’s section for further explanation):

Component

Optional

Default

Timestamp

NO

ENABLED

Category

NO

ENABLED

Verbosity Level

NO

ENABLED

Message

NO

ENABLED

File Context

YES

DISABLED

Function Name

YES

ENABLED

9.5.1.1. Timestamp

The log timestamp follows the ISO 8601 standard for local timestamps, i.e. YYYY-MM-DD hh:mm:ss.sss. This component cannot be further configured or disabled.

9.5.1.2. Category

Log entries have a category assigned when producing the log via the macros presented in Logging Messages. The category component can be used to filter log entries so that only those categories specified in the filter are consumed (see Filters). This component cannot be further configured or disabled.

9.5.1.3. Verbosity Level

eProsima Fast DDS logging module provides three verbosity levels defined by the Log::Kind enumeration, those are:

The logging module’s verbosity level defaults to Log::Kind::Error, which means that only messages logged with logError would be consumed. The verbosity level can be set and retrieved using member functions Log::SetVerbosity() and Log::GetVerbosity() respectively.

// Set log verbosity level to Log::Kind::Info
Log::SetVerbosity(Log::Kind::Info);

// Get log verbosity level
Log::Kind verbosity_level = Log::GetVerbosity();

Warning

Setting any of the CMake options LOG_NO_INFO, LOG_NO_WARNING or LOG_NO_ERROR to ON will completely disable the corresponding verbosity level. LOG_NO_INFO is set to ON as default value if not in Debug mode.

9.5.1.4. Message

This component constitutes the body of the log entry. It is specified when producing the log via the macros presented in Logging Messages. The message component can be used to filter log entries so that only those entries whose message pattern-matches the filter are consumed (see Filters). This component cannot be further configured or disabled.

9.5.1.5. File Context

This component specifies the origin of the log entry in terms of file name and line number (see Logging Messages for a log entry example featuring this component). This is useful when tracing code flow for debugging purposes. The file context component can be enabled/disabled using the member function Log::ReportFilenames().

// Enable file name and line number reporting
Log::ReportFilenames(true);

// Disable file name and line number reporting
Log::ReportFilenames(false);

9.5.1.6. Function Name

This component specifies the origin of the log entry in terms of the function name (see Logging Messages for a log entry example featuring this component). This is useful when tracing code flow for debugging purposes. The function name component can be enabled/disabled using the member function Log::ReportFunctions().

// Enable function name reporting
Log::ReportFunctions(true);

// Disable function name reporting
Log::ReportFunctions(false);

9.5.2. Register Consumers

eProsima Fast DDS logging module supports zero or more consumers logging the entries registered in the logging queue with the methods described in Logging Messages. To register a consumer, the Log class exposes member function Log::RegisterConsumer()

// Create a FileConsumer consumer that logs entries in "archive.log"
std::unique_ptr<FileConsumer> file_consumer(new FileConsumer("archive.log"));
// Register the consumer. Log entries will be logged to STDOUT and "archive.log"
Log::RegisterConsumer(std::move(file_consumer));

The consumers list can be emptied with member function Log::ClearConsumers().

// Clear all the consumers. Log entries are discarded upon consumption.
Log::ClearConsumers();

Note

Registering and configuring consumers can also be done using Fast DDS XML configuration files. Please refer to XML Configuration for details.

Warning

Log::ClearConsumers() empties the consumers lists. All log entries are discarded until a new consumer is register via Log::RegisterConsumer(), or until Log::Reset() is called.

9.5.3. Reset Configuration

The logging module’s configuration can be reset to default settings with member function Log::Reset().

Warning

Resetting the module’s configuration entails:

9.5.4. XML Configuration

eProsima Fast DDS allows for registering and configuring log consumers using XML configuration files. Please refer to Log profiles for details.