Developer Guide

  • 2021.3
  • 11/18/2021
  • Public

Instrument the Code

You will need to add Instrumentation and Tracing Technology API (ITT API) calls to your real-time application to designate the tasks that you want to measure. This topic covers the basic flow of calls that you need to add. For more information about ITT APIs, see VTune™ Profiler User Guide.
To instrument your real-time application, use the following sequence of operations:
  1. Define and initialize the domain and task handle (the measurement). Parameters:
    • domain_name
      : String identifier of the domain. A domain enables tagging trace data for different modules or libraries in a program. You can selectively enable or disable specific domains in your application, in order to filter the subsets of instrumentation that are collected. The overhead of a disabled domain is a single
      check. You need to create at least one domain. Domain name has no impact on the API behavior.
    • measurement_name
      : String identifier of the measurement instance. You can use any name suitable for your use case, such as
      , or
      . This name will be used to identify this measurement instance for buffer configuration (Control Data Collection) and analysis. Example:
    __itt_domain* domain = __itt_domain_create(domain_name); __itt_string_handle* measurement = __itt_string_handle_create(measurement_name);
  2. Start the measurement. Call
    at the beginning of the task. The API collects the measurement start time based on the CPU’s timestamp counter (TSC). Parameters:
    • domain
      : Pointer to the
      structure. Must not be
    • measurement
      : Pointer to the
      structure. Example:
    __itt_task_begin(domain, __itt_null, __itt_null, measurement);
  3. End the measurement. Call
    at the end of the task. The API collects the measurement end time based on the TSC and calculates the difference between the start and end times to get the latency measurement. Your workload can have multiple nested measurements, and
    pairs with the last started measurement. Parameter:
    • domain
      : Pointer to the
Example of the instrumented code with three measurement instances: one for the entire cycle and two for different stages within the cycle:
/* Initialize the ITT domain */ __itt_domain* domain = __itt_domain_create("TCC"); /* Initialize the ITT handlers to collect performance data */ __itt_string_handle* stage1_handler = __itt_string_handle_create(stage1_name); __itt_string_handle* stage2_handler = __itt_string_handle_create(stage2_name); __itt_string_handle* cycle_handler = __itt_string_handle_create(cycle_name); for (int i = 0; i < iterations; ++i) { /* Start cycle measurement */ __itt_task_begin(domain, __itt_null, __itt_null, cycle_handler); /* Start stage 1 measurement */ __itt_task_begin(domain, __itt_null, __itt_null, stage1_handler); /* Run stage 1 */ stage1(); /* End stage 1 measurement */ __itt_task_end(domain); /* Start stage 2 measurement */ __itt_task_begin(domain, __itt_null, __itt_null, stage2_handler); /* Run stage 2 */ stage2(); /* End stage 2 measurement */ __itt_task_end(domain); /* End cycle measurement */ __itt_task_end(domain); }

Product and Performance Information


Performance varies by use, configuration and other factors. Learn more at