How to Collect Session Data

# Summary

This guide demonstrates how to use Modality to collect a trace of system events for the first time. We assume your embedded system has already been instrumented with Modality.

# Open a Session

The unit of data collection in Modality is a session. Each session is associated with a System Under Test (SUT) and represents a single continuous run of execution.

  1. To begin collecting data, simply open a session by calling modality session open <session-name> <sut-name>
$ modality session open first-session drone

In the example above, this command creates a session named first-session which is associated with a drone SUT. There is no output if the command is successful.

  1. Next, we'll call modality session use <session-name> to set the default session for further commands.

  2. Then, we'll call modality status to check the default SUT and session, and to see which, if any, sessions are active.

$ modality session use first-session

$ modality status
┌─ Modality Status ────────────────────────────────────────┐
│                                                          │
│  Default User:                                           │
│  Default SUT:     drone                                  │
│  Default Session: first-session                          │
│                                                          │
├─ Active Session Info ────────────────────────────────────┤
│                                                          │
│  Name: first-session                                     │
│  Collector Connections:                                  │
│    udp://                                  │
│                                 │
│  Control Connections:                                    │
|    udp://                                 |
│                                                          │

In the example above, we can see that first-session is the default session and is currently active.

For more info on configuring connections for the active session, see the Modality configuration file reference.

# Generate and Label Data

  1. Next, let's run the system to generate some data:
$ ./
  1. To add some real-world context to this session, we can use Modality's scope functionality to label a region of execution for future analysis. After waiting for our drone to complete takeoff, we will:

$ modality session scope open figure_8

$ ./
Beginning figure 8 maneuver
Figure 8 maneuver completed successfully

$ modality session scope close figure_8
  1. In our example trace, we will now have a scope named figure_8 which contains the execution associated with our figure_8 script.

    • Scopes can be nested or overlap with other scopes. For example, figure_8 could be nested inside an airborne scope alongside other maneuvers.
  2. Having done that, we are ready to stop exercising the system and finish this round of data collection by calling modality session close <session-name>:

$ ./
Beginning landing procedure
Landing successful

$ modality session close

# See Session Statistics

At this point we have a completed session capturing takeoff, a figure 8, and then landing. To confirm that there is data in the session, we will call modality session probe list and modality session scope list to see the basic units that are in the session:

$ modality session probe list
NAME               TAGS                                               EVENTS
GAZEBO_SIMULATOR   [control-plane, gazebo, gazebo-plugin, simulator]  2634
PX4_BATTERY        [battery, control-plane, library, power, px4]      12239
PX4_COMMANDER      [commander, control-plane, module, px4]            9688
PX4_LAND_DETECTOR  [control-plane, land-detector, module, px4]        77
PX4_NAVIGATOR      [module, navigator, px4]                           5
PX4_SIMULATOR      [control-plane, module, px4, simulator]            8245

$ modality session scope list
figure_8  Closed  1

Now that you have collected a session, let's see how to analyze it.