RTI Distributed Logger API Version 7.1.0
RTI Distributed Logger API

This module contains common definitions such as RTI Distributed Logger singleton, message sending functions, and general configuration. More...

Modules

 RTI Distributed Logger Options API
 Customize RTI Distributed Logger using this API.
 
 RTI Distributed Logger Utility Module
 Commodity functions to work with RTI Distributed Logger .
 
 RTI Distributed Logger Version Module
 

Data Structures

struct  RTI_DL_DistLogger_MessageParams
 Input parameters for RTI_DL_DistLogger_logMessageWithParams. More...
 
struct  RTI_DL_DistLogger
 Struct defining RTI Distributed Logger singleton. More...
 

Functions

RTI_DL_DistLoggerRTI_DL_DistLogger_getInstance (void)
 Provides access to the RTI_DL_DistLogger singleton. More...
 
DDS_ReturnCode_t RTI_DL_DistLogger_setFilterLevel (RTI_DL_DistLogger *self, DDS_Long newLevel)
 Sets the filter level for the singleton. More...
 
RTIBool RTI_DL_DistLogger_setOptions (RTI_DL_Options *options)
 Assigns configurable options to RTI Distributed Logger before its creation. More...
 
RTIBool RTI_DL_DistLogger_setRTILoggerPrintFormat (RTI_DL_DistLogger *self, NDDS_Config_LogPrintFormat logPrintFormat)
 Sets PrintFormat of RTI Logger to the provided value. More...
 
void RTI_DL_DistLogger_setRTILoggerVerbosityByCategory (RTI_DL_DistLogger *self, NDDS_Config_LogCategory category, NDDS_Config_LogVerbosity verbosity)
 Updates the LogCategory and the LogVerbosity in RTI Logger to the provided value. More...
 
void RTI_DL_DistLogger_logMessageWithLevelCategory (RTI_DL_DistLogger *self, int logLevel, const char *message, const char *category)
 Logs a message at the specified level and with the specified category. More...
 
void RTI_DL_DistLogger_logMessageWithParams (RTI_DL_DistLogger *self, const struct RTI_DL_DistLogger_MessageParams *params)
 Performs the same function as RTI_DL_DistLogger_logMessageWithLevelCategory except that it also allows specification of the message timestamp. More...
 
void RTI_DL_DistLogger_fatal (RTI_DL_DistLogger *self, const char *message)
 Logs a fatal message. More...
 
void RTI_DL_DistLogger_severe (RTI_DL_DistLogger *self, const char *message)
 Logs a severe message. More...
 
void RTI_DL_DistLogger_error (RTI_DL_DistLogger *self, const char *message)
 Logs a error message. More...
 
void RTI_DL_DistLogger_warning (RTI_DL_DistLogger *self, const char *message)
 Logs a warning message. More...
 
void RTI_DL_DistLogger_notice (RTI_DL_DistLogger *self, const char *message)
 Logs a notice message. More...
 
void RTI_DL_DistLogger_info (RTI_DL_DistLogger *self, const char *message)
 Logs a info message. More...
 
void RTI_DL_DistLogger_debug (RTI_DL_DistLogger *self, const char *message)
 Logs a debug message. More...
 
void RTI_DL_DistLogger_trace (RTI_DL_DistLogger *self, const char *message)
 Logs a trace message. More...
 
void RTI_DL_DistLogger_log (RTI_DL_DistLogger *self, int logLevel, const char *message)
 Logs a message. More...
 
DDS_ReturnCode_t RTI_DL_DistLogger_finalizeInstance (void)
 Finalizes and deletes the RTI Distributed Logger singleton. More...
 
DDS_Long RTI_DL_DistLogger_get_fatal_log_level (void)
 Return Fatal log level. More...
 
DDS_Long RTI_DL_DistLogger_get_error_log_level (void)
 Return Error log level. More...
 
DDS_Long RTI_DL_DistLogger_get_warning_log_level (void)
 Return Warning log level. More...
 
