Getting Started with Develocity for Apache Maven™ users

This guide covers how to get started with Develocity, with topics such as strategies for incrementally introducing Build Scans and Build Cache usage, and key Build Scan features for improving your development productivity.

Develocity provides two complementary functions: Build Scan and the Build Cache. A Build Scan is a permanent and shareable record of an executed build that allows collaborative troubleshooting and optimization. The Build Cache makes builds faster by allowing reuse of the outputs of builds.

Installation

This guide does not cover installation of Develocity. Please consult one of the following installation manuals for help with installation:

The remainder of this guide will assume that your installation has a public hostname of develocity.mycompany.com and has enabled HTTPS.

Develocity Maven Extension

The configuration examples in this document assume you are using Develocity Maven extension 1.21 or later. For older versions, please refer to the (Legacy) Gradle Enterprise Maven Extension User Manual.

In order to use Build Scans and build caching, you must apply the Develocity Maven extension to your Maven project.

Automated setup

Execute the init goal to quickly set up the Develocity Maven extension on a Maven project:

mvn com.gradle:develocity-maven-extension:1.22.2:init -Ddevelocity.url=https://develocity.mycompany.com

See here for more information.

Manual setup

Apply the Develocity Maven extension to your build by adding the following configuration block to a new or existing .mvn/extensions.xml file in your Maven project. Maven automatically downloads the extension from Maven Central when you run your build.

Add the following to .mvn/extensions.xml

<extensions>
  <extension>
    <groupId>com.gradle</groupId>
    <artifactId>develocity-maven-extension</artifactId>
    <version>1.22.2</version>
  </extension>
</extensions>

You can also add the extension jar into the lib/ext folder of your Maven installation. This is useful if you are packaging a custom Maven installation for your organization and you want Develocity to be available to all your projects out of the box.

The extension is configured through one or more develocity.xml files and the pluginManagement sections of your pom.xml files. Similarly to the extensions.xml file, the develocity.xml file can be placed in your Maven project’s .mvn directory. Unless you intend to publish a Build Scan to scans.gradle.com, the minimum configuration required is the Develocity server URL.

Add the following to .mvn/develocity.xml

<develocity>
  <server>
    <url>https://develocity.mycompany.com</url>
  </server>
</develocity>

You may encounter a warning about an untrusted certificate when connecting to Develocity over HTTPS. The ideal solution is for someone to add a valid SSL certificate to the Develocity instance, but we recognise that you may not be able to do that. In this case, set the allowUntrusted option to true:

.mvn/develocity.xml

<develocity>
  <server>
    <url>https://develocity.mycompany.com</url>
    <allowUntrusted>true</allowUntrusted>
  </server>
</develocity>

This is a convenient workaround, but you shouldn’t use it as a long-term solution.

More detailed information about the Develocity Maven extension can be found in the Develocity Maven extension user manual.

Build Scan

Build Scans are a significant innovation in software build tooling. Having centralized and shareable records providing fine-grained details and insights of all builds, including local development builds, enables new levels of collaborative debugging and optimization.

Quick start

Build Scans are automatically enabled for all builds, when applying the Develocity Maven extension. In order for you to get started properly, you might want to publish only some scans first.

To do so, modify .mvn/develocity.xml as follows:

.mvn/develocity.xml

<develocity>
  ...
  <buildScan>
    <publish>ON_DEMAND</publish>
  </buildScan>
</develocity>

Then, execute your build as always, but adding the -Dscan system property to the command-line invocation. As the build completes, the last lines of output will be similar to:

Publishing build scan...
https://develocity.mycompany.com/s/3z475bz247h5g

Follow that link to view your Build Scan.

Build Scan highlights

This section calls out a subset of the things that you can do with Build Scans.

Find and view any Build Scan

Search through all the captured Build Scans by going to https://develocity.mycompany.com/scans.

This view allows searching by various criteria, including top-level project name, user name, build outcome, build start time and more. By default, the list is sorted to show the most recent scans first.

Beyond looking for a particular Build Scan, the listing can provide new insights into the actual builds being run at your organization and by your colleagues. You may find occurrences of previously unknown errors with your build, or that the build is taking longer in certain cases than you expected, or that certain build users are executing more goals than they need to and are therefore subjecting themselves to more build time than they need to, and other previously unknown behaviors.

Inspect test results

If your build executed tests, then their results will be included in your Build Scan. Use the left navigation menu to visit the Tests section.

This section shows the results of all the tests that ran during your build, along with their outcome and durations. The results are broken down by goal, test suite and test case. Select any test suite or test case to see details about each of their individual executions, in case of test retry. The total time is available for goal, test suites and test cases. Generally, it corresponds to the wall clock time that an execution lasted. Under some circumstances, some durations may be missing. Please refer to Viewing test results for more details.

Analyze build performance

A key benefit of Build Scans are the various insights they provide into build performance. Many builds provide different functions for different people and will perform differently on different machines. Having deep performance insights available for every build enables optimizing all corners of the build, for all users.

Use the left navigation menu to visit the Performance section.

The different tabs focus on different aspects of performance.

