Logging

Configure how much debugging information is reported during runtime and where it is logged. More...

Modules
	Activity Context
	Add contextual information to log messages.

Data Structures
struct	NDDS_Config_Logger
	<<interface>> The singleton type used to configure RTI Connext logging. More...
struct	NDDS_Config_LogMessage
	Log message. More...
struct	NDDS_Config_LoggerDevice
	<<interface>> Logging device interface. Use for user-defined logging devices. More...

Typedefs
typedef void(*	NDDS_Config_LoggerDeviceWriteFnc) (struct NDDS_Config_LoggerDevice *device, const struct NDDS_Config_LogMessage *message)
	Prototype of a NDDS_Config_LoggerDevice write function. More...
typedef void(*	NDDS_Config_LoggerDeviceCloseFnc) (struct NDDS_Config_LoggerDevice *device)
	Prototype of a NDDS_Config_LoggerDevice close function. More...

Enumerations
enum	NDDS_Config_LogVerbosity {   NDDS_CONFIG_LOG_VERBOSITY_SILENT,   NDDS_CONFIG_LOG_VERBOSITY_ERROR,   NDDS_CONFIG_LOG_VERBOSITY_WARNING,   NDDS_CONFIG_LOG_VERBOSITY_STATUS_LOCAL,   NDDS_CONFIG_LOG_VERBOSITY_STATUS_REMOTE,   NDDS_CONFIG_LOG_VERBOSITY_STATUS_ALL }
	The verbosities at which RTI Connext diagnostic information is logged. More...
enum	NDDS_Config_LogLevel {   NDDS_CONFIG_LOG_LEVEL_FATAL_ERROR,   NDDS_CONFIG_LOG_LEVEL_ERROR,   NDDS_CONFIG_LOG_LEVEL_WARNING,   NDDS_CONFIG_LOG_LEVEL_STATUS_LOCAL,   NDDS_CONFIG_LOG_LEVEL_STATUS_REMOTE,   NDDS_CONFIG_LOG_LEVEL_DEBUG }
	Level category assigned to RTI Connext log messages returned to an output device. More...
enum	NDDS_Config_LogCategory {   NDDS_CONFIG_LOG_CATEGORY_PLATFORM,   NDDS_CONFIG_LOG_CATEGORY_COMMUNICATION,   NDDS_CONFIG_LOG_CATEGORY_DATABASE,   NDDS_CONFIG_LOG_CATEGORY_ENTITIES,   NDDS_CONFIG_LOG_CATEGORY_API,   NDDS_CONFIG_LOG_CATEGORY_ALL }
	Categories of logged messages. More...
enum	NDDS_Config_LogPrintFormat { ,   NDDS_CONFIG_LOG_PRINT_FORMAT_DEFAULT,   NDDS_CONFIG_LOG_PRINT_FORMAT_TIMESTAMPED,   NDDS_CONFIG_LOG_PRINT_FORMAT_VERBOSE,   NDDS_CONFIG_LOG_PRINT_FORMAT_VERBOSE_TIMESTAMPED,   NDDS_CONFIG_LOG_PRINT_FORMAT_DEBUG,   NDDS_CONFIG_LOG_PRINT_FORMAT_MINIMAL,   NDDS_CONFIG_LOG_PRINT_FORMAT_MAXIMAL }
	The format used to output RTI Connext diagnostic information. More...

Functions
NDDS_Config_Logger *	NDDS_Config_Logger_get_instance (void)
	Get the singleton instance of this type. More...
NDDS_Config_LogVerbosity	NDDS_Config_Logger_get_verbosity (const NDDS_Config_Logger *self)
	Get the verbosity at which RTI Connext is currently logging diagnostic information. More...
NDDS_Config_LogVerbosity	NDDS_Config_Logger_get_verbosity_by_category (const NDDS_Config_Logger *self, NDDS_Config_LogCategory category)
	Get the verbosity at which RTI Connext is currently logging diagnostic information in the given category. More...
void	NDDS_Config_Logger_set_verbosity (NDDS_Config_Logger *self, NDDS_Config_LogVerbosity verbosity)
	Set the verbosity at which RTI Connext will log diagnostic information. More...
void	NDDS_Config_Logger_set_verbosity_by_category (NDDS_Config_Logger *self, NDDS_Config_LogCategory category, NDDS_Config_LogVerbosity verbosity)
	Set the verbosity at which RTI Connext will log diagnostic information in the given category. More...
FILE *	NDDS_Config_Logger_get_output_file (NDDS_Config_Logger *self)
	Get the file to which the logged output is redirected. More...
DDS_Boolean	NDDS_Config_Logger_set_output_file (NDDS_Config_Logger *self, FILE *out)
	Set the file to which the logged output is redirected. More...
DDS_Boolean	NDDS_Config_Logger_set_output_file_name (NDDS_Config_Logger *self, const char *file_name)
	Set the name of the file to which the logged output is redirected. More...
DDS_Boolean	NDDS_Config_Logger_set_output_file_set (NDDS_Config_Logger *self, const char *file_preffix, const char *file_suffix, int max_capacity, int max_files)
	Configure a set of files to redirect the logged output. More...
NDDS_Config_LogPrintFormat	NDDS_Config_Logger_get_print_format (const NDDS_Config_Logger *self)
	Get the current message format for the log level NDDS_CONFIG_LOG_LEVEL_ERROR. More...
NDDS_Config_LogPrintFormat	NDDS_Config_Logger_get_print_format_by_log_level (const NDDS_Config_Logger *self, NDDS_Config_LogLevel log_level)
	Get the current message format, by log level, that RTI Connext is using to log diagnostic information. More...
DDS_Boolean	NDDS_Config_Logger_set_print_format (NDDS_Config_Logger *self, NDDS_Config_LogPrintFormat print_format)
	Set the message format that RTI Connext will use to log diagnostic information for all the log levels, except for NDDS_CONFIG_LOG_LEVEL_FATAL_ERROR. When the Activity Context is printed, the user can select the information that will be part of the Activity Context by using the API NDDS_Config_ActivityContext_set_attribute_mask. More...
DDS_Boolean	NDDS_Config_Logger_set_print_format_by_log_level (NDDS_Config_Logger *self, NDDS_Config_LogPrintFormat print_format, NDDS_Config_LogLevel log_level)
	Set the message format that RTI Connext will use to log diagnostic information for all the log levels, except for NDDS_CONFIG_LOG_LEVEL_FATAL_ERROR. When the Activity Context is printed, the user can select the information that will be part of the Activity Context by using the API NDDS_Config_ActivityContext_set_attribute_mask. More...
struct NDDS_Config_LoggerDevice *	NDDS_Config_Logger_get_output_device (NDDS_Config_Logger *self)
	Return the user device registered with the logger. More...
DDS_Boolean	NDDS_Config_Logger_set_output_device (NDDS_Config_Logger *self, struct NDDS_Config_LoggerDevice *device)
	Register a NDDS_Config_LoggerDevice. More...

Detailed Description

Configure how much debugging information is reported during runtime and where it is logged.

Typedef Documentation

NDDS_Config_LoggerDeviceWriteFnc

typedef void(* NDDS_Config_LoggerDeviceWriteFnc) (struct NDDS_Config_LoggerDevice *device, const struct NDDS_Config_LogMessage *message)

Prototype of a NDDS_Config_LoggerDevice write function.

Write a log message to the input device.

Note: It is not safe to make any calls to the RTI Connext core library, including calls to DDS_DomainParticipant_get_current_time, from any of the logging device operations.

Parameters

device	<<in>> Logging device.
message	<<in>> Message to log.

NDDS_Config_LoggerDeviceCloseFnc

typedef void(* NDDS_Config_LoggerDeviceCloseFnc) (struct NDDS_Config_LoggerDevice *device)

Prototype of a NDDS_Config_LoggerDevice close function.

Close the input device.

Note: It is not safe to make any calls to the RTI Connext core library, including calls to DDS_DomainParticipant_get_current_time, from any of the logging device operations.

Parameters

device

<<in>> Logging device.

Enumeration Type Documentation

NDDS_Config_LogVerbosity

enum NDDS_Config_LogVerbosity

The verbosities at which RTI Connext diagnostic information is logged.

Enumerator
NDDS_CONFIG_LOG_VERBOSITY_SILENT	No further output will be logged.
NDDS_CONFIG_LOG_VERBOSITY_ERROR	Only error and fatal error messages will be logged. An error indicates something wrong in the functioning of RTI Connext. The most common cause of errors is incorrect configuration.
NDDS_CONFIG_LOG_VERBOSITY_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.
NDDS_CONFIG_LOG_VERBOSITY_STATUS_LOCAL	Errors, warnings, and verbose information about the lifecycles of local RTI Connext objects will be logged.
NDDS_CONFIG_LOG_VERBOSITY_STATUS_REMOTE	Errors, warnings, and verbose information about the lifecycles of remote RTI Connext objects will be logged.
NDDS_CONFIG_LOG_VERBOSITY_STATUS_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.

NDDS_Config_LogLevel

enum NDDS_Config_LogLevel

Level category assigned to RTI Connext log messages returned to an output device.

Enumerator
NDDS_CONFIG_LOG_LEVEL_FATAL_ERROR	The message describes a fatal error. A fatal error indicates an unrecoverable situation in the functioning of RTI Connext. Error messages with this log level usually indicate a violation of an internal invariant or a segfault, and may include the function call stack where the fatal error happened.
NDDS_CONFIG_LOG_LEVEL_ERROR	The message describes an error. An error indicates a non-fatal problem in the functioning of RTI Connext. Errors are usually recoverable and will not stop application execution, although they may prevent some features from working properly. The most common cause of non-fatal errors is incorrect configuration and incorrect arguments.
NDDS_CONFIG_LOG_LEVEL_WARNING	The message describes a warning. 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.
NDDS_CONFIG_LOG_LEVEL_STATUS_LOCAL	The message contains information about the lifecycles of local RTI Connext objects will be logged.
NDDS_CONFIG_LOG_LEVEL_STATUS_REMOTE	The message contains information about the lifecycles of remote RTI Connext objects will be logged.
NDDS_CONFIG_LOG_LEVEL_DEBUG	The message contains debug information that might be relevant to your application.

NDDS_Config_LogCategory

enum NDDS_Config_LogCategory

Categories of logged messages.

The NDDS_Config_Logger_get_verbosity_by_category and NDDS_Config_Logger_set_verbosity_by_category can be used to specify different verbosities for different categories of messages.

Enumerator
NDDS_CONFIG_LOG_CATEGORY_PLATFORM	Log messages pertaining to the underlying platform (hardware and OS) on which RTI Connext is running are in this category.
NDDS_CONFIG_LOG_CATEGORY_COMMUNICATION	Log messages pertaining to data serialization and deserialization and network traffic are in this category.
NDDS_CONFIG_LOG_CATEGORY_DATABASE	Log messages pertaining to the internal database in which RTI Connext objects are stored are in this category.
NDDS_CONFIG_LOG_CATEGORY_ENTITIES	Log messages pertaining to local and remote entities and to the discovery process are in this category.
NDDS_CONFIG_LOG_CATEGORY_API	Log messages pertaining to the API layer of RTI Connext (such as function argument validation) are in this category.
NDDS_CONFIG_LOG_CATEGORY_ALL	Log messages pertaining to all category of RTI Connext.

NDDS_Config_LogPrintFormat

enum NDDS_Config_LogPrintFormat

The format used to output RTI Connext diagnostic information.

Enumerator
NDDS_CONFIG_LOG_PRINT_FORMAT_DEFAULT	(default) Print message, method name, and Activity Context (what was happening when the event occurred).
NDDS_CONFIG_LOG_PRINT_FORMAT_TIMESTAMPED	Print message, method name, Activity Context, and timestamp.
NDDS_CONFIG_LOG_PRINT_FORMAT_VERBOSE	Print message with all available context information (includes thread identifier, Activity Context).
NDDS_CONFIG_LOG_PRINT_FORMAT_VERBOSE_TIMESTAMPED	Print message with all available context information, and timestamp.
NDDS_CONFIG_LOG_PRINT_FORMAT_DEBUG	Print a set of fields (including the Activity Context and backtrace information) that may be useful for internal debugging.
NDDS_CONFIG_LOG_PRINT_FORMAT_MINIMAL	Print only message number and method name.
NDDS_CONFIG_LOG_PRINT_FORMAT_MAXIMAL	Print all available fields (including backtrace information).

