Getting Started with Develocity for sbt Users

Publish your first Build Scan® from your sbt build, then enable the local and remote Build Cache. You can introduce both incrementally, starting with CI builds.

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 doesn’t cover installation of Develocity. 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.example.com and has enabled HTTPS.

Quickstart

Try the steps in this guide against a real project. If you do not have a suitable project, use the quickstart project.

Build Scan

A Build Scan can be published for any build, including local development builds and CI builds. The fine-grained detail it captures supports collaborative debugging and optimization.

Applying the plugin

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

project/plugins.sbt
addSbtPlugin("com.gradle" % "sbt-develocity" % "1.4.5")

All Develocity settings are grouped under one configuration object that needs to be set in the ThisBuild scope. Unless you publish a Build Scan to Develocity at develocity.ai, you must set the Develocity server URL.

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

You might encounter a warning about an untrusted certificate when connecting to Develocity over HTTPS. The best solution is to add a valid SSL certificate to the Develocity instance, but that might not be within your control. In this case, set the allowUntrusted option to true:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://develocity.example.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:

Output
Publishing Build Scan to Develocity...
https://develocity.example.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.

Build Scan Highlights

Find and View Any Build Scan

Search through all the captured Build Scan records by going to https://develocity.example.com/scans.

Example of the Build Scan Overview Page
Example of the Build Scan Overview Page

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.

The listing also provides insight into the builds your organization runs. You might discover:

  • Build errors you were not aware of

  • Builds that take longer than you expected in certain cases

  • Users running more commands than they need to, and spending more build time as a result

Share Console Logs

The Build Scan includes the console output produced by the build. 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.

Example of the Build Scan Overview Page
Example of the Build Scan Overview Page

Select any line to highlight it, or hold Shift and select two lines to highlight a block. 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 want them to see.

Build Scan sections are directly linkable, which supports 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.

Example of the Tests Overview Page
Example of the Tests Overview Page

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 the Build Scan is the insight it provides into build performance. A build often serves different purposes for different people, and its performance varies by machine. 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.

Build Scan Performance Insights
Build Scan Performance Insights

The different tabs focus on different aspects of performance.

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

The Build Cache tab displays the Build Cache configuration, including whether the build used a remote Build Cache. It also lists the individual Build Cache operations and how long they took. Use it to analyze the performance of the remote Build Cache connection and to see whether a slow connection is affecting build time.

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

Example of the Timeline Overview Page
Example of the Timeline Overview Page

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

It also shows graphs of resource usage: CPU, memory, disk and network traffic. These graphs require 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 and helps you understand dependencies between them. To see the detail for a task, hover over it and click the details inspector icon.

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’s strongly recommended to configure your builds to always publish a Build Scan, for every build. Collecting Build Scan records for every build yields deeper visibility and insights into how your build is performing and being used.

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

Extending your Build Scan 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 (for example, CI or local)

  • Links to CI system record of build for CI builds

This adds useful context to your Build Scan.

Integrating Your CI Tool

The Build Scan is passive with regard to the build process. That’s to say, enabling the Build Scan doesn’t affect the outcome or outputs of your build. As such, it is safe to add the Build Scan configuration to your projects and check it in to version control. Doing so enables Build Scan publishing for everyone who runs the build.

The Build Scan plugin won’t cause build failures, even when there’s no connection available to the Develocity server when trying to publish.

Build Cache

The best way to accelerate your builds is to avoid work that has already been done. Build caching does this by fetching the outputs of a task execution 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 a task and its inputs, Develocity can detect when a build runs a task with the same inputs as a previous execution. It can then reuse the outputs from that execution instead of recomputing them.

The Develocity sbt plugin supports a local on-disk Build Cache and a remote Build Cache provided by Develocity. The remote Build Cache shares results across machines and users.

Quick Start

The local Build Cache is enabled by default. To fully test the remote Build Cache, temporarily disable the local Build Cache and enable storing outputs in the remote one.

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.

The first time you build your project against the remote Build Cache, you see uploads to the cache but no reuse from it. Run the same build again and it should succeed without compiling sources or running tests, because those results come from the remote Build Cache.

Develocity provides an overview of Build Cache activity at https://develocity.example.com/cache-admin. Use it to see the effect of running your build against the Build Cache.

Example of the Build Cache Usage Overview Page
Example of the Build Cache Usage Overview Page

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

See 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.example.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 can produce and reuse task outputs at different rates. A Build Cache is limited in size and evicts least recently used items to make space. A project that changes frequently and produces a large volume of outputs can dominate the Build Cache, leaving a low hit rate for other projects. Distributing projects across Build Cache nodes can yield higher hit rates.

The speed of network communication between the build and the Build Cache is the main factor in how effective a remote Build Cache is. A node closer to where the builds run, or with a better network connection to them, can reduce build 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.example.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 can 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 the Build Scan.

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 the Build Scan 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 use Develocity under a trial or a purchased license, you have received instructions for accessing Develocity support. If you have any issues with or questions about Develocity, please raise a support request.

If your issue can be discussed publicly, use the Gradle discussion forum. This is also the place to ask if you are not yet using Develocity. 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.

If you have any questions or need any assistance contact the Develocity support team or your customer success representative.