Use the Gradle build-scan!
Tags: android, kotlin, gradle
Published: 2019-09-22 06:45:19

# Use the Gradle Build-Scan!

There is one very sad problem in the Android world that has a good and simple solution, so if you are an Android developer or are otherwise using Gradle as your build tools, please pay attention!

## The problem: lost context

Let's imagine you arrive to work in the morning. A notification pop-up:

> *Application not working*
> Hello dear developer. One customer has reported that the application is not working since yersterday. *Please fix it ASAP*. 

My wild guess is that you would react along those lines

> Excuse me?
> What is not working? Is that a crash? Do you have a stacktrace?
> Or is something not working as expected? And why? Which version of the app? On which smartphone?
> Do you have reproducing steps?

## This is Reporting 101. 

Yet somehow we forget it when it comes to our builds.

Those context-free "bug reports" and tips are everywhere. I am sad when I look at StackOverflow questions  [tagged with "gradle, android"](https://stackoverflow.com/questions/tagged/gradle%2bandroid?tab=Active). I am sad when I read issues in the android issue tracker. I am sad when I read all those Medium posts. Everywhere the same pattern:

> (original_post) Hello, my build is slow / not working, please advice.
> (original_post) Here are 2.000 probably irrelevant lines that I copy/pasted from my build.
> > (answer1) Copy/paste this Groovy snippet somewhere in your builds. I don't understand what it does, but that should solve your problem.
> > > (answer2) No, that doesn't work.

Those context-less conversation are infuriating. The good news is that there is a good, simple answer for this!

## The solution: a Gradle Build-Scan URL

Everytime you need to understand why your build is failing and ask for help, re-run the Gradle task that was failing with `--scan`. For example:
 

{% gist https://gist.github.com/jmfayard/a50cd5a24f75d730d88d0a3afdeff539 %}

To make it more convenient, you should add this setup at in your top `./build.gradle` file.

{% gist https://gist.github.com/jmfayard/2c498e2e1631c93915421fc5041f78a4 %}

You will find `$VERSION` at https://plugins.gradle.org/plugin/com.gradle.build-scan

## What does that bring us?

Everything.

Explore by yourself at https://scans.gradle.com/s/ug6vfggccmozm/

Or continue reading.

## The timeline of tasks execution

![image](https://user-images.githubusercontent.com/459464/65383112-709c0880-dd10-11e9-8ab0-131c9153c143.png)

If your build fails, the stacktrace will be available as well.

## Your development infrastructure: OS, JVM, ...

![image](https://user-images.githubusercontent.com/459464/65383046-4ac23400-dd0f-11e9-8020-fb5b9838a3ad.png)

## The plugins your build is using, and their versions

![image](https://user-images.githubusercontent.com/459464/65383061-8230e080-dd0f-11e9-8d16-e6361e6dfdd3.png)

## The dependencies that you are using, and their versions

![image](https://user-images.githubusercontent.com/459464/65383071-a987ad80-dd0f-11e9-99a2-d13d0812fc25.png)


## Your failing tests

Don't try anymore to decipher in your Jenkins log why your tests are failing. The Gradle Build Scan also reports which tests are failing and why:

![image](https://user-images.githubusercontent.com/459464/65383092-2450c880-dd10-11e9-9a09-9fdcdf6fd663.png)

## Performance metrics and personalised suggestions

Performance metrics for **your** build with personalised suggestion from Gradle.

![image](https://user-images.githubusercontent.com/459464/65383101-48140e80-dd10-11e9-9559-0443bf077bec.png)

Read along its companion manual
https://scans.gradle.com/s/ug6vfggccmozm/performance/build


## This is awesome! Why didn't I know this before?

Some would answer: "Because you didn't RTFM?".

But what I find interesting about [RTFM](https://en.wikipedia.org/wiki/RTFM) is that it has two, quite different meanings: **Read The Fucking Manual** and **Read The Friendly Manual**. 

The ["Configure your build" section on the Android official website](https://developer.android.com/studio/build?hl=en) is really terrible and I'm not surprised you didn't know about the Gradle Build Scan if that is what you rely on.

And that's perhaps the best part of using the Gradle Build Scan: it provides direct links to the relevant parts of the official documentation from Gradle which are more of the *Friendly Manual* kind. 

For example: 
![image](https://user-images.githubusercontent.com/459464/65383309-fb323700-dd13-11e9-8ab7-e109cd7d9979.png)

See it yourself: https://scans.gradle.com/s/ug6vfggccmozm#switches

## Update: Setting it up with Gradle 6

If you have updated to Gradle 6, there are some changes!

The `build-scan` plugin is now called the Gradle Enterprise plugin.
And it must now be configured in the `settings.gradle` or `settings.gradle.kts` file. 


```
// https://dev.to/jmfayard/the-one-gradle-trick-that-supersedes-all-the-others-5bpg
// Find VERSION at https://plugins.gradle.org/plugin/com.gradle.enterprise
plugins {
   id("com.gradle.enterprise").version(VERSION) 
}

gradleEnterprise {
    buildScan {
        // Accept the license agreement for com.gradle.build-scan plugin
        termsOfServiceUrl = "https://gradle.com/terms-of-service"
        termsOfServiceAgree = "yes"
        publishOnFailure()
    }
}
```

## Reference

- Creating Build Scans https://guides.gradle.org/creating-build-scans/
- Improving the Performance of Gradle builds https://guides.gradle.org/performance/
- The Build Scan user manual explain among other things how to publish the Build Scans on a company server: https://docs.gradle.com/build-scan-plugin/