This guide lists and describes the format of CloudBees Build Acceleration annotation files. This guide is release-independent; therefore, it contains information for all CloudBees Build Acceleration releases as of the date of publication of this guide. Where appropriate, the earliest release that includes a specific tag or feature is noted. If no specific release is identified, then the tag or feature is available in all releases.
About annotation files
CloudBees Build Acceleration annotation files are an enhanced version of a standard build output log, "annotated" with additional information for troubleshooting and performance analysis. Annotation files are XML text in UTF-8 encoding, and therefore may be processed using any XML processing system. CloudBees recommends the use of CloudBees Build Acceleration Insight or annolib, the annotation processing library upon which CloudBees Build Acceleration Insight is built, but many users have written custom analysis tools using the programming language of their choice.
The structure of an annotation file is straightforward:
<build> <make> <job>...</job> <job>...</job> <make>...</make> <job>...</job> </make> </build>
That is, there is a root <build> tag which encompasses the entire document. Within that tag, there is a single <make> which represents the top-level emake or electrify invocation in the build. The <make> tag is populated by <job> tags which represent individual steps in the build (compiles, links, etc), and additional <make> tags for submakes spawned by jobs in the parent.
Each <job> in turn contains a wealth of information about the job, such as the commands run for the job, any output from those commands, and timing information about the job. The annotation may also include information about filesystem operations performed by those commands.
By taking the alternating job / make / job / make / … entries from a given job to the root of the document, we can construct a unique "job path" for every job in the build. This path is used in various ways by emake, most notably for describing cross-make-instance dependencies in history files. The job path can be seen in CloudBees Build Acceleration Insight by viewing the "Job Path" tab of the "Job Details" window for any job.
Note that the <make> tag for a submake immediately follows the closing </job> tag for the job that created it, rather than being nested inside the <job> tag as you might naturally expect. This placement reflects the manner in which emake processes the build.