Dumping modem traces over UART after capture

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

Note

On top of the following Kconfig options, the flash trace backend needs two things from devicetree: the modem trace shared-memory region, which the note in UART tracing describes, and a dedicated modem_trace flash partition. The app/overlay-upload-modem-traces-to-memfault.overlay file already declares both, and you can use it directly or copy it as a starting point. Pass it on the build command line with -DEXTRA_DTC_OVERLAY_FILE="overlay-upload-modem-traces-to-memfault.overlay".

Add the following configuration to the prj.conf file:

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

Note

The flash partition size configuration allocates 255 sectors of 4 kB each, which is 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.

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

To mitigate buffer overflow issues, adjust the trace level through the CONFIG_NRF_MODEM_LIB_TRACE_LEVEL choice symbol:

CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_OFF: Disables the 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, which Nordic Semiconductor recommends for most use cases.
CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_FULL: LTE, IP, GNSS, and coredump, which has the highest data volume.

The trace level sets how often the trace buffer fills up. When the trace buffer gets full, the backend overwrites the oldest entry. To prevent the overwrite, 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.

To capture the traces, complete the following steps:

Connect to the device using a serial terminal.
Start capturing the traces with the Cellular Monitor app on UART 1, or run 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

Once the capture completes, convert the traces to PCAP in the Cellular Monitor app for analysis.