Cookbook

  • 2020
  • 10/23/2020
  • Public Content
Contents

Enabling Performance Profiling in GitLab* CI

This recipe helps you integrate
Intel® VTune™
Profiler
into your GitLab* CI pipeline to profile your builds on-the-fly.
Content expert:
Dmitry Sivkov
This recipe demonstrates how you can enable unattended, automated profiling of your builds by including
VTune
Profiler
into your GitLab Continuous Integration pipeline, and how to make access to the latest performance analysis data more convenient by using a static HTML feature of
VTune
Profiler
.
This approach offers the following advantages:
  • Automatic performance analysis:
    If a performance regression was introduced into the build, setting up a test environment and collecting performance results manually can be monotonous and consumes valuable time of the engineers. Integration of
    VTune
    Profiler
    into the testing stage of your GitLab CI pipeline allows you to automatically collect performance data in a predetermined environment and to upload the results automatically as an artifact.
    This eliminates manual work and lets you focus on determining the cause of the regression by making the performance results data readily available once the build is complete.
  • Customized configuration:
    The Command-Line Interface (CLI) capabilities of
    VTune
    Profiler
    allow for great flexibility in terms of CI integration. Using the CLI of
    VTune
    Profiler
    , you can set up a customized process that suits your team, for example, by selecting the necessary analysis types and parameters.
    Some examples of possible configurations are:
    • Automatically run a basic Hotspots analysis for each build
    • Profile a new build only when a performance regression was detected at the load testing stage of your build system and collect performance data for all the necessary analysis types
  • HTML analysis reports:
    VTune
    Profiler
    offers a command line option that generates a static HTML page with the summary for the collected result. This allows you to view the HTML page using your browser and to determine whether additional analysis is needed. Optionally, you can host these HTML reports as GitLab Pages for convenience.

INGREDIENTS

This section lists the software tools used for the performance analysis scenario.
  • Infrastructure:
    GitLab repository with a pre-configured GitLab CI pipeline, which includes:
    • Makefile for your project
    • Pre-populated
      .gitlab-ci.yml
      file
    • GitLab Runner with VTune Profiler installed
  • Tools:
    Intel® VTune™
    Profiler
    2020 (standalone or included in Intel® Parallel Studio XE or Intel® System Studio).
    • For
      VTune
      Profiler
      downloads and product support, visit https://software.intel.com/en-us/vtune.
    • All the Cookbook recipes are scalable and can be applied to Intel VTune Amplifier 2018 and higher. Slight version-specific configuration changes are possible.
    • Intel® VTune™ Amplifier has been renamed to Intel® VTune™ Profiler starting with its version for Intel® oneAPI Base Toolkit (Beta). You can still use a standalone version of the VTune Profiler, or its versions integrated into Intel Parallel Studio XE or Intel System Studio.

Install GitLab Runner

If you do not have a configured GitLab Runner, to install and configure the GitLab Runner software package, follow the instructions provided in the official GitLab documentation available at https://docs.gitlab.com/runner/#install-gitlab-runner.
After installing GitLab Runner, install
VTune
Profiler
using your preferred method. For instructions and available installation methods, see the
VTune
Profiler
Install Guide
.
  • Make sure to set
    /proc/sys/kernel/perf_event_paranoid
    to 0 to allow hardware event-based sampling collection without root privileges. For more information on profiling without Intel sampling drivers or root privileges, see the Profiling Hardware Without Intel Sampling Drivers Cookbook recipe.
  • The performance analysis result may vary depending on the Runner selection and the individual machine running the analysis.

Configure Automatic Data Collection

Add the
vtune
command calls and the artifact handling commands to your GitLab pipeline. For example, you can add the following command to your
.gitlab-ci.yml
file:
vtune -collect hotspots ./
<your_application>
This command launches the application specified by the last command option and collects Hotspots analysis data. It also stores the results data in a separate directory.
You can upload any combination of
VTune
Profiler
results and summary HTML pages. For example, you can upload the full analysis result and the static HTML summary page for a quick overview of the performance of your application.
To generate a static HTML page, include the following command:
vtune -report summary -format=html > hotspots_summary.html
To upload the full
VTune
Profiler
result as an artifact, it is necessary to package the result directory with your tool of choice. For example, to package the result data with
tar
:
tar -c r00* > vtune_result.tar
  • Using the
    vtune
    command, you can specify any options and select any analysis types that are valid for your environment. For more information on how to run an analysis from the command line, see the Run Command Line Analysis page of the online User Guide.
  • The graphical user interface of
    VTune
    Profiler
    offers a Command Line Configuration Generation feature, which allows you to conveniently pre-configure an analysis in the GUI and to instantly generate and copy a command that includes all the options and parameters that are necessary for your preferred analysis configuration. You can use this feature to quickly generate a command for later use.
For more information on manually creating a
vtune
command, see the Command Line Interface chapter of the online User Guide.
You may encounter limitations regarding the type of analysis you can run in a certain environment. For example, the Microarchitecture Exploration analysis type is not available under certain virtual machine hypervisors.

Configure an Automatic Upload of your Results as Artifacts

Add the files that you wish to upload to the
artifacts/paths:
section of your
.gitlab-ci.yml
file. For example, to upload both the HTML summary and a
.tar
file with the result directory:
artifacts: paths: - <relative-path-to-project>/vtune_result.tar - <relative-path-to-project>/hotspots_summary.html
Make sure to upload your result as a GitLab artifact. Otherwise, the results are still saved on the machine running
VTune
Profiler
, but you will have to retrieve them manually.

View the Results Data

Once a build is complete, you can use the GitLab web interface to quickly access the analysis summary page. To do this:
  1. On GitLab, navigate to the Pipelines page.
  2. From this page, you can either download the entire artifact bundle, or browse to the HTML page separately and determine whether downloading the precollected result is necessary based on the summary.
To download the HTML page separately:
  1. Navigate to the pipeline stage report page and click
    Browse
    .
  2. Navigate to the location of the HTML page and download it.
  3. Open the summary HTML in your browser of choice and determine whether additional analysis is needed.
To view the results data using the graphical user interface of
VTune
Profiler
:
  1. Extract the results files from the
    .tar
    archives.
  2. Launch the
    VTune
    Profiler
    GUI.
  3. Click the
    Open Result
    button and browse to the result file. The result data will open in a new tab.

(Optional) Resolve Newly Introduced Issues

If you detect a performance regression, you can use other analysis types offered by
VTune
Profiler
to help you identify and resolve the issues.
To discuss this recipe, visit the
VTune
Profiler
developer forum
.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804