DDS_Long RTI_DL_DistLogger_get_notice_log_level (void)
 Return Notice log level. More...
 
DDS_Long RTI_DL_DistLogger_get_info_log_level (void)
 Return Info log level. More...
 
DDS_Long RTI_DL_DistLogger_get_debug_log_level (void)
 Return Debug log level. More...
 

Detailed Description

This module contains common definitions such as RTI Distributed Logger singleton, message sending functions, and general configuration.

This module provides an API to publish log messages to a DDS Topic. Generally this API is used by an application logging infrastructure to integrate it into an application, although it is also possible to use the API directly. In general, the steps to customize and use RTI Distributed Logger are the following:

  1. Customize your RTI Distributed Logger using the RTI Distributed Logger Options API. RTI_DL_Options must be set before creating the RTI_DL_DistLogger.
  2. Assign the newly created options to RTI Distributed Logger using RTI_DL_DistLogger_setOptions.
  3. Create your RTI Distributed Logger API using RTI_DL_DistLogger_getInstance. Make sure the instance was not created before or the option setup will have no effect.
  4. Finally, send your own log messages using RTI Distributed Logger API logging functions: RTI_DL_DistLogger_error, RTI_DL_DistLogger_fatal, ... Internal RTI Logger will be sent automatically once RTI Distributed Logger is created (no additional configuration required).

Function Documentation

◆ RTI_DL_DistLogger_getInstance()

RTI_DL_DistLogger * RTI_DL_DistLogger_getInstance ( void  )

Provides access to the RTI_DL_DistLogger singleton.

This method provides access to the singleton instance of RTI Distributed Logger, RTI_DL_DistLogger. If the instance does not exist, it will be created. To customize it, use the RTI Distributed Logger Options API API BEFORE creating the singleton the first time. Note that no change in options is allowed after the singleton is created.

Returns
The singleton instance of RTI_DL_DistLogger.
Note
This function is only thread-safe on Linux and Windows platforms.

◆ RTI_DL_DistLogger_setFilterLevel()

DDS_ReturnCode_t RTI_DL_DistLogger_setFilterLevel ( RTI_DL_DistLogger self,
DDS_Long  newLevel 
)

Sets the filter level for the singleton.

Filtering controls what type of log messages are sent. This enables filtering on the sending side (in the application using Distributed Logger). You can also enable filtering on the receiving side (such as in a tool that receives log messages, like RTI Admin Console or RTI Monitor).

Supported Filter Levels: See the table below. The default value is RTI_DL_INFO_LEVEL.

Or see the IDL file provided with Distributed Logger (file: <RTI Connext Installation Folder>/resource/idl/distlog.idl). In the IDL file, there are language-specific bindings. Prepend the appropriate binding to the filter level shown in the IDL. For example, one of the filter levels in the IDL is INFO_LEVEL. To refer to this filter level in C, use RTI_DL_INFO_LEVEL.

Log messages up to and including the specified filter level will pass through the filter and be sent on the network. For example, the WARNING level allows log messages up to and including the WARNING level (FATAL, SEVERE, ERROR, and WARNING) to be sent; any other log messages with numerically higher filter levels (INFO, DEBUG, and TRACE) will be filtered out and not sent.

Parameters
[in,out]selfPointer to the RTI_DL_DistLogger
[in]newLevelThe new log level.
Returns
Error code. DDS_RETCODE_OK if everything went as planned.

The following table shows how RTI Connext DDS log levels (RTI Logger) map to RTI Distributed Logger log filter levels.

Not all Distributed Logger levels appear in this table because there is not a one-to-one mapping between RTI Connext DDS and RTI Distributed Logger levels (there are more levels in RTI Distributed Logger). You can obtain the filter level using a constant defined in the Distributed Logger IDL file or a getter function in the Distributed Logger API.

Filter Levels
Connext DDS API constant Distributed Logger IDL constant Distributed Logger API getter
NDDS_CONFIG_LOG_FATAL_ERROR RTI_DL_FATAL_LEVEL RTI_DL_DistLogger_get_fatal_log_level
NDDS_CONFIG_LOG_LEVEL_ERROR RTI_DL_ERROR_LEVEL RTI_DL_DistLogger_get_error_log_level
NDDS_CONFIG_LOG_LEVEL_WARNING RTI_DL_WARNING_LEVEL RTI_DL_DistLogger_get_warning_log_level
NDDS_CONFIG_LOG_LEVEL_STATUS_LOCAL RTI_DL_NOTICE_LEVEL RTI_DL_DistLogger_get_notice_log_level
NDDS_CONFIG_LOG_LEVEL_STATUS_REMOTE RTI_DL_INFO_LEVEL RTI_DL_DistLogger_get_info_log_level
NDDS_CONFIG_LOG_LEVEL_DEBUG RTI_DL_DEBUG_LEVEL RTI_DL_DistLogger_get_debug_log_level

◆ RTI_DL_DistLogger_setOptions()

RTIBool RTI_DL_DistLogger_setOptions ( RTI_DL_Options options)

Assigns configurable options to RTI Distributed Logger before its creation.

Assigns the values in the RTI_DL_Options struct to the RTI_DL_DistLogger singleton before its creation. If the singleton was already created, this function has no effect.

Parameters
[in]optionsNew options to be assigned to the RTI_DL_DistLogger singleton.
Precondition
self must be NULL.
Returns
RTI_TRUE if everything went as planned. RTI_FALSE if RTI Distributed Logger already existed.

◆ RTI_DL_DistLogger_setRTILoggerPrintFormat()

RTIBool RTI_DL_DistLogger_setRTILoggerPrintFormat ( RTI_DL_DistLogger self,
NDDS_Config_LogPrintFormat  logPrintFormat 
)

Sets PrintFormat of RTI Logger to the provided value.

This method is mostly a pass-through to the appropriate call in the RTI Connext DDS library, but it also has the benefit of keeping the state of RTI Logger and RTI Distributed Logger in sync.

Parameters
[in,out]selfPointer to the RTI_DL_DistLogger
[in]logPrintFormatThe new PrintFormat.
Returns
RTI_TRUE if everything went as planned.

◆ RTI_DL_DistLogger_setRTILoggerVerbosityByCategory()

void RTI_DL_DistLogger_setRTILoggerVerbosityByCategory ( RTI_DL_DistLogger self,
NDDS_Config_LogCategory  category,
NDDS_Config_LogVerbosity  verbosity 
)

Updates the LogCategory and the LogVerbosity in RTI Logger to the provided value.

This method is mostly a pass-through to the appropriate call in the RTI Connext DDS library, but it also has the benefit of keeping the state of RTI Logger and RTI Distributed Logger in sync.

Parameters
[in,out]selfPointer to the RTI_DL_DistLogger
[in]categoryThe category for which to set the verbosity.
[in]verbosityThe new verbosity level for the category.

◆ RTI_DL_DistLogger_logMessageWithLevelCategory()

void RTI_DL_DistLogger_logMessageWithLevelCategory ( RTI_DL_DistLogger self,
int  logLevel,
const char *  message,
const char *  category 
)

Logs a message at the specified level and with the specified category.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]logLevelThe level of the log message.
[in]messageThe message to log.
[in]categoryThe category of the log message.

◆ RTI_DL_DistLogger_logMessageWithParams()

void RTI_DL_DistLogger_logMessageWithParams ( RTI_DL_DistLogger self,
const struct RTI_DL_DistLogger_MessageParams params 
)

Performs the same function as RTI_DL_DistLogger_logMessageWithLevelCategory except that it also allows specification of the message timestamp.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]paramsParameters.

◆ RTI_DL_DistLogger_fatal()

void RTI_DL_DistLogger_fatal ( RTI_DL_DistLogger self,
const char *  message 
)

Logs a fatal message.

The message received is logged using the default category and the RTI_DL_FATAL_LEVEL log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]messageThe message to log.

◆ RTI_DL_DistLogger_severe()

void RTI_DL_DistLogger_severe ( RTI_DL_DistLogger self,
const char *  message 
)

Logs a severe message.

The message received is logged using the default category and the RTI_DL_SEVERE_LEVEL log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]messageThe message to log.

◆ RTI_DL_DistLogger_error()

void RTI_DL_DistLogger_error ( RTI_DL_DistLogger self,
const char *  message 
)

Logs a error message.

The message received is logged using the default category and the RTI_DL_ERROR_LEVEL log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]messageThe message to log.

◆ RTI_DL_DistLogger_warning()

void RTI_DL_DistLogger_warning ( RTI_DL_DistLogger self,
const char *  message 
)

Logs a warning message.

The message received is logged using the default category and the RTI_DL_WARNING_LEVEL log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]messageThe message to log.

◆ RTI_DL_DistLogger_notice()

void RTI_DL_DistLogger_notice ( RTI_DL_DistLogger self,
const char *  message 
)

Logs a notice message.

The message received is logged using the default category and the RTI_DL_NOTICE_LEVEL log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]messageThe message to log.

◆ RTI_DL_DistLogger_info()

void RTI_DL_DistLogger_info ( RTI_DL_DistLogger self,
const char *  message 
)

Logs a info message.

The message received is logged using the default category and the RTI_DL_INFO_LEVEL log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]messageThe message to log.

◆ RTI_DL_DistLogger_debug()

void RTI_DL_DistLogger_debug ( RTI_DL_DistLogger self,
const char *  message 
)

Logs a debug message.

The message received is logged using the default category and the RTI_DL_DEBUG_LEVEL log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]messageThe message to log.

◆ RTI_DL_DistLogger_trace()

void RTI_DL_DistLogger_trace ( RTI_DL_DistLogger self,
const char *  message 
)

Logs a trace message.

The message received is logged using the default category and the RTI_DL_TRACE_LEVEL log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]messageThe message to log.

◆ RTI_DL_DistLogger_log()

void RTI_DL_DistLogger_log ( RTI_DL_DistLogger self,
int  logLevel,
const char *  message 
)

Logs a message.

The message received is logged using the default category and the given log level.

Parameters
[in]selfPointer to the RTI_DL_DistLogger
[in]logLevelThe level of the log message.
[in]messageThe message to log.

◆ RTI_DL_DistLogger_finalizeInstance()

DDS_ReturnCode_t RTI_DL_DistLogger_finalizeInstance ( void  )

Finalizes and deletes the RTI Distributed Logger singleton.

Unset the connections with DDS, free memory, and set the singleton to NULL

Returns
DDS_RETCODE_OK if everything went as planned. Otherwise, an error code is returned.

◆ RTI_DL_DistLogger_get_fatal_log_level()

DDS_Long RTI_DL_DistLogger_get_fatal_log_level ( void  )

Return Fatal log level.

Returns
Fatal log level.

◆ RTI_DL_DistLogger_get_error_log_level()

DDS_Long RTI_DL_DistLogger_get_error_log_level ( void  )

Return Error log level.

Returns
Error log level.

◆ RTI_DL_DistLogger_get_warning_log_level()

DDS_Long RTI_DL_DistLogger_get_warning_log_level ( void  )

Return Warning log level.

Returns
Warning log level.

◆ RTI_DL_DistLogger_get_notice_log_level()

DDS_Long RTI_DL_DistLogger_get_notice_log_level ( void  )

Return Notice log level.

Returns
Notice log level.

◆ RTI_DL_DistLogger_get_info_log_level()

DDS_Long RTI_DL_DistLogger_get_info_log_level ( void  )

Return Info log level.

Returns
Info log level.

◆ RTI_DL_DistLogger_get_debug_log_level()

DDS_Long RTI_DL_DistLogger_get_debug_log_level ( void  )

Return Debug log level.

Returns
Debug log level.