nRF Profiler

The nRF Profiler provides an interface for logging and visualizing data for performance measurements, while the system is running. You can use the module to profile Application Event Manager events or custom events. The output is provided using RTT and can be visualized in a custom Python backend.

See the Profiler sample for an example of how to use the nRF Profiler.

Configuration 

Since Application Event Manager events are converted to nRF Profiler events, the nRF Profiler can be configured to profile custom events or Application Event Manager events, or both.

Configuring for use with custom events 

To use the nRF Profiler for custom events, complete the following steps:

Enable the CONFIG_NRF_PROFILER Kconfig option. This option adds the nRF Profiler source code to the application.
Call nrf_profiler_init() during the application start to initialize the nRF Profiler.
Profile custom events, as described in the following section.

Profiling custom events

To profile custom events, complete the following steps:

Register the custom events using nrf_profiler_register_event_type(). The following code example shows how to register event types:

static const char * const data_names[] = {"value1", "value2", "value3", "value4", "string"};
static const enum nrf_profiler_arg data_types[] = {NRF_PROFILER_ARG_U32, NRF_PROFILER_ARG_S32,
            NRF_PROFILER_ARG_S16, NRF_PROFILER_ARG_U8,
            NRF_PROFILER_ARG_STRING};

no_data_event_id = nrf_profiler_register_event_type("no_data_event", NULL,
            NULL, 0);
data_event_id = nrf_profiler_register_event_type("data_event", data_names,
            data_types, 5);

Add a structure for sending information about event occurrences:
1. Add the following mandatory functions to the structure:
  - nrf_profiler_log_start() - Start logging.
  - nrf_profiler_log_send() - Send profiled data.
2. Add one or more of the following optional functions in-between the mandatory functions, depending on the data format:
  - nrf_profiler_log_encode_uint32() - Add 32-bit unsigned integer connected with the event.
  - nrf_profiler_log_encode_int32() - Add 32-bit integer connected with the event.
  - nrf_profiler_log_encode_uint16() - Add 16-bit unsigned integer connected with the event.
  - nrf_profiler_log_encode_int16() - Add 16-bit integer connected with the event.
  - nrf_profiler_log_encode_uint8() - Add 8-bit unsigned integer connected with the event.
  - nrf_profiler_log_encode_int8() - Add 8-bit integer connected with the event.
  - nrf_profiler_log_encode_string() - Add string connected with the event.

Wrap the calls in one function that you then call to profile event occurrences. The following code example shows a function for profiling an event with data:

static void profile_data_event(uint32_t val1, int32_t val2, int16_t val3,
            uint8_t val4, const char *string)
{
  struct log_event_buf buf;

  nrf_profiler_log_start(&buf);
  /* Profiling data connected with an event */
  nrf_profiler_log_encode_uint32(&buf, val1);
  nrf_profiler_log_encode_int32(&buf, val2);
  nrf_profiler_log_encode_int16(&buf, val3);
  nrf_profiler_log_encode_uint8(&buf, val4);
  nrf_profiler_log_encode_string(&buf, string);
  nrf_profiler_log_send(&buf, data_event_id);
}

Note

The data_event_id and the data that is profiled with the event must be consistent with the registered event type. The data for every data field must be provided in the correct order.

Configuration for use with Application Event Manager 

If you are using the Application Event Manager, in order to use the nRF Profiler follow the steps in Implementing profiling for Application Event Manager events and Configuration on the Application Event Manager profiler tracer documentation page.

Enabling supported backend 

The nRF Profiler supports a custom backend that is based around Python scripts to visualize the output data. The backend communicates with the host using RTT.

To save profiling data, the scripts use CSV files for event occurrences and JSON files for event descriptions.

Available scripts 

The scripts can be found under scripts/nrf_profiler/ in the nRF Connect SDK folder structure. The following script files are available:

data_collector.py - This script connects to the device using RTT, receives profiling data, and saves it to files. When running the script from the command line, provide the time for collecting data (in seconds) and the dataset name. For example:
```
python3 data_collector.py 5 test1
```
In this command, 5 is the time value for collecting data and test1 is the dataset name.
plot_from_files.py - This script plots events from the dataset that is provided as the command-line argument. For example:
```
python3 plot_from_files.py test1
```
In this command, test1 is the dataset name.
real_time_plot.py - This script connects to the device using RTT, plots data in real-time, and saves the data. When running the script from the command line, provide the dataset name. For example:
```
python3 real_time_plot.py test1
```
merge_data.py - This script combines data from test_p and test_c datasets into one dataset test_merged. It also provides clock drift compensation based on the synchronization events: sync_event_p and sync_event_c. This enables you to observe times between events for the two connected devices. As command-line arguments, provide names of events used for synchronization for a Peripheral (sync_event_p) and a Central (sync_event_c), as well as names of datasets for the Peripheral (test_p), the Central (test_c), and the merge result (test_merged). For example:
```
python3 merge_data.py test_p sync_event_p test_c sync_event_c test_merged
```

Running the backend 

To enable and run the custom backend, complete the following steps:

Connect device to the computer.
Complete the configuration steps for use with either custom events or Application Event Manager, as described in the Configuration section.
From the list of Available scripts, choose the Python script that you want to use for event visualization, analysis, and calculating statistics.
Run the script from the command line using its related command.

Backend visualization 

When you run either the plot_from_files.py or the real_time_plot.py script, the profiled events are visualized in a GUI window.

The visual output can look like the following diagram:

Example of nRF Profiler backend script visualization

In this diagram:

Red dots indicate the submissions for the related events.
Blue vertical rectangles indicate the processing of the events, with their width corresponding to the processing time length.
The Start/Stop button can be used to pause or resume the real-time plot translation.

The GUI also supports the following actions:

Scrolling on the diagram using the mouse wheel zooms it in or out.
- When plotting is paused, scrolling zooms to the cursor location.
- When plotting in running, scrolling zooms to the right edge of the plot.
Middle mouse button can be used to mark an event submission or processing for tracking, and to display the event data.
When plotting is paused, you can click and drag with the left mouse button to pan the plot.
You can click the left or right mouse button to place a vertical line at the cursor location. When two lines are present, the application measures the time between them and displays it.

Shell integration 

The nRF Profiler is integrated with Zephyr’s Shell module. You can use the CONFIG_NRF_PROFILER_SHELL option to add an additional subcommand set (nrf_profiler) to the shell. The option is enabled by default.

This subcommand set contains the following commands:

list: Show a list of profiled event types. The letters “E” or “D” indicate if profiling is currently enabled or disabled for a given event type.
enable or disable: Enable or disable profiling. If called without additional arguments, the command applies to all event types. To enable or disable profiling for specific event types, pass the event type indexes (as displayed by list) as arguments.

API documentation 

Header file: include/nrf_profiler.h

Source files: subsys/nrf_profiler/

Profiler