9.6. Filters
eProsima Fast DDS logging module allows for log entry filtering when consuming the logs, so that an application execution output can be limited to specific areas of interest. Beside the Verbosity Level, Fast DDS provides three different filtering possibilities.
It is worth mentioning that filters are applied in the specific order presented above, meaning that file name filtering is only applied to the entries that pattern-match the category filter, and content filtering is only applied to the entries that pattern-match both category and file name filters.
9.6.1. Category Filtering
Log entries can be filtered upon consumption according to their Category component using regular
expressions.
Each time an entry is ready to be consumed, the category filter is applied using std::regex_search()
.
To set a category filter, member function Log::SetCategoryFilter()
is used:
// Set filter using regular expression
Log::SetCategoryFilter(std::regex("(CATEGORY_1)|(CATEGORY_2)"));
// Would be consumed
EPROSIMA_LOG_ERROR(CATEGORY_1, "First log entry");
// Would be consumed
EPROSIMA_LOG_ERROR(CATEGORY_2, "Second log entry");
// Would NOT be consumed
EPROSIMA_LOG_ERROR(CATEGORY_3, "Third log entry");
The previous example would produce the following output:
2020-05-27 15:07:05.771 [CATEGORY_FILTER_1 Error] First log entry -> Function main
2020-05-27 15:07:05.771 [CATEGORY_FILTER_2 Error] Second log entry -> Function main
9.6.2. File Name Filtering
Log entries can be filtered upon consumption according to their File Context component using
regular expressions.
Each time an entry is ready to be consumed, the file name filter is applied using std::regex_search()
.
To set a file name filter, member function Log::SetFilenameFilter()
is used:
// Filename: example.cpp
// Enable file name and line number reporting
Log::ReportFilenames(true);
// Set filter using regular expression so filename must match "example"
Log::SetFilenameFilter(std::regex("example"));
// Would be consumed
EPROSIMA_LOG_ERROR(CATEGORY, "First log entry");
// Set filter using regular expression so filename must match "other"
Log::SetFilenameFilter(std::regex("other"));
// Would NOT be consumed
EPROSIMA_LOG_ERROR(CATEGORY, "Second log entry");
The previous example would produce the following output:
2020-05-27 15:07:05.771 [CATEGORY Error] First log entry (example.cpp:50) -> Function main
Note
File name filters are applied even when the File Context entry component is disabled.
9.6.3. Content Filtering
Log entries can be filtered upon consumption according to their Message component using regular
expressions.
Each time an entry is ready to be consumed, the content filter is applied using std::regex_search()
.
To set a content filter, member function Log::SetErrorStringFilter()
is used:
// Set filter using regular expression so message component must match "First"
Log::SetErrorStringFilter(std::regex("First"));
// Would be consumed
EPROSIMA_LOG_ERROR(CATEGORY, "First log entry");
// Would NOT be consumed
EPROSIMA_LOG_ERROR(CATEGORY, "Second log entry");
The previous example would produce the following output:
2020-05-27 15:07:05.771 [CATEGORY Error] First log entry -> Function main
9.6.4. Reset Logging Filters
The logging module’s filters can be reset with member function Log::Reset()
.
Warning
Resetting the module’s filters entails:
Setting Verbosity Level to
Log::Kind::Error
.Disabling File Context component.
Enabling Function Name component.
Clear all Filters.
Clear all consumers and reset the default consumer according to CMake option
LOG_CONSUMER_DEFAULT
.