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". 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:

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

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

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

Your development infrastructure: OS, JVM, ...

The plugins your build is using, and their versions

The dependencies that you are using, and their versions

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:

Performance metrics and personalised suggestions

Performance metrics for your build with personalised suggestion from Gradle.

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 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 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:

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/