Develocity sbt Plugin User Manual

Develocity installations may be configured to require build scan publishing to be authenticated. Additionally, installations may be configured to only allow certain users to publish build scans. If your instance doesn’t require authentication, you can skip to Using build scans

For example, when invoking a single command in the shell:

sbt allows one to chain several commands separated by semicolons, as in compile; test. In this case, a build scan is published for each one of them:

When sbt is invoked with several tasks on the command line, as it’s often the case on CI, sbt will publish a single build scan for the whole sbt process.

This is the default. There are many advantages to publishing build scans regularly, such as being able to track the behavior and performance of a build over time. It makes no sense relying on ad-hoc publishing of scans in such a situation as it’s easy to forget on the command line. Should you decide to explicitly enforce this default option, you can do this as follows

This approach means that you get a build scan for every successful and failed build that runs, including from your continuous integration infrastructure and your developers.

We imagine that when you first start experimenting with build scans, you won’t want to publish them all the time until you become familiar with the implications. Even then, you may have good reason not to go all-in and automate the process. That’s where one-off build scans come in.

If you only want to publish build scans when explicitly requested, use the following publish configuration:

When publishing on-demand, you can pass the scan system property to control publishing:

This system property overrides the configured value, so it can also be used to disable publishing, regardless of the build setting by setting it to false.

Many of you will want a bit more control over exactly when build scans are published without resorting to using -Dscan each time. Perhaps you only want to publish build scans when the build fails, or if the build is running on your continuous integration infrastructure. Such scenarios are covered by the options in the following code snippets.

It may be desirable to conditionally set the value based on the environment.

Background uploading can be disabled by setting the gradle.scan.uploadInBackground system property to false. The system property setting always takes precedence over the programmatic setting.

Project identifier can be specified by setting the develocity.projectId. The system property setting always takes precedence over the programmatic setting.

Tags are typically used to indicate the type or class of a build, or a key characteristic. They are prominent in the user interface and quickly inform a user about the nature of a build. A build can have zero or more tags.

They can be added at build time via the buildScan.tags field:

As demonstrated by the example above, tags are typically applied either as fixed strings within a condition or evaluated at runtime from the environment. But there are no set rules that you need to follow—these are only suggestions.

Note that the order in which you declare the tags doesn’t affect the build scan view. They are displayed in alphabetical order, with any all-caps labels displayed before the rest.

Builds rarely live in isolation. Where does the project source live? Is there online documentation for the project? Where can you find the project’s issue tracker? If these exist and have a URL, you can add them to the build scan.

They can be added at build time via the buildScan.links field:

The above example demonstrates how you can attach a link to an online VCS repository that points to a specific branch provided as a system property.

Links are Scala pairs, with the first field being the label, and the second one a valid URL. The <label> is simply a string identifier that you choose and that means something to you.

You can see the effect of a custom link in figure 1, which shows how a label Source becomes a hyperlink that anyone viewing the build scan can follow.

Some information just isn’t useful without context. What does "1G" mean? You might guess that it represents 1 gigabyte, but of what? It’s only when you attach the label "Max heap size for build" that it makes sense. The same applies to git commit IDs, for example, which could be interpreted as some other checksum without a suitable label.

Custom values are designed for these cases that require context. They’re standard key-value pairs, in which the key is a string label of your choosing and the values are also strings, often evaluated from the build environment.

This examples shows that you can include any sbt setting value. This applies to tags and links as well.

As with tags, you can filter build scans by custom values in Develocity.

Indicates whether the build was configured to upload the Build Scan in the background.

Information about how to configure background uploading for build scans can be found in Configuring background uploading section.

Indicates whether the console log messages generated during the build are captured and displayed in build scans.

Information about how to configure build output capturing for build scans can be found in Capturing build output section.

Indicates whether the build was configured to use Coursier for dependencies resolution.

Coursier is the default dependency resolution library since sbt 1.3.0

Indicates whether the sbt was configured to work without a network connection where possible.

Indicates whether the build was configured to use optional performance optimization features.

Turbo mode is available since sbt 1.3.0.

Indicates whether the build was configured to use parallel tasks execution.

Information about parallel tasks execution can be found in the reference documentation.

Indicates whether the projects in the build were configured to use SemanticDB Scalac plugin.

SemanticDB support is available since sbt 1.3.0.

Indicates whether the build was run from within the sbt shell, or in batch mode.

Information about the sbt interactive mode can be found in the reference documentation.

Every task, test suite and test case has an outcome. For a task, the outcome is either SUCCESS, indicating that the task was successful, or FAILED, which means that at least one test suite has failed.

For test suites, the outcome can be SKIPPED, meaning that the test suite was not executed, SUCCESS, meaning that all test cases were successful, FAILED, indicating that at least one test case was failed, or FLAKY, meaning that at least one test case was successful only after retry.

For test cases, the outcome can be SKIPPED, meaning that the test case was not executed, SUCCESS, meaning that the test case was successful, FAILED indicating that the test case was failed, or FLAKY, meaning that the test case was successful only after retry.

On a task, the total time corresponds to the total amount of wall clock time the task took to execute.

The own time is the time spent setting up the test execution. In other words, it is the time spent executing the task before and after the actual test execution happened. When tests are running in a forked JVM, this duration is unavailable.

The serial time is the sum of the test task own time and its test suites' own times. When tests are running in a forked JVM or any test case run by this task does not report its duration, this duration is unavailable.

On a test suite, the total time corresponds to the total amount of wall clock time the test suite took to execute. The total time is unavailable when tests run in a forked JVM.

The own time is the time spent setting up the test suite. In other words, it is the time spent executing the test suite before and after the test cases executions happened. The own time is unavailable when tests run in a forked JVM or a test case does not report its duration.

The serial time is the sum of the test task own time and its test cases durations. The serial time is unavailable when tests run in a forked JVM or any test case does not report its duration.

On a test case, the total time corresponds to the total amount of wall clock time the test case took to execute. Clicking on a test suite will open the details for this test suite, which will display the results of the test cases which ran as part of this test suite.

Because of how sbt reports test events in case a test suite runs in a forked JVM, it is not possible to accurately report a test suite's total, own and serial durations. Because these durations are missing, the parent test task's own and serial durations are not available either when tests are run in a forked JVM.

Some test frameworks do not report the duration of a test case duration, and Develocity can therefore not show that information on the test results pages. The following test frameworks are known not to report test case durations:

When a test case duration is not reported, the following durations will also not be available in Develocity (because they can’t be computed correctly):

Stores the DevelocityConfiguration.

Publishes the build scan captured by the last build.

Authenticates your build environment with Develocity.

The Develocity sbt plugin does not capture logs generated via the sbt sLog logger (refer to the sbt documentation log messages in a setting for details).

If sLog is used inside a task definition, use streams.value.log.info instead (as suggested by the related sbt documentation) for the log messages to be captured in build scans.

If sLog is used inside a setting definition, no workaround is available.

If log4j usage for internal loggers is enabled via the setting ThisBuild / useLog4J := true, an unexpected javax.management.InstanceAlreadyExistsException may be thrown. This is a known issue that can be ignored.

(sbt version <1.10.0-M1)

If a failure occurs outside of task evaluation (i.e. purely in an sbt command), then the failure will not be registered by Develocity, and the build will not be marked as failed in Develocity.

The workaround is to update to sbt 1.10.0-M1 or later.