System Logging

The system log API provides a common interface to process messages issued by developers. These messages are currently printed on the terminal but the API is defined in a generic way.

This API can be deactivated through the Kconfig options, see Global Kconfig Options. This approach prevents impacting image size and execution time when the system log is not needed.

Each of the four SYS_LOG_X macros correspond to a different logging level, The logging macros activate when their logging level or higher is set.

There are two configuration categories: configurations per module and global configurations. When logging is enabled globally, it works for modules. However, modules can disable logging locally. Every module can specify its own logging level. The module must define the SYS_LOG_LEVEL macro before including the include/logging/sys_log.h header file to do so. Unless a global override is set, the module logging level will be honored. The global override can only increase the logging level. It cannot be used to lower module logging levels that were previously set higher.

You can set a local domain to differentiate messages. When no domain is set, then the [general] domain appears before the message. Define the SYS_LOG_DOMAIN macro before including the include/logging/sys_log.h header file to set the domain.

When several macros are active, the printed messages can be differentiated in two ways: by a tag printed before the message or by ANSI colors. See the CONFIG_SYS_LOG_SHOW_TAGS and CONFIG_SYS_LOG_SHOW_COLOR Kconfig options for more information.

Define the SYS_LOG_NO_NEWLINE macro before including the include/logging/sys_log.h header file to prevent macros appending a new line at the end of the logging message.

Global Kconfig Options

These options can be found in the following path subsys/logging/Kconfig.

CONFIG_SYS_LOG: Global switch, turns on/off all system logging.

CONFIG_SYS_LOG_DEFAULT_LEVEL: Default level, sets the logging level used by modules that are not setting their own logging level.

CONFIG_SYS_LOG_SHOW_TAGS: Globally sets whether level tags will be shown on log or not.

CONFIG_SYS_LOG_SHOW_COLOR: Globally sets whether ANSI colors will be used by the system log.

CONFIG_SYS_LOG_OVERRIDE_LEVEL: It overrides module logging level when it is not set or set lower than the override value.

Example

The following macro:

SYS_LOG_WRN("hi!");

Will produce:

[general] [WRN] main: Hi!

For the above example to work at least one of the following settings must be true:

APIs

group system_log

System Log.

Defines

IS_SYS_LOG_ACTIVE

Specifies whether SYS_LOG is in use or not.

This macro expands to 1 if SYS_LOG was activated for current .c file, 0 otherwise.

SYS_LOG_ERR(...)

Writes an ERROR level message to the log.

Lowest logging level, these messages are logged whenever sys log is active. it’s meant to report severe errors, such as those from which it’s not possible to recover.

Parameters
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

SYS_LOG_WRN(...)

Writes a WARNING level message to the log.

available if SYS_LOG_LEVEL is SYS_LOG_LEVEL_WARNING or higher. It’s meant to register messages related to unusual situations that are not necessarily errors.

Parameters
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

SYS_LOG_INF(...)

Writes an INFO level message to the log.

available if SYS_LOG_LEVEL is SYS_LOG_LEVEL_INFO or higher. It’s meant to write generic user oriented messages.

Parameters
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

SYS_LOG_DBG(...)

Writes a DEBUG level message to the log.

highest logging level, available if SYS_LOG_LEVEL is SYS_LOG_LEVEL_DEBUG. It’s meant to write developer oriented information.

Parameters
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.