Build Cache - Monitoring and Diagnosing Efficiency

This feature is only available in Incredibuild's Enterprise and Business Plans.

Monitoring the Effectiveness of Build Cache

Details of how much time was saved from using the Build Cache is included in the output of all of your builds. This can be seen in the summary tab of the Build Monitor, as well as the output you see in the command line.

Note: The sizes of submitted and restored files may differ slightly from your original files, and may differ from each other due to metadata that Incredibuild adds to the files.

You can also see the cache hit rate in the Build Monitor's Progress Display:

  • Tasks to cache are tasks that were executed and are candidates to be added to the Build Cache for future builds.

  • Cache hits are tasks that were retrieved from the Build Cache instead of being executed.

Cache Sizing Warnings

If any tasks were not cached because the Build Cache was full, you can view the warnings in the Build Monitor > Warnings tab.

In the Build Cache section, the following warnings indicate an issue with your Build Cache size: 

  • System low on free space

  • Endpoint rejected caching of X tasks....due to cache size limitation

  • Build Cache endpoint is unable to fully cache this build. Please consider increasing the cache size.

Examining Cache Efficiency Further

If the hit rate is low, you can investigate the reason by enhancing the output to include information about each task. Go to Agent Settings > Initiator > Build Cache Client Settings and change Include more details in build output to on.

Note that this may take time and slow down your build. In extreme cases (40,000 tasks) this has been seen to take up to 15 minutes beyond your expected build time.

Run another build and examine the Build Cache tab in the Build Monitor. This includes a detailed Build Cache hit/miss report with extensive information about each task, including whether it was a hit or miss, and in case of cache miss it will show you the reason for the miss.

Every task in your build appears in the report. Expand a task to see the exact information about the task and how Build Cache was able to handle it, as denoted in the Cache line:

The cache behavior for each task is visible on the line starting with “Cache”. The values can be one of the following: 

  • HIT-RESTORED

    This task was found in the cache, and the task contents were retrieved saving the need to re-execute the task again. The line with Original exec time shows how long the task took originally – this is the time you saved by using Build Cache.

  • HIT-LICENSE-TEMPORARILY-DEPLETED

    This task was found in the cache but was not retrieved but rather was re-executed. This is because the Cache Cores license was depleted, pending the next reset time. This is an indication that your Cache Cores license cannot sustain the current load of Build Cache activity.

  • SKIP-UNSUPPORTED-TOOL

    The task was executed because Build Cache does not support the relevant tool.

  • SKIP-DISABLED-TOOL

    The task was executed because, although Build Cache support the relevant tool, it is disabled in the configuration. Depending on the case, it is possible to enable the tool and improve the hit rate for the build.

  • SKIP-PROFILE-FILTER

    The compilation task was executed (and not cached) because it is of a specific file type that is not included in the cache.

  • MISS-DATA-DELETED

    The task was executed because the cached item was evacuated earlier. The cache content is automatically purged periodically to remove redundant items. Had the cache been larger, it is possible that the relevant item would have been found and retrieved, improving the build hit rate.

  • MISS-NEW-SOURCE-FILE

    The task was executed because the source file has never been compiled before. Note: it is expected that all tasks of the first build on an empty (cold) cache will show this cache behavior.

  • SKIP-MANAGED-C++ (Deprecated. Replaced by SKIP-PROFILE-FILTER)

    The compilation task was executed because it compiles managed C++ code, which Build Cache doesn’t support.

  • MISS-EXISTING-SOURCE-FILE

    The task was executed before and stored in the cache, but none of the cached items can be used for this build.

    In this case, the report includes a table with the relevant cached items (from previous builds) and the reason why they can’t be used: INPUT-FILES (source or header mismatch), TOOL-VERSION (compiler or toolchain mismatch), COMMAND-OPTIONS (command line mismatch), or ENV-VARS (environment variables mismatch).