Application Event Manager profiler tracer

The Application Event Manager profiler tracer is a library that enables profiling Application Event Manager events. It serves as a linking layer between Application Event Manager and the nRF Profiler and allows to profile Application Event Manager event submissions and processings as the Profiler events. The Profiler allows you to observe the propagation of an nrf_profiler event in the system, view the data connected with the event, or create statistics.

The events managed by the Application Event Manager are structured data types that are defined by the application and can contain additional data. The Application Event Manager profiler tracer registers nrf_profiler_info as trace_data of event types. The tracer uses this additional information to track the usage of events within the application.

See the Application Event Manager profiling tracer sample for an example of how to use the library with the nRF Profiler.

Configuration

To use the Application Event Manager profiler tracer, enable the CONFIG_APP_EVENT_MANAGER_PROFILER_TRACER Kconfig option. This Kconfig option also automatically initializes the Profiler.

Additional configuration

You can also set the following Kconfig options when working with the Application Event Manager profiler tracer:

• CONFIG_APP_EVENT_MANAGER_PROFILER_TRACER_TRACE_EVENT_EXECUTION - With this Kconfig option set, the Application Event Manager profiler tracer will track two additional events that mark the start and the end of each event execution, respectively.

• CONFIG_APP_EVENT_MANAGER_PROFILER_TRACER_PROFILE_EVENT_DATA - With this Kconfig option set, the Application Event Manager profiler tracer will trigger logging of event data during profiling, allowing you to see what event data values were sent.

Implementing profiling for Application Event Manager events

Note

Before you complete the following steps, make sure to implement Application Event Manager events and modules.

To profile an Application Event Manager event, you must complete the following steps:

1. Enable profiling Application Event Manager events using the CONFIG_APP_EVENT_MANAGER_PROFILER_TRACER Kconfig option.

2. Edit the source file for the event type:

   1. Define a profiling function that logs the event data to a given buffer by calling one of the following functions for every registered data type:

      • nrf_profiler_log_encode_uint32()

      • nrf_profiler_log_encode_int32()

      • nrf_profiler_log_encode_uint16()

      • nrf_profiler_log_encode_int16()

      • nrf_profiler_log_encode_uint8()

      • nrf_profiler_log_encode_int8()

      • nrf_profiler_log_encode_string()

      The nrf_profiler_log_start() and nrf_profiler_log_send() are called automatically by the Application Event Manager profiler tracer. You do not need to call these functions for Application Event Manager events. Mapping the nRF Profiler event ID to an Application Event Manager event is also handled by the Application Event Manager profiler tracer.

   2. Define an nrf_profiler_info structure using APP_EVENT_INFO_DEFINE in your event source file and provide it as an argument when defining the event type with APP_EVENT_TYPE_DEFINE macro. This structure contains a profiling function and information about the data fields that are logged. The following code example shows a profiling function for the event type sample_event:

      static void profile_sample_event(struct log_event_buf *buf, const struct app_event_header *aeh)
             {
                     struct sample_event *event = cast_sample_event(aeh);
      
                     nrf_profiler_log_encode_int8(buf, event->value1);
                     nrf_profiler_log_encode_int16(buf, event->value2);
                     nrf_profiler_log_encode_int32(buf, event->value3);
             }
      

      The following code example shows how to define the event profiling information structure and add it to event type definition:

      APP_EVENT_INFO_DEFINE(sample_event,
                             /* Profiled datafield types. */
                             ENCODE(NRF_PROFILER_ARG_S8, NRF_PROFILER_ARG_S16, NRF_PROFILER_ARG_S32),
                             /* Profiled data field names - displayed by nRF Profiler. */
                             ENCODE("value1", "value2", "value3"),
                             /* Function used to profile event data. */
                             profile_sample_event);
      
      APP_EVENT_TYPE_DEFINE(sample_event,
                             log_sample_event,       /* Function for logging event data. */
                             &sample_event_info,     /* Structure with data for profiling. */
                             APP_EVENT_FLAGS_CREATE(APP_EVENT_TYPE_FLAGS_INIT_LOG_ENABLE));  /* Flags managing event type. */
      

      Note

      • By default, all Application Event Manager events that are defined with an event_info argument are profiled.

      • sample_event_info is defined within the APP_EVENT_INFO_DEFINE macro.

3. Use the Profiler Python scripts to profile the application. See Enabling supported backend in the Profiler documentation for details.

Implementation details

The profiler tracer uses some of the Application Event Manager hooks to connect with the manager.

Initialization hook usage

The Application Event Manager provides an initialization hook for any module that relies on the Application Event Manager initialization before the first event is processed. The hook function should be declared in the int hook(void) format. If the hook function returns a non-zero value, the initialization process is interrupted and a related error is returned.

To register the initialization hook, use the macro APP_EVENT_MANAGER_HOOK_POSTINIT_REGISTER. For details, refer to API documentation.

The Application Event Manager profiled tracer uses the hook to append itself to the initialization procedure.

Tracing hook usage

The Application Event Manager provides an initialization hook for any module that relies on the Application Event Manager initialization before the first event is processed. The hook function should be declared in the int hook(void) format. If the hook function returns a non-zero value, the initialization process is interrupted and a related error is returned.

To register the initialization hook, use the macro APP_EVENT_MANAGER_HOOK_POSTINIT_REGISTER. For details, refer to API documentation.

The Application Event Manager profiled tracer uses the hook to append itself to the initialization procedure.

The Application Event Manager uses flexible mechanism to implement hooks when an event is submitted, before it is processed, and after its processing. The tracing hooks are originally designed to implement event tracing, but you can use them for other purposes as well. The registered hook function should be declared in the void hook(const struct app_event_header *aeh) format.

The following macros are implemented to register event tracing hooks:

• APP_EVENT_HOOK_ON_SUBMIT_REGISTER_FIRST, APP_EVENT_HOOK_ON_SUBMIT_REGISTER, APP_EVENT_HOOK_ON_SUBMIT_REGISTER_LAST

• APP_EVENT_HOOK_PREPROCESS_REGISTER_FIRST, APP_EVENT_HOOK_PREPROCESS_REGISTER, APP_EVENT_HOOK_PREPROCESS_REGISTER_LAST

• APP_EVENT_HOOK_POSTPROCESS_REGISTER_FIRST, APP_EVENT_HOOK_POSTPROCESS_REGISTER, APP_EVENT_HOOK_POSTPROCESS_REGISTER_LAST

For details, refer to API documentation.

The Application Event Manager profiler tracer uses the tracing hooks to register nRF Profiler events and log their occurrence when application is running.

API documentation

Header file: include/app_event_manager_profiler_tracer.h

Source files: subsys/app_event_manager_profiler_tracer/

Application Event Manager profiler tracer