Getting Started with Develocity for sbt users

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.

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.

Applying the plugin

You apply the Develocity sbt plugin to your build by adding the following configuration block to a new or existing project/plugins.sbt file in your sbt project. The sbt plugin will be downloaded automatically from Maven Central once you load your build.

project/plugins.sbt

addSbtPlugin("com.gradle" % "sbt-develocity" % "1.1.2")

All Develocity settings are grouped under one configuration object that needs to be set in the ThisBuild scope. Unless you intend to publish Build Scans to scans.gradle.com, the minimum configuration required is that of the Develocity server URL.

build.sbt

ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://develocity.mycompany.com"))
    )
}

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:

build.sbt

ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://develocity.mycompany.com"))
        .withAllowUntrusted(true)
    )
}

This is a convenient workaround, but you shouldn’t use it in a production environment.

Given the above configuration, you can now run your build as usual. As the build completes, the last lines of the output will be similar to:

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

Follow that link to view your Build Scan.

More detailed information about the Develocity sbt plugin can be found in the Develocity sbt Plugin User Manual.

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 commands than they need to and are therefore subjecting themselves to more build time than they need to, and other previously unknown behaviors.

Share console logs

Build Scans include the console output produced by the build. Many tools used by the build, such as compilers, often write diagnostic information to the console log.

Use the left navigation menu to visit the Console log section.

Click on any line to highlight it or shift-click two different lines to highlight a block of lines. Note that the browser’s current location has been updated. By sharing that URL with a colleague, you can direct them to the exact console output that you wish them to see.

Many aspects of Build Scans are directly linkable to facilitate sharing and collaboration.

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 task, 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 tasks, test suites and test cases. Generally, it corresponds to the wall clock time that an execution lasted. 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 Timeline section.

This section provides insights into the task executions, visualizing them as a timeline. This representation clearly shows the parallel utilization of your build.

It also shows several graphs about resource usage (CPU, memory, disk and network traffic), when using Develocity sbt plugin 1.1 or later with sbt 1.7.0 or later.

The table below the graph provides a concise breakdown of the tasks executed during the build. The table provides more detail on individual tasks (click the icon when hovering over a task) and can be used to understand dependencies between tasks.

Next steps

Always publishing a Build Scan

The Develocity sbt plugin can be configured to:

Publish a Build Scan for every build invocation
Always publish if programmatically-defined criteria are met
Always publish if the build fails

The dedicated Develocity sbt plugin 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 being used.

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.

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

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 task executions, from a previous identical execution. Under the hood, a task is a function that takes some inputs and produces some outputs in a deterministic way. By analyzing the task mechanics and its inputs, Develocity can detect whether a given build tries to execute a given task with the same inputs as a previous execution, and decide to reuse the already produced outputs instead of recomputing them.

The Develocity sbt plugin 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.

build.sbt

ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withLocal(previous.buildCache.local.withEnabled(false))
        .withRemote(previous.buildCache.remote.withStoreEnabled(true))
    )
}

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 the build succeed without compiling sources or executing tests, as these results will be taken from the remote 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 tasks your build executed.

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

Remote Build Cache nodes

Build Cache nodes are the Build Caches that sbt 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 task 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 sbt build. Further configuration elements are detailed in the Develocity sbt plugin 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 sbt 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 conditionally enable the Build Cache in CI only:

build.sbt

ThisBuild / develocityConfiguration ~= { previous =>
  val isCi = sys.env.contains("CI")

  previous
    .withBuildCache(
      previous.buildCache
        .withLocal(
          previous.buildCache.local
            .withEnabled(isCi)
        )
        .withRemote(
          previous.buildCache.remote
            .withEnabled(isCi)
            .withStoreEnabled(isCi)
        )
    )
}

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.