Function Documentation

NDDS_Config_Logger_get_instance()

NDDS_Config_Logger* NDDS_Config_Logger_get_instance

(

void

)

Get the singleton instance of this type.

NDDS_Config_Logger_get_verbosity()

NDDS_Config_LogVerbosity NDDS_Config_Logger_get_verbosity

(

const NDDS_Config_Logger *

self

)

Get the verbosity at which RTI Connext is currently logging diagnostic information.

The default verbosity if NDDS_Config_Logger_set_verbosity is never called is NDDS_CONFIG_LOG_VERBOSITY_ERROR.

If NDDS_Config_Logger_set_verbosity_by_category has been used to set different verbosities for different categories of messages, this function will return the maximum verbosity of all categories.

NDDS_Config_Logger_get_verbosity_by_category()

NDDS_Config_LogVerbosity NDDS_Config_Logger_get_verbosity_by_category	(	const NDDS_Config_Logger *	self,
		NDDS_Config_LogCategory	category
	)

Get the verbosity at which RTI Connext is currently logging diagnostic information in the given category.

The default verbosity if NDDS_Config_Logger_set_verbosity and NDDS_Config_Logger_set_verbosity_by_category are never called is NDDS_CONFIG_LOG_VERBOSITY_ERROR.

NDDS_Config_Logger_set_verbosity()

void NDDS_Config_Logger_set_verbosity	(	NDDS_Config_Logger *	self,
		NDDS_Config_LogVerbosity	verbosity
	)

Set the verbosity at which RTI Connext will log diagnostic information.

Note: Logging at high verbosities will be detrimental to your application's performance. Your default setting should typically remain at NDDS_CONFIG_LOG_VERBOSITY_WARNING or below. (The default verbosity if you never set it is NDDS_CONFIG_LOG_VERBOSITY_ERROR.)

NDDS_Config_Logger_set_verbosity_by_category()

void NDDS_Config_Logger_set_verbosity_by_category	(	NDDS_Config_Logger *	self,
		NDDS_Config_LogCategory	category,
		NDDS_Config_LogVerbosity	verbosity
	)

Set the verbosity at which RTI Connext will log diagnostic information in the given category.

NDDS_Config_Logger_get_output_file()

FILE* NDDS_Config_Logger_get_output_file

(

NDDS_Config_Logger *

self

)

Get the file to which the logged output is redirected.

If no output file has been registered through NDDS_Config_Logger_set_output_file, this function will return NULL. In this case, logged output will on most platforms go to standard out as if through printf.

NDDS_Config_Logger_set_output_file()

DDS_Boolean NDDS_Config_Logger_set_output_file	(	NDDS_Config_Logger *	self,
		FILE *	out
	)

Set the file to which the logged output is redirected.

