Table of Contents
OpenThread offers several configuration options for printing logs that can be used for providing logging capability to your application, useful for debugging or measurements.
For detailed information about the available API, see Logging.
The logging feature can be used to introduce additional overhead to the communication medium and measure how much the original performance is degradated. For an example using Border Router, see Performance measurement test results (NCP).
OpenThread logging configuration
OpenThread prints logs by calling the otPlatLog function.
The default log output option is OPENTHREAD_CONFIG_LOG_OUTPUT_PLATFORM_DEFINED, defined in the src/core/config/logging.h file. For Nordic platforms, this means using RTT logging.
When configuring logging, you have to change the configuration file and choose the desired Log levels and Log regions.
Output options
The otPlatLog function output depends on the configuration of the default src/core/config/logging.h file or the configuration file of your application. The configuration file defines the output options listed in the following table.
| Output option | Define | Description |
|---|---|---|
| NONE | OPENTHREAD_CONFIG_LOG_OUTPUT_NONE | Logging is disabled. |
| APP | OPENTHREAD_CONFIG_LOG_OUTPUT_APP | The application must provide the otPlatLog function. You can use this option for example for printing the logs on the CLI console in a CLI example. They can be read by PuTTY, minicom etc. |
| PLATFORM_DEFINED | OPENTHREAD_CONFIG_LOG_OUTPUT_PLATFORM_DEFINED | This option is enabled by default. The platform, for example the nRF52840 port, must provide the otPlatLog function. You can use this option for example when you have implemented the SEGGER RTT logging for nRF52840. |
| NCP_SPINEL | OPENTHREAD_CONFIG_LOG_OUTPUT_NCP_SPINEL | With this option, logs are sent over the Spinel property SPINEL_PROP_STREAM_LOG, which provides streaming of formatted log string from NCP along with an optional metadata. |
| DEBUG_UART | OPENTHREAD_CONFIG_LOG_OUTPUT_DEBUG_UART | With this option, you can use logs for debugging purposes when using UART. |
Changing output options
To change the default logging output configuration:
- Open the
.h configuration file whose name corresponds to the name of theopenthread-core-default-config.hfile, for exampleopenthread-core-posix-config.h. - In this file, define the desired log output configuration.
Log levels
The log level is determined at compile time and is enabled in the configuration file with the OPENTHREAD_CONFIG_LOG_LEVEL define.
There are several log levels. This allows you to decide how much output you want to see printed. The following is the default setting, in which the output contains only the critical logs:
#define OPENTHREAD_CONFIG_LOG_LEVEL OT_LOG_LEVEL_CRITSee the following table for an overview of the available log levels.
| Define | Description |
|---|---|
| OT_LOG_LEVEL_NONE | No logs are printed. |
| OT_LOG_LEVEL_CRIT | This is the default log level. Only the logs of critical importance are printed. |
| OT_LOG_LEVEL_WARN | Only warning logs, and the OT_LOG_LEVEL_CRIT critical logs are printed. |
| OT_LOG_LEVEL_NOTE | Only notes, the OT_LOG_LEVEL_WARN warning logs, and the OT_LOG_LEVEL_CRIT critical logs are printed. |
| OT_LOG_LEVEL_INFO | Only the OT_LOG_LEVEL_NOTE notes, the OT_LOG_LEVEL_WARN warning logs, and the OT_LOG_LEVEL_CRIT critical logs are printed. |
| OT_LOG_LEVEL_DEBG | This is the most verbose log level. Only debug logs, the OT_LOG_LEVEL_NOTE notes, the OT_LOG_LEVEL_WARN warning logs, and the OT_LOG_LEVEL_CRIT critical logs are printed. |
Dynamic log level
The dynamic logging allows you to change the log level at runtime.
The dynamic logging is disabled by default. To enable the dynamic log level, edit the configuration file and change the OPENTHREAD_CONFIG_ENABLE_DYNAMIC_LOG_LEVEL define value to 1.
After enabling the dynamic log level, the logging will start at the log level value specified in the OPENTHREAD_CONFIG_INITIAL_LOG_LEVEL define, which is also used in the compile-time configuration.
- Note
- When enabled, the dynamic log level control only allows decreasing the log level from the compile time value.
Changing log levels
To change the log level:
- At compile time: edit the
OPENTHREAD_CONFIG_LOG_LEVELdefine in the configuration file. - At runtime, when using Dynamic log level : use the otLoggingSetLevel() function.
To enable the highest verbosity level, append FULL_LOGS flag to the make command, for example:
$ make -f examples/Makefile-nrf52840 FULL_LOGS=1Log regions
You can narrow the area for which the logging output is produced by selecting modules for which you want to see the logging output.
The otLogRegion enumeration contains the complete list of modules that are available for logging.
By default, logging for all modules is enabled, with the exception of the Platform module (OT_LOG_REGION_PLATFORM).
Changing log regions
You can pass a log region as a parameter to the log function to narrow the log output.
RTT logging
SEGGER RTT logging is Nordic's default configuration for log output. It is available as part of RTT Viewer and is enabled with the default OPENTHREAD_CONFIG_LOG_OUTPUT_PLATFORM_DEFINED output option.
RTT Viewer can be used either as a standalone tool by opening its own connection to J-Link and target or in parallel to a running debug session by attaching to it and using the existing J-Link connection.
The RTT logging supports all major features of RTT:
- Terminal output on Channel 0
- Sending text input on Channel 0
- Up to 16 virtual terminal with only one target channel
- Controlling text output: colored text, erasing the console
- Logging data on Channel 1
Enabling RTT logging on Windows
To enable logging on Windows:
- Connect the DK to your machine with a USB cable.
- Run J-Link RTT Viewer. The configuration window appears.
- From the Specify Target Device dropdown menu, select
NRF52840_XXAA. - From the Target Interface & Speed dropdown menu, select
SWD.
The logs will be printed in the RTT viewer's window.
Enabling RTT logging on Linux
To enable logging on Linux:
- Connect the DK to your machine with a USB cable.
- Run
JLinkExeto connect to the target. For example:JLinkExe -device NRF52840_XXAA -if SWD -speed 4000 -autoconnect 1 -SelectEmuBySN <SEGGER_ID> -RTTTelnetPort 19021 - Run
JLinkRTTTelnetto obtain the RTT logs from the connected device in a separate console. For example:JLinkRTTClient -RTTTelnetPort 19021
The logs will be printed in the RTT viewer's window.
Portions of this page are reproduced from work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License.