Analyze build failures

The Builds tab shows details about the builds that ran as part of a pipeline run. The following section describes how to use build failure classification to pinpoint the source of build failures.

Build details

When you select a pipeline step in the left pane, the Builds tab shows build details of the selected step, and of its child pipeline steps. You can view a build's information such as the build's status, number, and duration, the build run history, the percentage of failed tests in this build that are being handled.

If configured, a custom report link to a build report stored externally is also available. For details on configuring custom build report links, see Label pipeline steps by job type.

Set the Assign to field to assign someone to investigate a failed build, as described in the section Assign someone to investigate failures. This is useful in case the build failed for reasons that are not related to a specific test. For example, the environment may need attention, or the build may have failed during compilation. For details, see Build failure classification below.

You can move between runs to help troubleshoot problems, using the Run selector in the upper right corner. Note that the Overview tab will always show the latest run.

Tip: Some builds might not be included.

You can configure hiding builds failures resulting from specific pipeline steps. For details, see Ignore or hide results of specific steps.

To check whether a step's builds are hidden, look at the step in the pipeline's Topology tab:

Back to top

Build failure classification

A label on a failed build indicates the type of issue that caused the failure. For example, Test code issue, Code issue, and Environment issues.

Use the build failure classification to determine who needs to handle the pipeline run failures and what issues need to be addressed.

You can classify builds manually to document the result of an investigation. For CI tools that support log injection, such as Jenkins and Bamboo, you can create rules to automatically classify your builds based on the build logs. For details, see Analyze build log messages.

The build failure classification is also presented at the pipeline run level. You can see the number of failed builds in this pipeline run, broken down by type of failure.

To view only build failures with a specific build failure classification, add a cross-filter using the CI build. Build fail classification field:

To understand what are the most common reasons for your build failures over time, add the Pipeline build failure classifications over time widget to your pipeline's dashboard. Hover over a specific run to see its classification details. Use this widget to determine whether your network or database is causing a lot of problems, tests are changing too often, code errors are being introduced and so on.

Tip: By default, this widget is set to show builds from the past week and to hide Unclassified builds if there are any classified builds.

Back to top

Classify build failures manually

After you investigate a build failure and know what caused it, use the Build Failure Classification button to label the failed build. This helps you share the results of your investigation and keep track of them for future analysis.

To add, replace, or clear the classification label:

  1. In a pipeline run, open the Builds tab.

  2. Select one or more failed builds.

  3. Click the Build Failure Classification toolbar button.

    Add new classification labels to the list.

  4. Select a classification label from the drop-down list.

    If the build was previously classified automatically, your manual classification overrides the automatic one.

Tip: To clear the classification label, click Clear

Back to top

Analyze build log messages

When you select a job in the left pane, the Logs tab shows you a local copy of the build log. You can then create rules map specific log messages to build failure classifications, and automatically classify builds based on the build logs.

In the Builds tab, the build failure classification label on a failed build indicates the type of issue that caused the failure. For example, Test code issue, Code issue, and Environment issues. You can use the build failure classification to determine who needs to handle the pipeline run failures and what issues need to be addressed.

Back to top

Create rules to classify build failures automatically

You can use rule patterns to automatically classify build failures.

To create a rule pattern:

  1. In a pipeline run, open the Logs tab.

  2. In the build log, select a log message to classify.

  3. Click + to add a rule.

  4. Give the rule a meaningful name, such as Illegal Number.

  5. The Rule pattern contains the text from the selected log line.

    Modify the Rule pattern to identify the log lines you want to map to a specific build failure classification.

    Replace parts of the text with wildcards (*) and add a \ before special characters.

    Example: *illegal number*

    As you edit the pattern, the matching text in the Selected log line area is highlighted. You can only save a rule if your pattern highlights the entire line.

  6. Select a classification to assign to log lines that match the pattern.

    Example: Environment - Other

    Tip: Admins can add classification labels to the list using the manual Build Failure Classification button.

  7. Click OK.

    The classification you specified is assigned to:

    • The selected log line in the build log file

    • All log lines that match the rule in future failed build logs.

      If a line matches more than one rule, it is classified by the most recently updated rule.

    All future failed builds are automatically labeled with the first classification mapped in their log.

Back to top

Edit or delete classification rules

When you open a build log for a CI tool that supports log injection such as Jenkins or Bamboo, you will see the classification labels that were applied by existing rules. If you are the author of the rule, you can modify or delete it.

You can see and modify all of the build failure classification rules in the Settings area. For details, see Manage build failure classification rules.

To view and change rules in a build log file:

  1. In a pipeline run, open the Logs tab.

  2. In the build log, hover over a specific line's classification label to see whose rule assigned that label.

  3. If you are the author of the rule, click Delete Rule or Edit Rule to make changes to the rule. Otherwise, click the author to send him or her an email about modifying their rule.

    Edit the rule's details as described in Create rules to classify build failures automatically.

What happens when I change a rule that is in use?

If you change a rule's classification, any log line already assigned by this rule is labeled with the new classification.

This affects log files from previous builds, but does not affect the classification of any existing builds. The change in the rule affects the classification of future builds only.

What happens when I delete a rule that is in use?

If you delete a rule that has already assigned a classification to a build log line, the classification is removed from all log files, but remains on any builds is was assigned to.

Back to top

See also: