OpenThread Logs

OpenThread logs are controlled by numerous compile-time configuration constants. Unless otherwise noted, these constants are defined in the following file:

/src/core/openthread-core-default-config.h

Output methods

OpenThread supports different output logging methods, defined as the compile-time configuration constant of OPENTHREAD_CONFIG_LOG_OUTPUT. The logging method options are listed in the following file:

/src/core/openthread-core-default-config.h

The default log output configuration is OPENTHREAD_CONFIG_LOG_OUTPUT_PLATFORM_DEFINED.

The output method is an example of where you may need to update the platform-level configuration constant instead of the core one. For example, to change the output method in the POSIX example app, edit /examples/platforms/posix/openthread-core-posix-config.h instead of /src/core/openthread-core-default-config.h.

Log levels

Logs may output varying levels of information, defined as the compile-time configuration constant of OPENTHREAD_CONFIG_LOG_LEVEL. The level options are listed in the following file:

/include/openthread/platform/logging.h

The list of log levels are also available in the Platform Logging Macros API reference.

The default log level is OT_LOG_LEVEL_CRIT which only outputs the most critical logs. Change the level to see more logs as desired. To see all OpenThread logs, use OT_LOG_LEVEL_DEBG.

Log regions

The log regions determine what areas of the OpenThread code are enabled for logging. The region enumeration is defined in the following file:

/include/openthread/platform/logging.h

The list of log regions are also available in the Platform Logging Enumerations API reference.

Log regions are commonly used as parameters in log functions. All regions are enabled by default.

Default logging function

The default function for logging within OpenThread is otPlatLog, defined as the compile-time configuration constant of OPENTHREAD_CONFIG_PLAT_LOG_FUNCTION.

See the Platform Logging API reference for more information on this function.

To use this function directly in the OpenThread example apps, use the CERT_LOG build switch. For example, to use it within the CLI app (examples/apps/cli/main.c) for the nRF52840 example:

make -f examples/Makefile-nrf52840 CERT_LOG=1

Alternatively, modify the COMMONCFLAGS variable in an example Makefile to enable it by default when building.

How to enable logs

Before enabling logs, make sure your environment is configured for building OpenThread. See Build OpenThread for more information.

Enable all logs

To quickly enable all log levels and regions, use the FULL_LOGS build switch:

make -f examples/Makefile-posix FULL_LOGS=1

This switch sets the log level to OT_LOG_LEVEL_DEBG and turns on all region flags.

Enable a specific level of logs

To enable a specific level of logs, edit /src/core/openthread-core-default-config.h and update OPENTHREAD_CONFIG_LOG_LEVEL to the desired level, then build OpenThread. For example, to enable logs up to OT_LOG_LEVEL_INFO:

#define OPENTHREAD_CONFIG_LOG_LEVEL OT_LOG_LEVEL_INFO
make -f examples/Makefile-posix

View logs in syslog

Logs are sent to the syslog by default. On Linux, this is /var/log/syslog.

  1. Build the POSIX example with all logs enabled:
    make -f examples/Makefile-posix FULL_LOGS=1
    
  2. Start a POSIX node:
    ./output/x86_64-unknown-linux-gnu/bin/ot-cli-ftd 1
    
  3. In a new terminal window, set up a real-time output of the OT logs:
    tail -F /var/log/syslog | grep "ot-cli-ftd"
    
  4. On the POSIX node, bring up Thread:
    panid 0x1234
    Done
    ifconfig up
    Done
    thread start
    Done
    
  5. Switch back to the terminal window running the tail command. Logs should display in real time for the POSIX node:
    ot-cli-ftd[30055]: [1] [DEBG]-MAC-----: SrcAddrMatch - Cleared all entries
    ot-cli-ftd[30055]: [1] [INFO]-CORE----: Non-volatile: Read NetworkInfo {rloc:0x9c00, extaddr:1a4aaf5e97c852de, role:Leader, mode:0x0f, keyseq:0x0, ...
    ot-cli-ftd[30055]: [1] [INFO]-CORE----: Non-volatile: ... pid:0x8581bc9, mlecntr:0x3eb, maccntr:0x3e8, mliid:05e4b515e33746c8}
    ot-cli-ftd[30055]: [1] [INFO]-CORE----: Notifier: StateChanged (0x7f133b) [Ip6+ Ip6- LLAddr MLAddr Rloc+ KeySeqCntr NetData Ip6Mult+ Channel PanId NetName ExtPanId MstrKey PSKc SecPolicy]
    ot-cli-ftd[30055]: [1] [INFO]-CLI-----: execute command: panid 0x1234
    ot-cli-ftd[30055]: [1] [INFO]-CLI-----: execute command: ifconfig up
    ot-cli-ftd[30055]: [1] [DEBG]-MAC-----: Idle mode: Radio receiving on channel 11
    ot-cli-ftd[30055]: [1] [INFO]-CLI-----: execute command: thread start
    ot-cli-ftd[30055]: [1] [NOTE]-MLE-----: Role Disabled -> Detached
    ot-cli-ftd[30055]: [1] [INFO]-MLE-----: Attempt to become router
    ot-cli-ftd[30055]: [1] [INFO]-CORE----: Non-volatile: Read NetworkInfo {rloc:0x9c00, extaddr:1a4aaf5e97c852de, role:Leader, mode:0x0f, keyseq:0x0, ...
    ot-cli-ftd[30055]: [1] [INFO]-CORE----: Non-volatile: ... pid:0x8581bc9, mlecntr:0x3eb, maccntr:0x3e8, mliid:05e4b515e33746c8}
    ot-cli-ftd[30055]: [1] [INFO]-CORE----: Non-volatile: Saved NetworkInfo {rloc:0x9c00, extaddr:1a4aaf5e97c852de, role:Leader, mode:0x0f, keyseq:0x0, ...
    ot-cli-ftd[30055]: [1] [INFO]-CORE----: Non-volatile: ... pid:0x8581bc9, mlecntr:0x7d4, maccntr:0x7d0, mliid:05e4b515e33746c8}
    ot-cli-ftd[30055]: [1] [DEBG]-MLE-----: Store Network Information
    ot-cli-ftd[30055]: [1] [INFO]-MLE-----: Send Link Request (ff02:0:0:0:0:0:0:2)
    

Note the log tags in the output: [INFO], [DEBG], [NOTE]. These all correspond to the log levels. For example, if you change the log level to OT_LOG_LEVEL_INFO, the DEBG logs disappear from the output.

View logs in the CLI app

Logs may be viewed directly in the OpenThread CLI example app.

  1. Edit the configuration file for the example platform and change the log output to the app. For POSIX, this is /examples/platforms/posix/openthread-core-posix-config.h:
    #define OPENTHREAD_CONFIG_LOG_OUTPUT OPENTHREAD_CONFIG_LOG_OUTPUT_APP
    
  2. Build the POSIX example with the desired level of logs. To enable all logs:
    make -f examples/Makefile-posix FULL_LOGS=1
    
  3. Start a POSIX node:
    ./output/x86_64-apple-darwin/bin/ot-cli-ftd 1
    
  4. You should see log output in the same window as the OpenThread CLI as commands are processed.

If you have added custom logging and enabled all logs, the UART transmit buffer may not be large enough to handle the additional custom logs. If some logs are not appearing when they should, try increasing the size of the UART transmit buffer, defined as OPENTHREAD_CONFIG_CLI_UART_TX_BUFFER_SIZE in /src/core/openthread-core-default-config.h

View logs for an NCP

Logs for an NCP may be sent through wpantund to the syslog of a host. For a Linux host, this is /var/log/syslog.

Use an OPENTHREAD_CONFIG_LOG_OUTPUT value of OPENTHREAD_CONFIG_LOG_OUTPUT_NCP_SPINEL to enable NCP logging. Change this in the platform's configuration file.

For example, to enable this for an nrf52840 connected to a Linux host:

  1. Edit the configuration file for the platform and change the log output to NCP Spinel. For nrf52840, this is /examples/platforms/nrf52840/openthread-core-nrf52840-config.h:
    #define OPENTHREAD_CONFIG_LOG_OUTPUT OPENTHREAD_CONFIG_LOG_OUTPUT_NCP_SPINEL
    
  2. Build the nrf52840 example with the desired level of logs and other NCP-specific flags. To build a joiner with all logs enabled:
    make -f examples/Makefile-nrf52840 JOINER=1 USB=1 FULL_LOGS=1
    
  3. Flash the NCP, connect it to the Linux host, and start wpantund as detailed in the OpenThread Hardware Codelab.
  4. Once the NCP is running, check the syslog on the Linux machine:
    tail -F /var/log/syslog | grep "ot-ncp-ftd"
    
  5. You should see OpenThread logs display in real time for the NCP. You may also see them in the wpantund output.

Change the log level at run time

Log levels may be changed at run time if dynamic log level control is enabled.

  1. Edit /src/core/openthread-core-default-config.h and set OPENTHREAD_CONFIG_ENABLE_DYNAMIC_LOG_LEVEL to 1.
  2. Change the log level depending on your implementation:
    1. For a system-on-chip (SoC), use the Logging API within your OpenThread application.
    2. For an NCP, use wpanctl on the command line:
      wpanctl set OpenThread:LogLevel 5
      
      See wpan-properties.h in the wpantund repository for all the properties exposed to wpanctl and the Spinel API for its log level definitions.