The Build tab provides a high level build time breakdown and memory information. It also shows several graphs about resource usage (CPU, memory, disk and network traffic), when using Develocity Maven extension 1.22 or later.

The Execution plan tab provides an interactive breakdown of the time spent preparing the execution plan of the projects participating in the build. The time shown for each project is the time taken before starting to execute the goals of the project. The most common contributor for a project is downloading plugins and dependencies.

The Dependency resolution tab provides shows insights about e.g. the dependency resolution for a given project or a given plugin. It also shows the size of the dependencies and if its resolution failed.

The Goal execution tab provides a concise breakdown of the goals that participated in the build, grouped by outcome. This provides a high level view of goal execution and can be used to understand build caching coverage for a particular build.

The Build Cache tab displays the Build Cache configuration for the build (e.g. whether a remote Build Cache was used), and lists the individual Build Cache operations and how long they took. This is particularly useful for analyzing the performance of the remote Build Cache connection and identifying whether a slow connection is having adverse effects on the build time.

The dedicated Timeline section (available via the left navigation menu) provides an alternative view onto the goal executions.

This view provides more detail on individual goals (click the icon when hovering over a goal execution).

Optimize cacheability

Build Scans make it easy to see which goals are cacheable, and why those that aren’t, aren’t. For instance, the surefire:test goal is cacheable for version 2.12.4 and above of the maven-surefire-plugin.

The Timeline section allows filtering of goal executions via certain criteria, one of which is cacheability.

This is useful when starting with build caching, and as your projects change and evolve, to ensure that you are getting the most out of the Build Cache.

Compare Build Scans to find differences

Develocity provides the ability to compare aspects of two Build Scans.

To compare two scans, use the scan list to find the scans to compare, selecting them by clicking the respective or icon. Or, from a scan that you wish to compare with another, click the Compare Build Scan on the left navigation menu.

Diagnose build caching issues

The goal inputs comparison is particularly effective in helping diagnose issues with build caching, particularly cases where reuse was expected but didn’t occur. In such cases, it is common that a non obvious input has actually changed which is preventing reuse. By comparing the inputs of the goal execution from the builds where reuse was expected, the exact input property with a different value between the builds is immediately apparent.

Trace reused goal execution outputs to their origin

When goal execution outputs are reused in a build, due to build caching, the Build Scan for that build provides links to the Build Scan of the origin build.

This feature can be used to provide an audit trail of build outputs, and for validating reuse. It is particularly useful for identifying and diagnosing incorrect reuse, which is typically caused by under declaration of goal inputs. In such cases, the Build Scan for the origin build can be used to determine the actual input state for cross referencing with the Build Scan that incorrectly reused the outputs.

To see this feature in action, create two Build Scans where one reuses output from another. The simplest way to do this is by running exactly the same build twice. View the Build Scan for the subsequent build and open the timeline visualization. Click on the icon of any goal that was FROM-CACHE, and click the View origin Build Scan link to view the Build Scan for the build that produced the reused outputs.

Next steps

Always publishing a Build Scan

The Build Scan plugin can be configured to publish a Build Scan for every build invocation, or, always publishing if certain programmatically defined criteria are met, or, always publishing if the build fails. The dedicated Develocity Maven extension user manual provides a section outlining how to do this.

It is strongly recommended to configure your builds to always publish Build Scans, for every build. Collecting Build Scans for every build yields deeper visibility and insights into how your build is performing and is being used, as well as making features such as tracing reused task outputs more effective.

Custom tags, values and links

Build Scans can be enriched with metadata particular to your environment by several means.

Extending your Build Scans with tags, values and links is strongly recommended. In particular:

VCS information such as commit identifiers, branch names, etc.
Tags for different types of builds (e.g. CI vs. local)
Links to CI system record of build for CI builds

This adds useful context to your Build Scans.

Integrating your CI tool

Build Scans are passive with regard to the build process. That is, enabling Build Scans does not affect the outcome or outputs of your build. As such, it is generally safe to simply add the necessary configuration to your projects to enable sending Build Scans to your Develocity installation and check it in to version control, enabling it for all users of the build. If you need to roll out the extension to lots of projects, consider creating your own extension to bundle the necessary configuration in a central place.

The Develocity Maven extension will not cause build failures, even when there is no connection available to the Develocity server when trying to publish.

Jenkins

The Gradle Jenkins plugin prominently displays links to the Build Scan for any Gradle or Maven build that produce Build Scans, which makes it convenient to access the Build Scans. See the following screenshot for an example:

Besides that, the plugin allows you to instrument all CI jobs and to publish a Build Scan without modifying the underlying projects. This eases the adoption of Build Scans within the company and allows configuring the Develocity Gradle plugin or Develocity Maven extension in a central place. For more information please read the documentation here.

TeamCity

The TeamCity Build Scan plugin prominently displays links to the Build Scan for any Gradle or Maven build that produce Build Scans, which makes it convenient to access the Build Scans. See the following screenshot for an example:

Bamboo

