Configuring Connext Logging

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 run time. 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.) See also Table 54.4 NDDSConfigLogger Operations and 54.3 Configuring Logging via XML for information on configuring 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.

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

You will typically change the verbosity of all of Connext at once. However, in the event that such a 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.6 Viewing Resolved QoS Values).
DISCOVERY	Messages pertaining to discovery.
SECURITY	Messages pertaining to Security Plugins. See Security Events and Logging, in the RTI Security Plugins User's Manual for more information.
ALL	Messages about all of the categories (default value)

The methods in the NDDSConfigLogger class can be used to change verbosity settings, as well as 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.
Change Verbosity for all Categories	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.
Change Verbosity for a Specific Category	set_verbosity_by_category	Gets/Sets the verbosity for a specific 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.2 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.2 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.1 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

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

NDDS_Config_Logger_set_verbosity_by_category(

    logger,

    NDDS_CONFIG_LOG_CATEGORY_SECURITY,

    NDDS_CONFIG_LOG_VERBOSITY_STATUS_ALL);