Event Manager profiler tracer

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

The events managed by the Event Manager are structured data types that are defined by the application and can contain additional data. The Event Manager profiler tracer registers 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 Event Manager profiling tracer sample for an example of how to use the library with the Profiler.

Configuration

To use the Event Manager profiler tracer, enable the CONFIG_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 Event Manager profiler tracer:

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

• CONFIG_EVENT_MANAGER_PROFILER_TRACER_PROFILE_EVENT_DATA - With this Kconfig option set, the 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 Event Manager events

Note

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

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

1. Enable profiling Event Manager events using the CONFIG_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:

      • profiler_log_encode_uint32()

      • profiler_log_encode_int32()

      • profiler_log_encode_uint16()

      • profiler_log_encode_int16()

      • profiler_log_encode_uint8()

      • profiler_log_encode_int8()

      • profiler_log_encode_string()

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

   2. Define an profiler_info structure using EVENT_INFO_DEFINE in your event source file and provide it as an argument when defining the event type with 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 event_header *eh)
             {
                     struct sample_event *event = cast_sample_event(eh);
      
                     profiler_log_encode_int8(buf, event->value1);
                     profiler_log_encode_int16(buf, event->value2);
                     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:

      EVENT_INFO_DEFINE(sample_event,
                             /* Profiled datafield types. */
                             ENCODE(PROFILER_ARG_S8, PROFILER_ARG_S16, PROFILER_ARG_S32),
                             /* Profiled data field names - displayed by profiler. */
                             ENCODE("value1", "value2", "value3"),
                             /* Function used to profile event data. */
                             profile_sample_event);
      
      EVENT_TYPE_DEFINE(sample_event,
                             true,
                             log_sample_event,       /* Function for logging event data. */
                             &sample_event_info);    /* Structure with data for profiling. */
      

      Note

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

      • sample_event_info is defined within the EVENT_INFO_DEFINE macro.

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

Event Manager profiler tracer implementation details

Event Manager provides tracing hooks that you can use at run time to get information about Event Manager initialization, event submission, and event execution. The hooks are provided as weak functions. You can override them for interacting with a custom profiler or for other purposes.

The following weak functions are provided by Event Manager as hooks:

• event_manager_trace_event_execution()

• event_manager_trace_event_submission()

• event_manager_trace_event_init()

• event_manager_alloc()

• event_manager_free()

For details, refer to API documentation.

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

API documentation

Header file: include/event_manager_profiler_tracer.h

Source files: subsys/event_manager_profiler_tracer/

group event_manager_profiler_tracer

Event Manager profiler tracer.

Defines

ENCODE(...)

Encode event data types or labels.

Parameters

• ... – Data types or labels to be encoded.

EVENT_INFO_DEFINE(ename, types, labels, profile_func)

Define event profiling information.

This macro provides definitions required for an event to be profiled.

Note

Types and labels of the profiled values should be wrapped with the ENCODE macro.

Parameters

• ename – Name of the event.

• types – Types of values to profile (represented as profiler_arg).

• labels – Labels of values to profile.

• profile_func – Function used to profile event data.

struct profiler_info

#include <event_manager_profiler_tracer.h>

Event description for profiling.

Public Members

void (*profile_fn)(struct log_event_buf *buf, const struct event_header *eh)

Function for profiling data related with this event

const uint8_t profiler_arg_cnt

Number of profiled data fields.

const char **profiler_arg_labels

Labels of profiled data fields.

enum profiler_arg *profiler_arg_types

Types of profiled data fields.

const char *name

Profiled event name.