RTI Connext DDS Micro C API  Version 3.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
LoggingModule

Modules

 REDA
 Real-time Efficient Data Structures and Algorithms. ModuleID = 1.
 OSAPI
 OS API. ModuleID = 0.
 DB
 Database. ModuleID = 2.
 CDR
 CDR. ModuleID = 5.
 RT
 RT. ModuleID = 3.
 NETIO
 Network I/O. ModuleID = 4.
 RTPS
 Real-Time Publish-Subscribe. ModuleID = 6.
 DDS_C
 DDS C. ModuleID = 7.
 RH
 Reader History. ModuleID = 8.
 WH
 Writer History. ModuleID = 9.
 DPSE
 DPSE. ModuleID = 10.
 DPDE
 DPDE. ModuleID = 11.
 APPGEN
 APPGEN. ModuleID = 13.

Detailed Description

RTI Connext DDS Micro Secure maintains a log of events occuring in an RTI Connext DDS Micro Secure 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.

Configuring Logging

By default RTI Connext DDS Micro Secure sets log verbosity to Error. It can be changed at any time by calling OSAPI_Log_set_verbosity() using the desired verbosity as parameter.

Note that when compiling with RTI_CERT defined, logging is completely removed.

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

The default buffer size is different for Debug and Release libraries, with Debug libraries configured to use a much larger buffer than the Release ones. A custom buffer size can be configured using the OSAPI_Log_set_property() function, e.g. to set a buffer size of 128 bytes:

  struct OSAPI_LogProperty prop = OSAPI_LogProperty_INIITALIZER;

  OSAPI_Log_get_property(&prop);
  prop.max_buffer_size = 128;
  OSAPI_Log_set_property(&prop);

Note that if the buffer size is too small, log entries will be truncated in order to fit in the available buffer.

The function used to write the logs can be set during compilation by defining macro OSAPI_LOG_WRITE_BUFFER. This macro shall have the same parameters as function prototype OSAPI_Log_write_buffer_T.

It is also possible to set this function during runtime by using function OSAPI_Log_set_property():

  struct OSAPI_LogProperty prop = OSAPI_LogProperty_INIITALIZER;

  OSAPI_Log_get_property(&prop);
  prop.write_buffer = <pointer to user defined write function>;
  OSAPI_Log_set_property(&prop);

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).

The log handler is called for every new log entry, even when the log buffer is full. An expected use case is redirecting log entries to another logger, such as one native to a particular platform.

Log Message Kinds

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

By the default the log verbosity is set to Error, so only error logs will be visible. To change the log verbosity simply call function OSAPI_Log_set_verbosity() with the desired verbosity level.

Interpreting Log Messages and Error Codes

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

Each entry contains a header with the following information:

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

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

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

  [943921909.645099999]ERROR: ModuleID=7 Errcode=200 X=1 E=0 T=1
  dds_c/DomainFactory.c:163/DDS_DomainParticipantFactory_get_instance: kind=19  

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

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


RTI Connext DDS Micro C API Version 3.0.0 Copyright © Fri Mar 22 2019 Real-Time Innovations, Inc