Enabling Logging via XML QoS file

Submitted by garyb on Thu, 12/05/2019 - 08:16

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

         

See QoS File XML Validation for additional information.
 

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

Note(s):
1 -  In code, this option is EXCEPTION rather than ERROR
2 -  In code, these options are prepended with STATUS_
 

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

Note(s):
3 -   In code, this option is ALL_CATEGORIES rather than ALL.

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.

 



 
 
 
 
Keywords: