Modules
	DDS_C
	DDS C. ModuleID = 7.

	REDA
	Real-time Efficient Data Structures and Algorithms. ModuleID = 1.

	OSAPI
	OS API. ModuleID = 0.

	DB
	Database. ModuleID = 2.

	RT
	RT. ModuleID = 3.

	NETIO
	Network I/O. ModuleID = 4.

	RTPS
	Real-Time Publish-Subscribe. ModuleID = 6.

	RH
	Reader History. ModuleID = 8.

	WH
	Writer History. ModuleID = 9.

	DPSE
	DPSE. ModuleID = 10.

	DPDE
	DPDE. ModuleID = 11.

Detailed Description

Objectives of this user guide:

Configuring the log buffer and logging verbosity
Interpreting log messages and error codes
Configuring the user log handler function

RTI Connext DDS Micro maintains a log of events occuring in an RTI Connext DDS Micro application. Information of each event is formatted into a log entry, and each entry can be stored in a buffer, stringified into a displayable log message, and/or redirected to a user-defined log handler.

Initializing Logging

To enable RTI Connext DDS Micro log functionality, initialize it (OSAPI_Log_initialize) with an input property that configures the following:

max_buffer_size. The maximum number of bytes of the log buffer.
log_detail. A bitmap controlling the fidelity of information stored per log message.

Managing the Log Buffer

The RTI Connext DDS Micro log stores new log entries in a log buffer.

Once the buffer is full, it will not store new entries but will still display and redirect them to the user-defined log handler.

The log buffer can be cleared at anytime with a call to OSAPI_Log_clear.

Log Message Kinds

Each log entry is classified as one of the following kinds:

Error. An unexpected event with negative functional impact.

Warning. An event that may not have negative fuctional impact but could indicate an unexpected situation.

Information. An event logged for informative purposes.

Interpreting Log Messages and Error Codes

A log entry in RTI Connext DDS Micro has a defined format.

Each entry contains a header with the following information:

Length. The length of the log message, in bytes.
Module ID. A numerical ID of the module from which the message was logged.
Error Code. A numerical ID for the log message. It is unique within a module. Though referred to as an "error" code, it exists for all log kinds (error, warning, info).

The module ID and error code together uniquely identify a log message within RTI Connext DDS Micro.

RTI Connext DDS Micro can be configured to provide additional details per log message:

Line Number. The line number of the source file from which the message is logged.
Module Name. The name of the module from which the message is logged.
Function Name. The name of the function from which the message is logged.

When an event is logged, by default it is printed as a message to standard output. An example informative entry looks like this:

[1379134571.591696998] INFO:ModuleID=6,Errcode=44,X=1,E=0,STATUS=f0000000
rtps/RTPSInterface.c/2137/RTPSReceiver_process_acknack:

A log message will need to be interpreted by the user when:

an error or warning has occurred and its cause needs to be determined, or
the user has set a log handler and is processing each log message based on its contents.

A description of an error code printed in a log message can be determined by following these steps:

Navigate to the module that corresponds to the Module ID, or the printed module name in the second line. In the above example, "ModuleID=6" corresponds to RTPS.

Search for the error code to find it in the list of the module's error codes. In the example above, with "Errcode=44," search for "44" to find the log message that has the value "(RTPS_LOG_BASE + 44)."

Setting the User Log Handler

A user can install a log handler function to process each new log entry. The handler must conform to the definition OSAPI_LogHandler_T, and it is set by OSAPI_Log_set_log_handler().

When called, the handler has parameters containing the raw log entry and detailed log information (e.g. error code, module, file and function names, line number).