Beta Feature
This guide covers how to get started with Develocity, with topics such as strategies for incrementally introducing Build Scan® usage, and key Build Scan features for improving your development productivity.
Develocity provides Build Scan, a permanent and shareable record of an executed build that allows collaborative troubleshooting and optimization.
|
npm support is not enabled by default with Develocity. If you wish to use npm with Develocity, please contact your customer success representative. |
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 npm agent
To use Build Scans, you must apply the Develocity npm agent to your project.
Setup
Install the agent
The Develocity npm agent is an npm package, but it is not publicly available on the npm registry. To install it in your project, you can use the command line below.
npm install --save-dev https://develocity-npm-pkgs.gradle.com/gradle-develocity-agent-0.10.0.tgzPrepare the agent for use
The agent is a regular Node.js module. In order for it to instrument npm invocations, it needs to be preloaded, using the -r option of Node.js. In order for this flag to be passed to the npm process, it needs to be set in the NODE_OPTIONS environment variable.
While using this mechanism to load the agent directly is possible, it requires the NODE_OPTIONS environment variable to be set and unset manually depending on the availability of the agent in the project (or in the system at large for that matter, since NODE_OPTIONS applies to any Node.js process).
As this can be tedious, error-prone, and lead to unexpected failures, we recommend using the agent loader to set NODE_OPTIONS once and never have to worry about it again.
Recommended: using the agent loader
The agent loader is a small package whose sole purpose is to load the agent if it’s currently available in the project, or silently ignore if it’s not.
To install it, use the command line below.
npm install --global https://develocity-npm-pkgs.gradle.com/gradle-develocity-agent-loader-0.9.0.tgzTo ensure that the agent is preloaded, set the NODE_OPTIONS environment variable as follows:
export NODE_OPTIONS="-r $(npm root -g)/@gradle/develocity-agent-loader"From now on, the agent will be automatically preloaded if it has been installed for the current project.
|
By default, the agent loader will simply ignore any error in loading the agent (which usually simply means that the agent itself is not installed for the current project). If you expect the agent to be loaded, but it’s not, you can set the |
Alternatively: managing NODE_OPTIONS manually
There are situations, such as CI, where managing NODE_OPTIONS manually is just as convenient as depending on the agent loader as a global package. In these cases, or if for other reasons you cannot use the agent loader, you can load the agent directly.
To ensure that the agent is preloaded, use the NODE_OPTIONS environment variable as such:
export NODE_OPTIONS='-r @gradle/develocity-agent/preload'Note that the agent will be preloaded for all invocations of Node.js. This can be inconvenient when working on local development environments, as NODE_OPTIONS needs to be set and unset depending on the availability of the agent in the project to avoid invocations of Node.js to fail. If you are in a situation where using the agent loader is unfeasible and need to manage NODE_OPTIONS manually, you might want to consider tooling to do that for you, such as dotenvx or direnv.
Configuration
To configure the agent, create a file called develocity.config.js or develocity.config.cjs in the root of your project.
module.exports = {
server: {
url: 'https://develocity.mycompany.com',
},
}| Configuration files using ESM or TypeScript are not supported. |
This is the minimum configuration required to publish a Build Scan. Publishing a Build Scan to scans.gradle.com is not supported.
Alternatively, you can use environment variables to configure the agent. Use DEVELOCITY_URL to set the Develocity server URL:
export DEVELOCITY_URL=https://develocity.mycompany.com|
You might 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 recognize that you may not be able to do that. In this case, set the module.exports = {
server: {
url: 'https://develocity.mycompany.com',
allowUntrustedServer: true,
},
}
Alternatively, you can set the This is a convenient workaround, but you shouldn’t use it as a long-term solution. |
More detailed information about the Develocity npm agent can be found in the Develocity npm agent 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 npm agent. 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, username, 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 might 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 console log
The console log will be included in your Build Scan. Use the left navigation menu to visit the Console Log section.
This section will display all the console log emitted by the instrumented npm process, as well as any process it spawned to perform some particular task (in the example above, npm test ran jest).
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 process, test file and test. Select any test file or test to see details about each of their individual executions, in case of test retry. The total time is available for processes, test files and tests. Generally, it corresponds to the wall clock time that an execution lasted. Please refer to Viewing test results for more details.
Next steps
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 (for example,
CIvs.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 Develocity npm agent will not cause build failures, even when there is no connection available to the Develocity server when trying to publish.
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 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.
Integrating with Gradle
If you run npm through a Gradle task, you might want to use the convenience API we offer through the Gradle Develocity plugin.
Learn more in the Develocity npm agent user manual.