Developer Guide

  • 2021.2
  • 06/11/2021
  • Public
Contents

Monitor Measurements and Deadlines

You can run the measurement analysis sample to monitor latency measurements and track deadline violations, based on data from a real-time application during application run. The real-time application must be instrumented with measurement library APIs.
In this mode, the analysis sample runs the instrumented application, attaches to the shared memory buffer, and starts reading the latency data that the instrumented application placed there. The analysis sample compares the data to the deadline. The sample prints each latency measurement at the moment when it was read and indicates whether it exceeded the deadline. After the application is finished, the analysis sample also stops. This type of analysis is called “stream monitoring.” This means that the results are constantly read from the shared memory buffer where they are placed by the instrumented application.
The analysis sample monitors the specified measurement instances from the real-time application. A
measurement instance
refers to the measurement library APIs that you have added to your application to measure the latency of the real-time cycle or any part of it. For more information about instrumenting your code with measurement library APIs, see Instrument the Code.
To run this example:
  1. From your host system, connect to the target system:
    ssh <user>@<target>
  2. In the SSH session
    , run the sample:
    tcc_measurement_analysis_sample monitor "Multiplication:5:3500" -time-units us -- tcc_multiple_measurements_sample --approximation 10000 --multiplication 100 --iterations 5
    where:
    Argument
    Description
    Multiplication:5:3500
    This argument specifies the measurement instance to collect:
    • “Multiplication” is the measurement name defined in the
      __itt_string_handle_create
      call in the
      tcc_multiple_measurements_sample
      .
    • “5” is the buffer size – the maximum number of measurements that can be stored for this measurement instance. The size matches the number of iterations specified in the
      tcc_multiple_measurements_sample
      command. To ensure all measurement results are stored, update the buffer size if you change the number of iterations when running the sample.
    • “3500” is the deadline in the time unit specified in
      -time-units
      .
    This argument has the same format as the
    TCC_MEASUREMENTS_BUFFERS
    environment variable. See Control Data Collection.
    -time-units us
    The output will display results in microseconds, and the deadline is specified in microseconds
    --
    Separates the measurement analysis sample command from the real-time application command. For more information about the command-line options of
    tcc_multiple_measurements_sample
    , see Command-Line Options.
  3. Feel free to edit the deadline value to see more or fewer deadline violations. For example, if the previous step did not generate any deadline violations, you can lower the deadline to try to generate deadline violations.
Output Example
The sample prints the output of the profiled application and the profiling results.
The profiling output includes the following:
  • Table of all measurement results. The analysis sample prints each measurement to the console immediately after it reads it from the shared buffer. Each row represents one measurement. If a measurement exceeded the deadline, this result is marked. Of the 5 measurements in this example, 1 exceeded the deadline.
  • Summary for each measurement instance:
    • Count of read data: Number of measurements that the analysis sample read from the shared memory buffer
    • Deadline violations: Number of measurements that exceeded the deadline
MONITORING OUTPUT: Monitoring "Multiplication" with deadline 3500 us. ---------------------------------- Name Latency(us) ---------------------------------- Multiplication 3751 Latency exceeding deadline Multiplication 3165 Multiplication 3175 Multiplication 3209 Multiplication 3145 [Multiplication] Count of read data: 5 (deadline violations: 1) ------------------------------ APPLICATION OUTPUT: Running with arguments: approximation = 10000, multiplication = 100, iterations = 5 Running workloads. This may take a while, depending on iteration values. Workloads were run successfully.

Buffer Size Influence

Internally, the measurement analysis sample runs the instrumented application with the
TCC_USE_SHARED_MEMORY
environment variable, so that measured values are stored in a ring buffer in shared memory. The instrumented application writes values to the shared memory, and the measurement analysis sample reads them from the shared memory.
If the buffer size (for example, Multiplication:5) is bigger than or equal to the number of iterations, the measurement analysis sample will read all values.
If the buffer size is smaller than the number of iterations, the count of read data may vary. The count may match the number of iterations in cases where the measurement analysis sample can read the data at about the same pace as the instrumented application writes the data. Otherwise, the count may be lower if the instrumented application writes values faster than the measurement analysis sample can read them. In this case, the instrumented application stops writing new values to the buffer until the measurement analysis sample reads the values from the buffer. While the application is waiting, the new values are dropped.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.