Understanding build performance

2 minute read

This section provides guidance for using Insight to help you understand build performance issues.

  • Specify the right annotation detail level

At a minimum, specify annodetail to basic. Additional detail levels enable more sophisticated analysis of the build. For maximum performance analysis, set annodetail to “basic,lookup,waiting,history,registry”. Because additional information might affect performance slightly, specify basic detail level only, unless you are actively pursuing a performance issue.

  • Use job details

When viewing an annotation file in Insight, you can see if your build is slow due to excessive conflicts, over serializations, or insufficient decomposition of build steps. You can then drill-down into job details by double-clicking individual jobs in the Agents & Jobs section.

  • Use reports

  • The Longest serial chain report can help estimate the best possible performance you can reasonably get from the build.

  • The Serialization analysis report can help you understand why jobs are serialized. In an optimal parallel build, all agents are busy at the same time.

For example, the image on the left shows a build that suffers from over serialization. Using the Serialization analysis report, you can determine why the build is serialized and adjust the build to eliminate serializations. The image on the right shows the result of making the correct adjustments.

  • Watch for the following in the Agents & Jobs section:

  • One agent bar is longer than others

  • If you see gaps where an agent is not running a job, carefully examine the running jobs while some agents are idle

  • Conflicts and reverted jobs

The presence of conflict and reverted jobs means the build was slower than necessary. Reverted jobs are symptoms of job conflicts. To eliminate reversions, you must eliminate conflicts. Usually, running a build with a history file eliminates conflicts. Typically, the most expensive job conflicts are those involving parse jobs.

If your build ran without a history file, you might have conflicts. If you had a pre-existing history file, your build should not contain conflicts unless the build changes affected job order and inter-dependencies.