Enabling Logging via XML QoS file
This article illustrates a method on how to enable logging in a QoS XML file.
The available logging options include:
- Logging Verbosity Level
- Logging by Category
- Logging Print Format
- Logging to a File
When Logging to a file, the user has the option of applying File Set generation rules:
- File Prefix
- File Suffix
- Maximum File Size
- Maximum number of Files
In order to take advantage of XML validation, and command-line completion, make sure the schema file is included at the top of the XML file, as shown below
The various logging options will be illustrated via a simple example.
In this example:
- The verbosity is set to LOCAL for ALL categories.
- The print format is set to MAXIMAL
- Log File Options (mutually exclusive):
- No log file
- Cumulative log file
- File set
Logging is related to the participant factory. The typical location to include logging is at the top of the <qos_libary> tag section:
<dds> <qos_library ...> <!-- Logging --> <qos_profile name="factoryLogging" is_default_participant_factory_profile="true"> <participant_factory_qos> <logging> <verbosity>LOCAL</verbosity> <category>ALL</category> <print_format>MAXIMAL</print_format> <!-- Logging Option 1: no log file --> <!-- Logging Option 2: logging to a single file --> <output_file>LogFile.log</output_file> <!-- Logging Option 3: logging to a file set --> <output_file>LogFile_</output_file> <output_file_suffix>.log</output_file_suffix> <max_bytes_per_file>1000</max_bytes_per_file> <max_files>3</max_files> </logging> </participant_factory_qos> </qos_profile> ....
In the above example, the user has several logfile options.
Logging Option 1: No log file specified
If no log file is specified, the results are printed to the console (typically stdout).
Logging Option 2: Logging to a single file
If a single log file is specified, the named file grows without bounds (an existing file is overwritten).
Logging Option 3: Logging to a set of files
In this example the four parameters are:
- output_file = “LogFile_"
- output_file_suffix = “.log”
- max_bytes = 1000
- max_files = 3
If Option 3 is selected, the resultant file set could include LogFile_1.log, LogFile_2.log, and LogFile_3.log. Each file is limited to 1000 bytes.
When the last file reaches the ‘max_bytes’ specified, the logging operation will overwrite existing files (i.e. rollover takes place).
There are some subtle naming differences between options when using XML versus adding logging directly in code. The differences are mentioned in the tables below.
Table 1 - Verbosity
Verbosity | Description | Note(s) |
SILENT | No further output will be logged. | |
ERROR (default) | Only error messages will be logged. An error indicates something wrong in the functioning of RTI Connext. The most common cause of errors is an incorrect configuration. | 1 |
WARNING | Both error and warning messages will be logged. A warning indicates that RTI Connext is taking an action that may or may not be what you intended. Some configuration information is also logged at this verbosity to aid in debugging. | |
LOCAL | Errors, warnings, and verbose information about the lifecycles of local RTI Connext objects will be logged. | 2 |
REMOTE | Errors, warnings, and verbose information about the lifecycles of remote RTI Connext objects will be logged. | 2 |
ALL | Errors, warnings, verbose information about the lifecycles of local and remote RTI Connext objects and periodic information about RTI Connext threads will be logged. | 2 |
Table 2 - Category
verbosity_by_category | Description | Note(s) |
PLATFORM | Log messages pertaining to the underlying platform (hardware and OS) on which RTI Connext is running are in this category. | |
COMMUNICATION | Log messages pertaining to data serialization and deserialization and network traffic are in this category. | |
DATABASE | Log messages pertaining to the internal database in which RTI Connext objects are stored are in this category. | |
ENTITIES | Log messages pertaining to local and remote entities and to the discovery process are in this category. | |
API | Log messages pertaining to the API layer of RTI Connext (such as method argument validation) are in this category. | |
ALL | Log messages pertaining to the API layer of RTI Connext (such as method argument validation) are in this category. | 3 |
Table 3 - Print Format
Print Format | Description | Note(s) |
DEFAULT | Print message, method name, and activity context (default). | |
TIMESTAMPED | Print message, method name, activity context, and timestamp. | |
VERBOSE | Print message with all available context information (includes thread identifier, activity context) | |
VERBOSE_TIMESTAMPED | Print message with all available context information, and timestamp | |
DEBUG | Print a set of field that may be useful for internal debug. | |
MINIMAL | Print only message number and method name. | |
MAXIMAL | Print all available fields. |