Gradle Profiler for Gradle Build Performance Analysis

Gradle build measurement and profiler selection

Gradle Profiler addresses a specific problem: Gradle builds can become slower because of version changes, build logic, dependency resolution, configuration work, or task execution, but a normal Gradle invocation does not provide a repeatable comparison across several runs. The tool addresses this by recording build execution times and by collecting deeper profiler information. It is intended for developers and build maintainers who work with Gradle builds, especially when they need to compare a proposed change with a baseline.

The tool separates benchmarking from profiling. Benchmarking records how long a selected task takes over several iterations and calculates a mean and standard error. Profiling changes the diagnostic depth. The available integrations include Gradle build scans, Async Profiler, JProfiler, YourKit, Java Flight Recorder, heap dumps in HPROF format, and Chrome Trace output. That range is useful because a timing report and a CPU profile answer different questions. A benchmark can show that a build changed, while a profiler can show where execution time is being spent.

The repository identifies Gradle Profiler as a tool for automating the gathering of profiling and benchmarking information. Its primary language is Java, and its Apache-2.0 license permits use under that license. The repository is not archived, and its last push was on 2026-10-14. The listed releases include v0.26.0, released on 2026-09-29, followed by v0.25.2 and v0.25.1 in July 2026.

Benchmark scenarios, iterations, and result files

A benchmark scenario is created from the Gradle project directory and one or more task names. Gradle Profiler uses the tasks in the same form as a normal Gradle command. During benchmarking, it runs the requested work repeatedly and calculates statistics from the measured samples. The resulting output is written to `profile-out/benchmark.html`, `profile-out/benchmark.csv`, and `profile-out/benchmark.json`.

The JSON file is the most suitable input for custom processing because it contains scenario definitions, measured samples, and the value associated with every iteration. It also includes statistics computed across measured iterations: mean, minimum, P25, median, P75, maximum, and standard deviation. CSV provides a tabular representation of the raw values, while HTML is intended for inspection in a browser.

When several scenarios or Gradle versions are tested, the HTML report can compare a scenario against a selected baseline using the Mann-Whitney U-Test. The report presents the confidence that performance behavior differs, meaning that a scenario is faster or slower. This is statistical comparison rather than a claim that every run will produce the same result. The CSV and JSON files retain raw iteration values, so scripts can apply a different analysis policy.

Gradle version selection and build-operation measurements

Gradle Profiler follows the Gradle settings associated with the build by default. The README states that it generally behaves like the Gradle wrapper. In particular, when a Gradle wrapper properties file is present, its values determine the Gradle version used for the benchmark.

The `--gradle-version` option allows a benchmark to specify a Gradle version or installation. Repeating the option for multiple versions lets the same build be benchmarked across several Gradle versions. This is the central workflow for evaluating whether a build behaves differently after a Gradle upgrade. It also means that the result depends on the build configuration and the selected Gradle distributions, so comparisons should record those inputs.

The `--measure-config-time` option adds configuration-time measurements. For more focused analysis, `--measure-build-op` accepts the fully qualified class name of a type that encloses the `Details` interface. The documented example is `org.gradle.api.internal.tasks.SnapshotTaskInputsBuildOperationType`, which can capture snapshotting time on Gradle 5.x. If a build operation does not exist in a benchmarked Gradle version, it is ignored gracefully and appears in the report with a value of 0. That behavior is useful for multi-version runs, but it also means a zero can mean that the operation was unavailable rather than that it consumed no measurable time.

Build-operation measurements can use `cumulative_time`, `wall_clock_time`, `time_to_last_inclusive`, or `time_to_first_exclusive`. The default is `cumulative_time`. The `--build-ops-trace` option produces a text trace and a Perfetto-compatible `.perfetto.proto` file. The README warns that these formats and their contents may change without notice, so consumers should not treat them as stable interfaces.

Installing Gradle Profiler and running the first benchmark

The README documents installation through SDKMAN!, Homebrew, release binaries, or a source build. On Unix-like systems, SDKMAN! installs the executable as `gradle-profiler`. Homebrew provides a similar package command. Release binaries are linked from the repository releases page.

For a source build, Java 11 or later is required. The default install location is `./distribution/gradle-profiler/bin`, so that directory must be added to `PATH`, or the executable must be exposed through a `gradle-profiler` alias. A different destination can be selected with the `gradle-profiler.install.dir` property.

