Annotation helps you debug build problems by identifying performance issues and determining the reasons for rebuilding a “no-touch” build.
Determining why a target was rebuilt
The <job> tag includes a <why> tag with a reason as well as a prereq attribute if applicable. The <why> tag reports why a job ran, which lets you differentiate between eMake-only reasons (for example, reasons related to eDepend or Ledger) and make-related reasons (for example, the job target is absent or out of data).
Following is an example where the target did not exist before the job ran:
<job ...> ... <why reason="target-absent"/> ... </job>
During an incremental build, a job probably ran because a dependency was newer than the target. The <why> tag includes a prereq attribute. For example:
<job ...> ... <why reason="prereq-newer" prereq="/path/to/hello.c"/> ... </job>
The following example demonstrates the eDepend ( --emake-autodepend=1 ) feature. The job was run because of this dependency:
<job ...> ... <why reason="autodep-prereq" prereq="/path/to/conf-obj-dir"/> ... </job>
Following are the possible values for the reason attribute. These indicate the reasons that a job can be run:
always-make autodep-prereq double-colon-no-prereq dryrun-prereq intermediate-newer invalid-charset ledger not-run phony prereq-absent prereq-did-work prereq-newer target-absent
double-colon-no-prereq is gmake-only. invalid-charset and prereq-did-work are NMAKE-only. autodep-prereq, intermediate-newer, prereq-absent, prereq-did-work, and prereq-newer can have a prereq attribute. For details about the complete list of possible values, see the CloudBees Build Acceleration Annotation Guide.
Profiling metrics
Annotation includes profiling metrics. These are the same metrics that are in the debug log file when the --emake-debug=g option is set. (The metrics appear in annotation whether or not --emake-debug=g is used.) These metrics are intended for use by CloudBees technical support and engineering staff.
Profiling metrics are within the <profile> tag and appear exactly as they do in the debug log file.
Per-job performance metrics
Annotation includes per-job performance metrics. These metrics track a variety of details about the performance of each job in the build. For example, metrics with the A2E_ prefix reflect low-level details of the eMake/agent protocol, such as file data and metadata requests made by the agent on behalf of the commands run during the job. Not all metrics are for use by end users, but CloudBees technical support and engineering staff might use them for certain performance analyses.
Per-job performance metrics are within the <jobMetrics> tag as in the following example.
<job... > ... <jobMetrics> A2E_GET_ALL_VERSIONS 11 A2E_GET_FILE_DATA 2 </jobMetrics> ... </job>