Installing

This will install the executable into ./build/install/gradle-profiler/bin. The examples below assume that you add this location to your PATH or create a gradle-profiler alias for it.

Benchmarking a build

Benchmarking simply records the time it takes to execute your build several times and calculates a mean and standard error for it. It has zero impact on the execution time, so it
is ideal for making before/after comparisons for new Gradle versions or changes to your build.

Where <root-dir-of-build> is the directory containing the build to be benchmarked, and <task> is the name of the task to run,
exactly as you would use for the gradle command.

Results will be written to a file called profile-out/benchmark.html and profile-out/benchmark.csv.

When the profiler runs the build, it will use the tasks you specified. The profiler will use the default
Gradle version, Java installation and JVM args that have been specified for your build, if any.
This generally works the same way as if you were using the Gradle wrapper. For example, the profiler will use the values
from your Gradle wrapper properties file, if present, to determine which Gradle version to run.

You can use the --gradle-version option to specify a Gradle version or installation to use to benchmark the build. You can specify multiple versions
and each of these is used to benchmark the build, allowing you to compare the behaviour of several different Gradle versions.

Profiling a build

Profiling allows you to get deeper insight into the performance of your build.

The app will run the build several times to warm up a daemon, then enable the profiler and run the build.
Once complete, the results are available under profile-out

Gradle build scans

In order to create a build scan of your build, use --profile buildscan. The build scan URL is available in profile-out/profile.log. You can then use the powerful timeline view
in the build scan to analyze which tasks ran, how long they took, how well your build parallelized etc. Also make sure to look at the performance tab to see where time was spent and for hints on how to optimize your build.

JProfiler

In order to work with JProfiler, use the --profile jprofiler option.

This will use JProfiler's CPU sampling by default. JProfiler supports several other options:

Enable CPU sampling of all methods by adding --jprofiler-config sampling-all (by default only packages containing the word gradle are sampled)

Use a specific profiler session (for full control over filters, sampling intervals etc.) by adding --jprofiler-session <sessionId>

use a different JProfiler installation with --jprofiler-home /path/to/jprofiler

YourKit

In order to work with YourKit, make sure YOURKIT_HOME environment variable is set and then use the --profile yourkit option.

This will use YourKit's CPU instrumentation by default. You can switch to CPU sampling by adding the --yourkit-sampling option. You can switch to memory allocation profiling by adding the --yourkit-memory option. All probes are disabled when using sampling or memory allocation profiling.

Java Flight Recorder

In order to profile with JFR, add the --profile jfr option. Note that JFR has a very low sampling frequency compared to other profilers and is unlikely to be helpful for short builds.

Honest Profiler

Install both Honest Profiler and the FlameGraph tool. Then you can run with the options --profile hp --hp-home /path/to/honest/profiler --fg-home /path/to/flamegraph

Honest Profiler currently only works on Linux.

Linux Perf

In order to profile with perf, add the --profile perf option. perf has several advantages over Java agent based profiling:

Accurate and low overhead

All Java processes forked by the build are included

Native stack frames are included

Inlined methods can be optionally unfolded

Prerequisites

Linux Kernel 4.7 or later

perf and cmake. For example:

sudo apt install linux-tools-`uname -r` linux-tools-generic cmake

Set the kernel.perf_event_max_stack Kernel parameter to accommodate deep Java stacks:

The use_pty sudo default option is required when perf is running with sudo in a background process. Without
use_pty, sudo won't relay the kill signal (SIGQUIT)
to the perf process and it won't be possible to stop profiling cleanly.

The profiler automatically downloads and builds the other required tools.

Chrome Trace

Add the --profile chrome-trace option and open the result in Google Chrome. It shows a low-level event dump (e.g. projects being evaluated, tasks being run etc.) together with CPU and memory usage as well as GC activity. Note that using chrome-trace requires Gradle 3.3+.

Command line options

--project-dir: Directory containing the build to run (required).

--benchmark: Benchmark the build. Runs the builds more times and writes the results to a CSV file.

--profile <profiler>: Profile the build using the specified profiler. See above for details on each profiler.

--gradle-version <version>: Specifies a Gradle version or installation to use to run the builds, overriding the default for the build. You can specify multiple versions.

--output-dir <dir>: Directory to write results to.

--no-daemon: Uses the gradle command-line client with the --no-daemon option to run the builds. The default is to use the Gradle tooling API and Gradle daemon.

--cli: Uses the gradle command-line client to run the builds. The default is to use the Gradle tooling API.

-D<key>=<value>: Defines a system property when running the build, overriding the default for the build.

--warmups: Specifies the number of warm-up builds to run for each scenario. Defaults to 2 for profiling, 6 for benchmarking.

--iterations: Specifies the number of builds to run for each scenario. Defaults to 1 for profiling, 10 for benchmarking.

--bazel: Benchmark scenarios using Bazel instead of Gradle. By default, only Gradle scenarios are run. You cannot --profile a Bazel build using this tool.

--buck: Benchmark scenarios using Buck instead of Gradle. By default, only Gradle scenarios are run. You cannot --profile a Buck build using this tool.

--maven: Benchmark scenarios using Maven instead of Gradle. By default, only Gradle scenarios are run. You cannot --profile a Maven build using this tool.

Advanced profiling scenarios

A scenario file can be provided to define more complex scenarios to benchmark or profile. Use the --scenario-file option to provide this. The scenario file is defined in Typesafe config format.

The scenario file defines one or more scenarios. You can select which scenarios to run by specifying its name on the command-line when running gradle-profiler, e.g.