The following commands build and install the application at the documented default location:

./gradlew install

After installation, the first useful operation is to check the benchmark help. The README gives this command for SDKMAN! and Homebrew installations:

gradle-profiler --benchmark help

To benchmark a real build, pass the directory containing the build and the task names exactly as they would be passed to Gradle:

gradle-profiler --benchmark --project-dir <root-dir-of-build> <task>...

Replace the placeholders with the actual build directory and task names. The command writes the benchmark report files under `profile-out/`, so inspect those files after the run. The task names must identify work that can be repeated under comparable conditions.

Profiling runs, flame graphs, and output limits

A profiling run uses the `--profile` option, the profiler name, the project directory, and one or more Gradle tasks. Gradle Profiler runs the build several times to warm a daemon before enabling the profiler and running the measured build. Results are written under `profile-out/`.

Async Profiler and Java Flight Recorder also produce flame graphs for each scenario. If multiple scenarios or versions are profiled, differential flame graphs are produced as well. That output can help narrow a regression, but the README does not document a stable command-line contract for every profiler-specific option, so the available profiler name and its configuration should be checked against the project documentation before adding flags.

The tool also supports Gradle build scans and Chrome Trace output. Build scans are a different reporting route from local profiler files: the README links them to the Gradle build scan service, while Chrome Trace output is intended for trace viewing. The repository does not state how authentication, data retention, or external services affect these choices. This matters for teams handling private build information.

Another limitation is that Gradle Profiler measures Gradle builds. It is not a general-purpose application benchmark runner, and the documented workflow does not remove nondeterminism from the build itself. Network access, filesystem state, daemon reuse, dependency caches, and task inputs can still affect iteration values. Repeating a benchmark can establish a comparison, but the report does not by itself prove why a difference occurred.

Gradle Profiler versus Gradle build scans and direct tooling

The closest alternatives come from the individual tools that Gradle Profiler can coordinate. Gradle build scans are one supported route for gathering profiling information, while Gradle Profiler can be used as a local command-line harness for repeated timing and profiler runs. A build scan is therefore a natural choice when the team wants Gradle's scan-oriented reporting, while Gradle Profiler is more directly aligned with scripted before-and-after measurements and local output files.

Async Profiler, JProfiler, YourKit, and Java Flight Recorder each provide profiler-specific capabilities. Gradle Profiler's value here is orchestration: it runs the selected Gradle build, activates a supported profiler, and places results under `profile-out/`. It does not turn every profiler into the same kind of report. Async Profiler and JFR have documented flame-graph behavior in this project; the README does not claim equivalent flame-graph output for every supported profiler.

Compared with invoking a profiler manually, Gradle Profiler adds build-aware setup and report generation. Compared with a build scan, it emphasizes repeatable local benchmarks and explicit output files. The choice depends on whether the primary question is build-time regression analysis, Gradle-hosted diagnostics, or direct use of a particular JVM profiler.

Maintenance, upgrades, and Apache-2.0 implications

The repository is not archived, and its last push was on 2026-10-14. Recent releases include v0.26.0 on 2026-09-29 and two v0.25.x releases on 2026-07-10. This indicates recent repository activity, but the README does not define a release compatibility policy for Gradle versions, Java versions beyond the Java 11 build requirement, or profiler integrations.

Upgrades may affect output files and automation because the README explicitly warns that the build-operations trace formats and contents may change without notice. The HTML, CSV, and JSON benchmark artifacts are documented, but the documentation does not promise that every report field will remain unchanged. Teams with scripts should treat generated files as versioned interfaces and review changes when upgrading `gradle-profiler`.

The project uses the Apache-2.0 license. That identifies the repository's licensing basis, but it does not by itself answer questions about redistribution of reports, external profiler data, Gradle build scans, or dependencies. Those issues need separate review rather than assumptions based only on the repository license.

Editorial conclusion

Adopt Gradle Profiler when you need repeatable Gradle build timings or profiler data across one or more Gradle versions. Do not choose it when a single ordinary build log is sufficient, or when the underlying build is not a Gradle build. Verify first that the requested profiler, Java installation, Gradle version selection, and output formats work with your build and your analysis workflow.

Frequently asked questions

Official sources

1. gradle/gradle-profiler on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases