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.

Log Verbosity Level Enumerations

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.

Logging Backends

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.

Enabling DOCA SDK Libraries Logging

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

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 

  This function applies to all SDK backends.

  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

Enabling DOCA Application Logging

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

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 

  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)

Logging DOCA Application Messages

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

Last updated: March 20, 2025