The file passed may be NULL, in which case further logged output will be redirected to the platform-specific default output location (standard out on most platforms).

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, RTI Connext only calls the function fwrite() (see https://pubs.opengroup.org/onlinepubs/009695399/functions/fwrite.html); it does not call the function fflush() (see https://pubs.opengroup.org/onlinepubs/009695399/functions/fflush.html). If your application requires a different flushing behavior, you may use NDDS_Config_Logger_set_output_device to configure a custom logging device.

NDDS_Config_Logger_set_output_file_name()

DDS_Boolean NDDS_Config_Logger_set_output_file_name	(	NDDS_Config_Logger *	self,
		const char *	file_name
	)

Set the name of the file to which the logged output is redirected.

The name may be NULL, in which case further logged output will be redirected to the platform-specific default output location (standard out on most platforms).

See NDDS_Config_Logger_set_output_file for the flushing behavior.

NDDS_Config_Logger_set_output_file_set()

DDS_Boolean NDDS_Config_Logger_set_output_file_set	(	NDDS_Config_Logger *	self,
		const char *	file_preffix,
		const char *	file_suffix,
		int	max_capacity,
		int	max_files
	)

Configure a set of files to redirect the logged output.

The logged output will be redirected to a set of files whose names are configured with a prefix and a suffix. The maximum number of bytes configures how many bytes to write into a file before opening the next file. After reaching the maximum number of files, the first one is overwritten.

For example, if the prefix is 'Foo', the suffix is '.txt', the max number of bytes is 1GB, and the max number of files is 3, the logger will create (at most) these files: Foo1.txt, Foo2.txt, and Foo3.txt. It will write to Foo1.txt, and after writing 1GB, it will move on to Foo2.txt, then to Foo3.txt, then to Foo1.txt again, and so on.

To stop logging to these files and redirect the output to the platform-specific location, pass NULL, NULL, 0, 0.

See NDDS_Config_Logger_set_output_file for the flushing behavior.

NDDS_Config_Logger_get_print_format()

NDDS_Config_LogPrintFormat NDDS_Config_Logger_get_print_format

(

const NDDS_Config_Logger *

self

)

Get the current message format for the log level NDDS_CONFIG_LOG_LEVEL_ERROR.

Use NDDS_Config_Logger_get_print_format_by_log_level to retrieve the format for other log levels.

If NDDS_Config_Logger_set_print_format is never called, the default format is NDDS_CONFIG_LOG_PRINT_FORMAT_DEFAULT.

NDDS_Config_Logger_get_print_format_by_log_level()

NDDS_Config_LogPrintFormat NDDS_Config_Logger_get_print_format_by_log_level	(	const NDDS_Config_Logger *	self,
		NDDS_Config_LogLevel	log_level
	)

Get the current message format, by log level, that RTI Connext is using to log diagnostic information.

If NDDS_Config_Logger_set_print_format is never called, the default format is NDDS_CONFIG_LOG_PRINT_FORMAT_DEFAULT.

NDDS_Config_Logger_set_print_format()

DDS_Boolean NDDS_Config_Logger_set_print_format	(	NDDS_Config_Logger *	self,
		NDDS_Config_LogPrintFormat	print_format
	)

Set the message format that RTI Connext will use to log diagnostic information for all the log levels, except for NDDS_CONFIG_LOG_LEVEL_FATAL_ERROR. When the Activity Context is printed, the user can select the information that will be part of the Activity Context by using the API NDDS_Config_ActivityContext_set_attribute_mask.

Set print mask for all the log levels, except for (RTI_LOG_LEVEL_FATAL_ERROR).

NDDS_Config_Logger_set_print_format_by_log_level()

DDS_Boolean NDDS_Config_Logger_set_print_format_by_log_level	(	NDDS_Config_Logger *	self,
		NDDS_Config_LogPrintFormat	print_format,
		NDDS_Config_LogLevel	log_level
	)

Set the message format that RTI Connext will use to log diagnostic information for all the log levels, except for NDDS_CONFIG_LOG_LEVEL_FATAL_ERROR. When the Activity Context is printed, the user can select the information that will be part of the Activity Context by using the API NDDS_Config_ActivityContext_set_attribute_mask.

NDDS_Config_Logger_get_output_device()

struct NDDS_Config_LoggerDevice* NDDS_Config_Logger_get_output_device

(

NDDS_Config_Logger *

self

)

Return the user device registered with the logger.

Parameters

self	<<in>> Cannot be NULL.

Returns

Registered user device or NULL if no user device is registered.

NDDS_Config_Logger_set_output_device()

DDS_Boolean NDDS_Config_Logger_set_output_device	(	NDDS_Config_Logger *	self,
		struct NDDS_Config_LoggerDevice *	device
	)

Register a NDDS_Config_LoggerDevice.

Register the specified logging device with the logger.

There can be at most only one device registered with the logger at any given time.

When a device is installed, the logger will stop sending the log messages to the standard output and to the file set with NDDS_Config_Logger_set_output_file.

To remove an existing device, use this function with NULL as the device parameter. After a device is removed the logger will continue sending log messages to the standard output and to the output file.

To replace an existing device with a new device, use this function providing the new device as the device parameter.

When a device is unregistered (by setting it to NULL), NDDS_Config_LoggerDevice calls the function NDDS_Config_LoggerDevice::close.

Parameters

self	<<in>> Cannot be NULL.
device	<<in>> Logging device.