Dumping modem traces over UART after capture

You can configure the device to continuously capture modem traces to external flash memory. After capture, you can use a shell command to dump the stored traces over UART using the Cellular Monitor app for storage and analysis.

Important

The flash trace backend needs two things from devicetree on top of the Kconfig options below: the modem trace shared-memory region (see the UART Tracing note) and a dedicated modem_trace flash partition. Both are already declared by app/overlay-upload-modem-traces-to-memfault.overlay, which you can use directly or copy as a starting point. Pass it on the build command line with -DEXTRA_DTC_OVERLAY_FILE="overlay-upload-modem-traces-to-memfault.overlay".

Add to prj.conf:

CONFIG_FCB=y
CONFIG_FLASH_MAP=y
CONFIG_NRF_MODEM_LIB_TRACE=y
CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_LTE_AND_IP=y
CONFIG_NRF_MODEM_LIB_TRACE_BACKEND_FLASH=y
CONFIG_NRF_MODEM_TRACE_FLASH_NOSPACE_ERASE_OLDEST=y
CONFIG_NRF_MODEM_LIB_TRACE_STACK_SIZE=896
CONFIG_NRF_MODEM_LIB_TRACE_FLASH_SECTORS=255
CONFIG_NRF_MODEM_LIB_TRACE_BACKEND_FLASH_PARTITION_SIZE=0xFF000
CONFIG_NRF_MODEM_LIB_SHELL_TRACE=y

Important

Flash Partition Configuration:

The flash partition size configuration allocates 255 sectors of 4 kB each (approximately 1 MB) for trace storage. Adjust the CONFIG_NRF_MODEM_LIB_TRACE_FLASH_SECTORS and CONFIG_NRF_MODEM_LIB_TRACE_BACKEND_FLASH_PARTITION_SIZE Kconfig options according to your available flash memory.

Trace Buffer Limitations:

Depending on the trace level, network, and IP activity, the trace buffer might get full. Due to a current limitation in Zephyr, the maximum size of the buffer is approximately 1 MB.

Trace Level Configuration:

To mitigate buffer overflow issues, the trace level can be adjusted through the CONFIG_NRF_MODEM_LIB_TRACE_LEVEL choice symbol:

CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_OFF: Disable output
CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_COREDUMP_ONLY: Coredump only
CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_IP_ONLY: IP only
CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_LTE_AND_IP: LTE and IP (recommended for most use cases)
CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_FULL: LTE, IP, GNSS, and coredump (highest data volume)

Adjusting the trace level will set how often the trace buffer is filled up. When the trace buffer gets full, the oldest entry will be overwritten. To disable this, disable CONFIG_NRF_MODEM_TRACE_FLASH_NOSPACE_ERASE_OLDEST.

The following modem_trace shell commands are available:

modem_trace - Commands for controlling modem trace functionality.
Subcommands:
  start      : Start modem tracing.
  stop       : Stop modem tracing.
  clear      : Clear captured trace data and prepare the backend for capturing
               new traces.
               This operation is only supported with some trace backends.
  size       : Read out the size of stored modem traces.
               This operation is only supported with some trace backends.
  dump_uart  : Dump stored traces to UART.

Complete the following to capture traces:

Connect to the device using a serial terminal.
Start capturing traces using the Cellular Monitor app on UART 1 or call the following nRF Util command:
```
nrfutil trace lte --input-serialport /dev/tty.usbmodemxxxxxx --output-raw raw-file.bin
```

Execute the dump command:

uart:~$ modem_trace stop
uart:~$ modem_trace dump_uart

When the traces have been captured, they can be converted to PCAP in the Cellular Monitor app for analysis.