Debuggability

DOCA logging infrastructure allows enabling printing DOCA SDK library error messages, and printing debug and error messages from applications.

To work with the DOCA logging mechanism, the header doca_log.h must be included in every source code using it.

The following verbosity levels are supported by the DOCA logging:

            

            
enum doca_log_level {
	DOCA_LOG_LEVEL_DISABLE = 10,	/**< Disable log messages */
	DOCA_LOG_LEVEL_CRIT = 20,		/**< Critical log level */
	DOCA_LOG_LEVEL_ERROR = 30,		/**< Error log level */
	DOCA_LOG_LEVEL_WARNING = 40,	/**< Warning log level */
	DOCA_LOG_LEVEL_INFO = 50,		/**< Info log level */
	DOCA_LOG_LEVEL_DEBUG = 60,		/**< Debug log level */
	DOCA_LOG_LEVEL_TRACE = 70,		/**< Trace log level */
};
        

See doca_log.h for more information.

DOCA logging backend is the target to which log messages are directed.

The following backend types are supported:

• FILE * – file stream which can be any open file or stdout/stderr

• file descriptor – any file descriptor that the system supports, including (but not limited to) raw files, sockets, and pipes

• buf – memory buffer (address and size) that can hold a single message and a callback to be called for every logged message

• syslog – system standard logging

Every logger is created with the following default lower and upper verbosity levels:

• Lower level – DOCA_LOG_LEVEL_INFO

• Upper level – DOCA_LOG_LEVEL_CRIT

SDK and application logging have different default configuration values and can be controlled separately using the appropriate API.

Every message is printed to every created backend if its verbosity level allows it.

The DOCA SDK libraries print debug and error messages to all the backends created using the following functions:

• doca_log_backend_create_with_file_sdk()

• doca_log_backend_create_with_fd_sdk()

• doca_log_backend_create_with_buf_sdk()

• doca_log_backend_create_with_syslog_sdk()

A newly created SDK backend verbosity level is set to the SDK global verbosity level value. This value can be changed using doca_log_level_set_global_sdk_limit().

doca_log_level_set_global_sdk_limit() sets the verbosity level for all existing SDK backends and sets the SDK global verbosity level.

doca_log_backend_set_sdk_level() sets the verbosity level of a specific SDK backend.

doca_log_level_get_global_sdk_limit() gets the SDK global verbosity level.

Any source code that uses DOCA can use DOCA logging infrastructure.

Every debug and error messages is printed to all backends created using the following functions:

• doca_log_backend_create_with_file()

• doca_log_backend_create_with_fd()

• doca_log_backend_create_with_buf()

• doca_log_backend_create_with_syslog()

The lower and upper levels of a newly created backend are set to the default values. Those values can be changed using doca_log_backend_set_level_lower_limit() and doca_log_backend_set_level_upper_limit().

doca_log_backend_create_standard() creates a default non-configurable set of two backends:

• stdout prints the range from global minimum level up to DOCA_LOG_LEVEL_INFO

• stderr prints the range from DOCA_LOG_LEVEL_WARNING level up to DOCA_LOG_LEVEL_CRIT

doca_log_backend_set_level_lower_limit_strict() marks the lower log level limit of a backend as strict, preventing it from being lowered by any future log level changes. It is both global and direct.

doca_log_backend_set_level_upper_limit_strict() marks the upper log level limit of a backend as strict, preventing it from being raised by any future log level changes. It is both global and direct.

doca_log_level_set_global_lower_limit() sets the lower limit for all existing backends not marked as strict and sets the global application lower limit.

doca_log_level_set_global_upper_limit() sets the upper limit for all existing backends not marked as strict and sets the global application upper limit.

To use the DOCA logging infrastructure with your source code to log its messages, users must call at the beginning of the file the macro DOCA_LOG_REGISTER(source) just before using the DOCA logging functionality. This macro handles the registration and the teardown from the DOCA logging.

Printing a message can be done by calling one of the following macros (with the same usage as printf()):

• DOCA_LOG_CRIT(format, ...)

• DOCA_LOG_ERR(format, ...)

• DOCA_LOG_WARN(format, ...)

• DOCA_LOG_INFO(format, ...)

• DOCA_LOG_DBG(format, ...)

• DOCA_LOG_TRC(format, ...)

The message is printed to all the application's backends with configured lower and upper logging limits.