8. Log Library

The DPDK Log library provides the logging functionality for other DPDK libraries and drivers. By default, logs are sent only to standard error output of the process. The syslog EAL option can be used to redirect to the stystem logger on Linux and FreeBSD. In addition, the log can be redirected to a different stdio file stream.

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

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

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

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

8.2.1. Log timestamp

An optional timestamp can be added before each message by adding the --log-timestamp option. For example:

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

Multiple alternative timestamp formats are available:

Table 8.4 Log time stamp format

Format

Description

Example

ctime

Unix ctime

[Wed Mar 20 07:26:12 2024]

delta

Offset since last

[<    3.162373>]

reltime

Seconds since last or time if minute changed

[  +3.001791] or [Mar20 07:26:12]

iso

ISO-8601

[2024-03-20T07:26:12−07:00]

To prefix all console messages with ISO format time the syntax is:

/path/to/app --log-timestamp=iso

Note

Timestamp option has no effect if using syslog because the syslog() service already does timestamping internally.

8.2.2. Color output

The log library will highlight important messages. This is controlled by the --log-color option. The optional argument describes when color is enabled:

never:

Do not enable color. This is the default behavior.

auto:

Enable color only when printing to a terminal. This is the same as --log-color with no argument.

always:

Always print color.

For example to enable color in logs if using terminal:

/path/to/app --log-color

Note

Color output is never used for syslog or systemd journal logging.