54.2 Configuring Connext Logging

Connext's builtin logging system provides several types of messages to help you debug your system and alert you to errors during runtime. You can control how much information is reported and where it is logged. By default, the builtin logging system writes to the standard output, but you can configure it to use a logging file or an output device such as a custom logging device or the Distributed Logger. (See 54.6 RTI Distributed Logger.) Using the RTI Connext Observability Framework (see the RTI Observability Framework documentation), you can also distribute and store the messages into a third-party, log aggregator backend.

This section provides information that describes how to configure the builtin logging system.

How much information is logged is known as the verbosity setting. Table 54.2 Message Logging Verbosity Levels describes the increasing verbosity levels. Note that the verbosities are cumulative: logging at a high verbosity means also logging all lower verbosity messages. If you change nothing, the default verbosity will be set to NDDS_CONFIG_LOG_VERBOSITY_ERROR.

Logging at high verbosities can be detrimental to your application's performance. You should generally not set the verbosity above NDDS_CONFIG_LOG_VERBOSITY_WARNING, unless you are debugging a specific problem.

Note: The APIs documented in this section are the Traditional C++ APIs. For information in other languages, see the following section in your language's API Reference HTML documentation: Modules > RTI Connext DDS API Reference > Logging and Version.

Table 54.2 Message Logging Verbosity Levels

Verbosity (NDDS_CONFIG_ LOG_VERBOSITY_*)	Description	Log level values corresponding to this verbosity (NDDS_CONFIG_LOG_LEVEL_*)
SILENT	No messages will be logged. (lowest verbosity)	-
ERROR (default level for all categories)	Log only high-priority error messages. An error indicates something is wrong with how Connext is functioning. The most common cause of this type of error is an incorrect configuration.	ERROR, FATAL_ERROR
WARNING	Additionally log warning messages. A warning indicates that 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.	WARNING, ERROR, FATAL_ERROR
STATUS_LOCAL	Additionally log verbose information about the lifecycles of local Connext objects.	STATUS_LOCAL, WARNING, ERROR, FATAL_ERROR
STATUS_REMOTE	Additionally log verbose information about the lifecycles of remote Connext objects.	STATUS_REMOTE, STATUS_LOCAL, WARNING, ERROR, FATAL_ERROR
STATUS_ALL	Additionally log verbose information about periodic activities and Connext threads. (highest verbosity)	DEBUG, STATUS_REMOTE, STATUS_LOCAL, WARNING, ERROR, FATAL_ERROR

In addition to the builtin logging system verbosity and log levels, Connext also works with standard Syslog verbosity and log levels. Syslog levels are used by some modules in Connext, and sometimes Connext has to translate between Syslog and its own builtin log levels. See 54.2.1 Syslog Level and Verbosity Mapping for additional information.

You will typically change the verbosity of all of Connext at once. However, if this strategy produces too much output, you can further discriminate among the messages you would like to see. The types of messages logged by Connext fall into the categories listed in Table 54.3 Message Logging Categories; each category can be set to a different verbosity level.

Table 54.3 Message Logging Categories

Category (NDDS_CONFIG_ LOG_CATEGORY_*)	Description
PLATFORM	Messages about the underlying platform (hardware and OS).
COMMUNICATION	Messages about data serialization and deserialization, and network traffic.
DATABASE	Messages about the internal database of Connext objects.
ENTITIES	Messages about local and remote entities and some of the discovery process. (To see all discovery-related messages, use the DISCOVERY category.)
API	Messages about Connext’s API layer, such as method argument validation and what QoS is being used (for details on QoS information, see 50.2.3.7 Viewing Resolved QoS Values).
DISCOVERY	Messages pertaining to discovery.
SECURITY	Messages pertaining to security. These messages include any security-related messages logged by Connext components even if they are not related to the Security Plugins.
USER	Messages generated by the user via the user log APIs described in Table 54.4 NDDSConfigLogger Operations.
ALL	Messages about all of the categories (default value)

The Connext builtin logging system is a singleton that can be obtained using the operation NDDSConfigLogger::get_instance().

The methods in the NDDSConfigLogger class can be used to change verbosity settings, log application-level (USER) log messages, and configure the destination and format of the logged messages. Table 54.4 NDDSConfigLogger Operations lists the available operations; consult the API Reference HTML documentation for more information.

Table 54.4 NDDSConfigLogger Operations

Purpose	Operation	Description
Change Verbosity for all Categories	get_verbosity	Gets the current verbosity. If per-category verbosities are used, returns the highest verbosity of any category.
	set_verbosity	Sets the verbosity of all categories.
Change Verbosity for a Specific Category	get_verbosity_by_category	Gets/Sets the verbosity for a specific category.
	set_verbosity_by_category
Change Destination of Logged Messages	get_output_file	Returns the file to which messages are being logged, or NULL for the default destination (standard output on most platforms).
	set_output_file	Redirects future logged messages to a set of files. For better performance when log messages are generated frequently, the log messages are not flushed into a file immediately after they are generated. In other words, while writing a log message, Connext only calls the function fwrite(); it does not call the function fflush(). If your application requires a different flushing behavior, you may configure a custom logging device (see 54.2.4 Customizing the Handling of Generated Log Messages).
	get_output_device	Returns the logging device installed with the logger.
	set_output_device	Registers a specified logging device with the logger. See 54.2.4 Customizing the Handling of Generated Log Messages
Change Message Format	get_print_format	Gets/Sets the current message format for the log level NDDS_CONFIG_LOG_LEVEL_ERROR. See 54.2.3 Format of Logged Messages. Use get_print_format_by_log_level and set_print_format_by_log_level to retrieve/set the format for other log levels.
	set_print_format
	get_print_format_by_log_level	Gets/Sets the current message format, by log level, that Connext is using to log diagnostic information.
	set_print_format_by_log_level
Log USER messages (based on Syslog levels)	emergency	Logs message with NDDS_CONFIG_SYSLOG_LEVEL_EMERGENCY and NDDS_CONFIG_LOG_CATEGORY_USER.
	alert	Logs message with NDDS_CONFIG_SYSLOG_LEVEL_ALERT and NDDS_CONFIG_LOG_CATEGORY_USER.
	critical	Logs message with NDDS_CONFIG_SYSLOG_LEVEL_CRITICAL and NDDS_CONFIG_LOG_CATEGORY_USER.
	error	Logs message with NDDS_CONFIG_SYSLOG_LEVEL_ERROR and NDDS_CONFIG_LOG_CATEGORY_USER.
	warning	Logs message with NDDS_CONFIG_SYSLOG_LEVEL_WARNING and NDDS_CONFIG_LOG_CATEGORY_USER.
	notice	Logs message with NDDS_CONFIG_SYSLOG_LEVEL_NOTICE and NDDS_CONFIG_LOG_CATEGORY_USER.
	informational	Logs message with NDDS_CONFIG_SYSLOG_LEVEL_INFORMATIONAL and NDDS_CONFIG_LOG_CATEGORY_USER.
	debug	Logs message with NDDS_CONFIG_SYSLOG_LEVEL_DEBUG and NDDS_CONFIG_LOG_CATEGORY_USER.

For example, to change the verbosity of all messages in the SECURITY category:

NDDSConfigLogger::get_instance()->set_verbosity_by_category(

        NDDS_CONFIG_LOG_CATEGORY_SECURITY,

        NDDS_CONFIG_LOG_VERBOSITY_STATUS_ALL);