CloudBees Accelerator Annotations Guide

This guide lists and describes the format of CloudBees Accelerator annotation files. This guide is release-independent; therefore, it contains information for all CloudBees Accelerator 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 Accelerator 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 Accelerator Insight or annolib, the annotation processing library upon which CloudBees Accelerator 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 Accelerator 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.

Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at www.cloudbees.com/jenkins/about. Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.