5. Log Library

The DPDK Log library provides the logging functionality for other DPDK libraries and drivers. By default, in a Linux application, logs are sent to syslog and also to the console. On FreeBSD and Windows applications, logs are sent only to the console. However, the log function can be overridden by the user to use a different logging mechanism.

5.1. Log Levels

Log messages from apps and libraries are reported with a given level of severity. These levels, specified in rte_log.h are (from most to least important):

  1. Emergency
  2. Alert
  3. Critical
  4. Error
  5. Warning
  6. Notice
  7. Information
  8. Debug

At runtime, only messages of a configured level or above (i.e. of higher importance) will be emitted by the application to the log output. That level can be configured either by the application calling the relevant APIs from the logging library, or by the user passing the --log-level parameter to the EAL via the application.

5.1.1. Setting Global Log Level

To adjust the global log level for an application, just pass a numeric level or a level name to the --log-level EAL parameter. For example:

/path/to/app --log-level=error

/path/to/app --log-level=debug

/path/to/app --log-level=5   # warning

Within an application, the log level can be similarly set using the rte_log_set_global_level API.

5.1.2. Setting Log Level for a Component

In some cases, for example, for debugging purposes, it may be desirable to increase or decrease the log level for only a specific component, or set of components. To facilitate this, the --log-level argument also accepts an, optionally wildcarded, component name, along with the desired level for that component. For example:

/path/to/app --log-level=lib.eal:crit

/path/to/app --log-level=lib.*:warning

Within an application, the same result can be got using the rte_log_set_level_pattern() or rte_log_set_level_regex() APIs.

5.2. Using Logging APIs to Generate Log Messages

To output log messages, rte_log() API function should be used. As well as the log message, rte_log() takes two additional parameters:

  • The log level
  • The log component type

The log level is a numeric value as discussed above. The component type is a unique id that identifies the particular DPDK component to the logging system. To get this id, each component needs to register itself at startup, using the macro RTE_LOG_REGISTER_DEFAULT. This macro takes two parameters, with the second being the default log level for the component. The first parameter, called “type”, the name of the “logtype”, or “component type” variable used in the component. This variable will be defined by the macro, and should be passed as the second parameter in calls to rte_log(). In general, most DPDK components define their own logging macros to simplify the calls to the log APIs. They do this by:

  • Hiding the component type parameter inside the macro so it never needs to be passed explicitly.
  • Using the log-level definitions given in rte_log.h to allow short textual names to be used in place of the numeric log levels.

The following code is taken from rte_cfgfile.c and shows the log registration, and subsequent definition of a shortcut logging macro. It can be used as a template for any new components using DPDK logging.

RTE_LOG_REGISTER_DEFAULT(cfgfile_logtype, INFO);
#define RTE_LOGTYPE_CFGFILE cfgfile_logtype

#define CFG_LOG(level, ...) \
	RTE_LOG_LINE_PREFIX(level, CFGFILE, "%s(): ", __func__, __VA_ARGS__)

Note

Because the log registration macro provides the logtype variable definition, it should be placed near the top of the C file using it. If not, the logtype variable should be defined as an “extern int” near the top of the file.

Similarly, if logging is to be done by multiple files in a component, only one file should register the logtype via the macro, and the logtype should be defined as an “extern int” in a common header file. Any component-specific logging macro should similarly be defined in that header.

Throughout the cfgfile library, all logging calls are therefore of the form:

CFG_LOG(ERR, "missing cfgfile parameters");

CFG_LOG(ERR, "invalid comment characters %c",
       params->comment_character);