The Develocity Bamboo plugin prominently displays links to the Build Scan for any Gradle or Maven build that produce Build Scans, which makes it convenient to access the Build Scans. See the following screenshot for an example:

GitLab templates

The Develocity GitLab templates allow you to instrument CI jobs and to publish a Build Scan without modifying the project’s build scripts. This eases the adoption of Build Scans within the company and allows configuring the Develocity Gradle plugin or Develocity Maven extension at the CI level. For more information please read the documentation here.

Build Cache

The best way to improve the execution time of yours builds is by not executing something that was already executed, and just reuse the product of this initial execution. Build caching allows to potentially save a tremendous amount of build time by fetching the outputs of certain goal executions, from a previous identical execution. Under the hood, a goal is a function that takes some inputs and produces some outputs in a deterministic way. By analyzing the goal mechanics and its inputs, Develocity can detect whether a given build tries to execute a given goal with the same inputs as a previous execution, and decide to reuse the already produced outputs instead of recomputing them.

The Develocity Maven extension enables using a local on-disk Build Cache and a remote Build Cache provided by Develocity, that can be used to share the results amongst different machines and users.

Quick start

The local Build Cache is enabled by default. In order to fully test the remote Build Cache provided by your Develocity installation, you should temporarily disable the local Build Cache, and enable storing the outputs in the remote Build Cache.

.mvn/develocity.xml

<develocity>
  ...
  <buildCache>
    <local>
      <enabled>false</enabled>
    </local>
    <remote>
      <storeEnabled>true</storeEnabled>
    </remote>
  </buildCache>
</develocity>

The above configuration disables the local Build Cache, and always pushes outputs to the remote Build Cache, for demonstration purposes. Disabling the local Build Cache is generally not recommended and this should be removed for real usage. We recommend allowing storing of the outputs to the remote Build Cache from trusted build agents only, such as CI machines.

You can now run your build as usual.

If this is the first time your project is being built while using the remote Build Cache, you will not see any reuse from the Build Cache; only uploads to it. If you run the same build again, you should see output from Maven indicating that goal executions were reused from the Build Cache.

Develocity provides an overview of the Build Cache activity at https://develocity.mycompany.com/cache-admin, which you can use to see the effect of running your build against the Build Cache.

The exact numbers you see will depend on how many cacheable goals your build executed.

Please have a look at the list of cacheable goals supported by Develocity.

Remote Build Cache nodes

Build Cache nodes are the Build Caches that Maven builds connect to. Develocity provides a built-in node at https://develocity.mycompany.com/cache. If you don’t specify any remote Build Cache, this is the node where goal execution outputs will be stored. You can install additional “remote” nodes, potentially on different servers, and connect them with Develocity.

Different projects may produce and reuse goal outputs at different rates. As Build Caches are limited in size, with least recently used items being evicted to make space, a project that produces many outputs and is frequently changing may undesirably dominate the Build Cache and result in a low cache hit rate for other projects. Distributing projects across Build Cache nodes may yield higher hit rates.

The effectiveness of using a remote Build Cache is largely dictated by the speed of network communication between the build and the Build Cache. Using a Build Cache node that is closer to where the builds are run, or that otherwise has a better network connection to it, may reduce build times by reducing network transfer times.

The Build Cache Node User Manual details how to declare a remote node in your Maven build. Further configuration elements are detailed in the Develocity Maven extension user manual.

Configuration

Nodes can be configured by going to https://develocity.mycompany.com/cache-admin and navigating to the Nodes page.

In particular, consider increasing the Build Cache size from the default of 1 GiB to something in the 10s of GiB. The larger the Build Cache, the more it can store, which may increase your cache hit rate.

Next steps

Learning more about the Build Cache

Reading the dedicated Maven build caching guide is strongly recommended. This guide provides detailed information about build caching in general, including considerations for using it in practice. It also covers how to debug and optimize Build Cache usage using Build Scans.

Planning a roll out

The best roll out strategy depends on your circumstances. A common strategy however is to first enable Build Cache usage only for CI builds, then later enabling for local development builds. The Build Cache configuration within a build can be specified dynamically, supporting this kind of usage.

For instance, you can define the -Dgradle.user.config system property on your CI builds to indicate the location of the develocity.xml file that needs to be used in this case or you can utilize the extension support to conditionally apply configuration only on CI. If you need to roll out the extension to lots of projects, consider creating your own extension to bundle the necessary configuration in a central place.

Enabling Build Scans for any build using the remote Build Cache should be considered a prerequisite. Build Scan insights make it considerably easier to debug and optimize Build Cache usage.

Getting help or asking questions

If you are currently using Develocity as part of your trial sign-up or license purchase, you will have received instructions on how to access the priority Develocity support channel. If you have any issues with or questions about Develocity, please raise a support request.

Alternatively, or if you are not yet using Develocity, you can use the Gradle discussion forum if you are able to discuss your issue publicly. If you are unable to discuss your issue publicly, please use our contact form.

Keeping up to date

Develocity is constantly evolving with regular updates that add new features and capabilities. The monthly Gradle newsletter is an easy way to stay informed about new releases, features and events.