DOCA Log

The DOCA logging infrastructure provides a mechanism for printing error messages, debug logs, and application-specific messages within the DOCA SDK.

To use DOCA logging, applications must include the doca_log.h header file in their source code.

DOCA logging supports multiple verbosity levels, allowing applications to filter logs based on severity:

            

            
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 */
};
        

Refer to doca_log.h for more information.

A logging backend is the destination where log messages are directed. DOCA supports multiple backend types:

• FILE* – Any open file, including stdout or stderr

• File descriptor – Any valid file descriptor (e.g., raw files, sockets, pipes)

• Buffer (buf) – A memory buffer that holds log messages and triggers a callback per message

• Syslog – System-standard logging mechanism

Each logging backend is initialized with the following default verbosity levels:

• Lower level – DOCA_LOG_LEVEL_INFO

• Upper level – DOCA_LOG_LEVEL_CRIT

DOCA SDK logs and application logs have different configurations and can be controlled independently via the DOCA logging API.

DOCA SDK libraries automatically print debug and error messages to configured logging backends.

The maximum number of logging backends can be queried using the doca_log_get_max_num_backends_sdk() function.

To create a logging backend for SDK logs, use:

            

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

The following functions control SDK logging levels:

• doca_log_level_set_global_sdk_limit() sets global verbosity level

  Info

  This function applies to all SDK backends.

  Info

  A newly created SDK backend verbosity level is set to the SDK global verbosity level value by default.

• doca_log_backend_set_sdk_level() sets verbosity level for a specific SDK backend

• doca_log_level_get_global_sdk_limit() gets the global SDK verbosity level

Applications that use DOCA SDK can utilize DOCA logging for structured logging.

The maximum number of logging backends can be queried using the doca_log_get_max_num_backends() function.

The total number of application logging backends that can be created is queried using the following function:

            

            
doca_log_get_max_num_backends()
        

To create an application logging backend, use:

            

            
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 following functions configure logging limits:

• doca_log_backend_set_level_{lower|upper}_limit() sets lower and/or upper verbosity levels for a backend

  Info

  The lower and upper levels of a newly created backend are set to the default values.

• doca_log_backend_create_standard() creates a standard, non-configurable logging setup. This creates two backends:

  • stdout – Logs messages up to DOCA_LOG_LEVEL_INFO

  • stderr – Logs messages from DOCA_LOG_LEVEL_WARNING to DOCA_LOG_LEVEL_CRIT

• doca_log_backend_set_level_{lower|upper}_limit_strict() sets strict limits for a backend (prevent future changes)

• doca_log_level_set_global_{lower|upper}_limit() sets global logging limits (affects all non-strict backends)

To enable DOCA logging in an application, use the DOCA log registration macro at the beginning of each source file:

            

            
DOCA_LOG_REGISTER(source);
        

This registers and manages teardown for logging in that file.

Log messages are printed using the following macros (similar to printf() syntax):

            

            
DOCA_LOG_CRIT(format, ...);   // Critical error messages
DOCA_LOG_ERR(format, ...);    // Standard error messages
DOCA_LOG_WARN(format, ...);   // Warnings
DOCA_LOG_INFO(format, ...);   // Informational messages
DOCA_LOG_DBG(format, ...);    // Debug messages
DOCA_LOG_TRC(format, ...);    // Trace-level messages