gradle/gradle-profiler

Gradle Profiler

A tool to automate the gathering of profiling and benchmarking information for Gradle builds.

Profiling information can be captured using several different tools:

• Using Gradle build scans
• Using Async Profiler
• Using JProfiler
• Using YourKit profiler
• Using Java flight recorder
• Producing a heap dump in HPROF format
• Producing Chrome Trace output

Installing

SDKMAN!

SDKMAN! is a tool for managing parallel versions of multiple Software Development Kits on most Unix-based systems.

> sdk install gradleprofiler
> gradle-profiler --benchmark help

Homebrew

Homebrew is the easiest and most flexible way to install the UNIX tools Apple didn’t include with macOS.

> brew install gradle-profiler
> gradle-profiler --benchmark help

Download binaries

Binaries are available and linked from the releases page.

Build from source

First, build and install the gradle-profiler app using:

> ./gradlew install

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

NOTE: You have to use Java 11 or later to build this project.

You can choose a different installation location by providing the gradle-profiler.install.dir property. E.g. ./gradlew install -Pgradle-profiler.install.dir=/usr/local/bin.

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.

Run the gradle-profiler app using:

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

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 files called profile-out/benchmark.html, profile-out/benchmark.csv and profile-out/benchmark.json. The JSON file contains the scenario definitions, the measured samples and the value of each sample for every iteration, so it can be parsed by custom tooling. For each sample it also contains statistics computed over the measured iterations (mean, min, P25, median, P75, max and standard deviation).

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.

You can also use the --measure-config-time option to measure some additional details about configuration time.

You can use --measure-build-op together with the fully qualified class name of the enveloping type of the Details interface to benchmark cumulative build operation time. For example, for Gradle 5.x there is a org.gradle.api.internal.tasks.SnapshotTaskInputsBuildOperationType which can be used to capture snapshotting time. If the build operation does not exists in a benchmarked version of Gradle, it is gracefully ignored. In the resulting reports it will show up with 0 time. You can specify different measurements to take by adding :<measurement kind> after the build operation name, e.g. --measure-build-op SomeType:time_to_last_inclusive. The default measurement kind is cumulative_time. The available measurement kinds are:

• cumulative_time: the cumulative time spent in the build operation, which may be greater than the wall clock time if there are concurrent executions of the build operation type
• wall_clock_time: the wall clock time spent in the build operation, which measures time when one or more executions of the build operation type are running, not the sum of the durations of the individual executions
• time_to_last_inclusive: the time from the start of the build until the maximum end time of any execution of the build operation type
• time_to_first_exclusive: the time from the start of the build until the minimum start time of any execution of the build operation type Multiple different measurement kinds can be specified for the same build operation type by repeating the option, e.g. --measure-build-op SomeType:cumulative_time --measure-build-op SomeType:time_to_last_inclusive.

You can use --build-ops-trace to produce a full Gradle build operations trace. This produces <scenario-name>-log.txt textual build operations log and a <scenario-name>.perfetto.proto that can be viewed via Perfetto UI. Note that the formats and contents are not stable and may change in the future without any notice.

Regression detection

If multiple scenarios or versions are tested, the HTML report can show the confidence that a scenario has a different performance behavior — i.e. it is faster or slower — than a baseline scenario selected in the report, using a Mann-Whitney U-Test. The CSV and JSON files contain the raw iteration values, from which such comparisons can be computed.

Profiling a build

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

To run the gradle-profiler app to profile a build use:

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

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/.

If you use Async profiler or JFR for profiling, Gradle profiler will also create flame graphs for each scenario. If you profile multiple scenarios or multiple versions, then Gradle profiler will create differential flame graphs as well.

Gradle build scans

Gradle build scans are a powerful tool to investigate the structure of your build and quickly find bottlenecks. You can use the timeline view to see which tasks ran, how long they took, whether they were cached, how well your build parallelized etc. The performance tab will show you details about configuration time and other hints on how to make your build faster.

In order to create a build scan of your build, use --profile buildscan. The build scan URL is reported on the console and is also available in profile-out/profile.log.

Async Profiler

Async profiler provides low-overhead CPU, allocation and perf event sampling on Linux and MacOS. It also correctly handles native method calls, making it preferable to JFR on these operating systems.

You can use async profiler to profile a Gradle build using --profile async-profiler. By default, this will profile CPU usage, with some reasonable default settings. These settings can be configured using various command-line options, listed below.

Alternatively, you can also use --profile async-profiler-heap to profile heap allocations, with some reasonable default settings.

Or, you can also use --profile async-profiler-wall to profile wall allocations, with some reasonable default settings. On Linux this option will also profile cpu events.

Finally, you can also use --profile async-profiler-all to profile cpu, heap allocations, and locks with some reasonable default settings. On Linux this option will also profile wall events.

By default, an Async profiler release will be downloaded from Github and installed, if not already available.

The outputs are flame and icicle graphs which show you the call tree and hotspots of your code.

The following options are supported and closely mimic the options of Async profiler. Have a look at its readme to find out more about each option:

• --async-profiler-event: The event to sample, e.g. cpu, wall, lock or alloc. Defaults to cpu. Multiple events can be profiled by using this parameter multiple times.
• --async-profiler-count: The count to use when aggregating event data. Either samples or total. total is especially useful for allocation profiling. Defaults to samples. Corresponds to the --samples and --total command line options for Async profiler.
• --async-profiler-interval: The sampling interval in ns, defaults to 10_000_000 (10 ms).
• --async-profiler-alloc-interval: The sampling interval in bytes for allocation profiling, defaults to 10 bytes. Corresponds to the --alloc command line option for Async profiler.
• --async-profiler-lock-threshold: Lock profiling threshold in nanoseconds, defaults to 250 microseconds. Corresponds to the --lock command line option for Async profiler.
• --async-profiler-wall-interval: Wall clock profiling interval in nanoseconds. Defaults to 10_000_000 (10 ms).
• --async-profiler-stackdepth: The maximum stack depth. Lower this if profiles with deep recursion get too large. Defaults to 2048.
• --async-profiler-system-threads: Whether to show system threads like GC and JIT compilation in the profile. Usually makes them harder to read, but can be useful if you suspect problems in that area. Defaults to false.

You can also use either the ASYNC_PROFILER_HOME environment variable or the --async-profiler-home command line option to point to the Async profiler install directory.

JProfiler

JProfiler is a powerful commercial profiler, which provides both sampling and instrumentation capabilities. You can tailor its settings in the JProfiler UI and then instruct the Gradle profiler to use these settings for full control over what you want to investigate. For instance, you could split calls to a dependency resolution rule by argument to find out if the rule is slow for a specific dependency.

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)
• Switch to CPU instrumentation by adding --jprofiler-config instrumentation
• Enable memory allocation recording by adding --jprofiler-alloc
• Enable monitor usage recording by adding --jprofiler-monitors
• Enable probes with --jprofiler-probes:<probe ids, separated by comma> (e.g. --jprofiler-probes builtin.FileProbe)
• Enable heapdump after build with --jprofiler-heapdump
• 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

YourKit is a powerful commercial profiler, which provides both sampling and instrumentation capabilities. Its integration in the Gradle profiler is currently limited, e.g. support for probes and other custom settings is missing. If you are using YourKit and would like to see better support, pull requests are welcome.

In order to work with YourKit, make sure the YOURKIT_HOME environment variable is set and then use the --profile yourkit option. This will use YourKit's CPU sampling instrumentation by default.

You can switch to CPU tracing using the --profile yourkit-tracing option. You can switch to memory allocation profiling by using the --profile yourkit-heap option. All probes are disabled when using sampling or memory allocation profiling.

By default, YourKit will use the 10021 port to connect to the agent in the build JVM. You can override it via org.gradle.profiler.yourkit.port system property.

Java Flight Recorder

JFR provides low overhead CPU, allocation, IO wait and lock profiling and runs on all major operating systems. It is available on Oracle JDK since Java 7 and on OpenJDK since Java 11 (make sure you have at least 11.0.3).

To our knowledge, it is the only low-overhead allocation profiler for Windows. However, be aware of its shortcomings, e.g. it will not sample native method calls, so you will get misleading CPU results if your code does a lot of system calls (like reading files).

You will get both the JFR file and flame graph visualizations of the data, which are much easier to understand than the Java Mission Control UI.

In order to profile with JFR, add the --profile jfr option. You can change the profiler settings using --jfr-settings, specifying either the path to a .jfc file or the name of a built-in template like profile.

Heap dump

To capture a heap dump at the end of each measured build, add the --profile heap-dump option. You can use this with other --profile options.

Chrome Trace

Chrome traces are a low-level event dump (e.g. projects being evaluated, tasks being run etc.). They are useful when you can't create a build scan, but need to look at the overall structure of a build. It also displays CPU load, memory usage and GC activity. Using chrome-trace requires Gradle 3.3+.

Add the --profile chrome-trace option and open the result in Google Chrome in chrome://tracing.

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.
• --output-dir <dir>: Directory to write results to. Default value is profile-out. If the profile-out directory already exists, it tries to find a profile-out-<index> directory that does not exist.
• --csv-format <format>: Format of the CSV output file. Values: wide (default) or long. The wide format produces a matrix with scenarios as columns. The long format produces one row per iteration/sample, which is more suitable for concatenating multiple benchmark results together.
• --single-shot: Run a single measured build with zero warm-ups. Implies --cold-daemon, but can be combined with --no-daemon. Cannot be used together with --warmups or --iterations.
• --warmups: Specifies the number of warm-up builds to run for each scenario. Defaults to 2 for profiling, 6 for benchmarking, and 1 when not using a warm daemon. Use --single-shot for zero warm-ups.
• --iterations: Specifies the number of builds to run for each scenario. Defaults to 1 for profiling, 10 for benchmarking.
• --group <group-name>: Run scenarios from the specified scenario group.
• --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.

The following command line options only apply when measuring Gradle builds:

• --gradle-user-home: The Gradle user home. Defaults to <project-dir>/gradle-user-home to isolate performance tests from your other builds.
• --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 by using this option once for each version.
• --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. The build runs in a single-use process forked by the client; jvm-args, system-properties and profiler JVM arguments apply to that process, not to the client. When profiling, the profiler stops recording that process at the end of each build, before the client receives the build result, so the time to write the profiler output is included in the measured build time. With --dry-run, the build runs no tasks and cannot notify the profiler, so the profiler does not record that process and produces no output.
• --cold-daemon: Use a cold daemon (one that has just started) rather than a warm daemon (one that has already run some builds). The default is to use a warm daemon.
• --cli: Uses the gradle command-line client to run the builds. The default is to use the Gradle tooling API and Gradle daemon.
• --build-ops-trace: Produce a build operations trace: raw textual log <scenario-name>-log.txt and <scenario-name>.perfetto.proto Perfetto trace. Note that the formats and contents are not stable and may change in the future without any notice.
• --measure-build-op: Additionally measure timing information about the given build operation. Only supported for Gradle 6.1 and later.
• --measure-config-time: Measure some additional details about configuration time. Only supported for Gradle 6.1 and later.
• --measure-gc: Measure the garbage collection time. Only supported for Gradle 6.1 and later.
• --measure-local-build-cache: Measure the size of the local build cache.
• -D<key>=<value>: Defines a system property when running the build, overriding the default for the build.
• --idea-install-dir, --idea-sandbox-dir, --no-idea-sandbox, --studio-install-dir, --studio-sandbox-dir, --no-studio-sandbox: IDE-sync-related options — see IDE sync support.
• --no-diffs: Do not generate differential flame graphs.

JVM requirements and options

Gradle Profiler itself is a JVM application. It requires Java 17 or later to run.

Gradle Profiler is itself a relatively lightweight app, as it mostly requires coordinating builds and processing the collected results at the end. To benchmark or profile builds, it always starts a separate build process or IDE process.

Configuring JVM for target Gradle builds

By default, Gradle Profiler starts a Gradle daemon for your build using the same JVM installation that was used to run it. In case your build requires an earlier version of the JVM or you require a specific JVM, you can configure it explicitly in your build.

For Gradle 8.13 and later, the recommended approach is to configure the Daemon JVM. However, it might require some additional setup in your build. You can follow the instructions in the linked documentation. Daemon JVM configuration can be checked into your VCS to make sure everyone on your team uses the same JVM version.

A more ad hoc solution for benchmarking or profiling purposes is to specify the org.gradle.java.home property in the gradle.properties file in the root directory of your build.

# gradle.properties
org.gradle.java.home=<path to a Java installation>

It will be respected when starting the daemon for your build, regardless of the JVM Gradle Profiler uses.

Configuring JVM running Gradle Profiler itself

Gradle Profiler is packaged via the standard application plugin.

In a rare case when you need to change the parameters of the Gradle Profiler JVM, you can use the GRADLE_PROFILER_OPTS. For instance, you can increase the heap size by setting GRADLE_PROFILER_OPTS=-Xmx4g. Note that this setting will not affect the target builds, which you are benchmarking or profiling.

Gradle version compatibility

Gradle Profiler supports benchmarking and profiling builds with Gradle 6.0 or later.

Gradle Profiler is tested against the latest patch releases of Gradle 6.x through 9.x.

If you require running your build with a specific Java version for the Gradle Daemon JVM, which is different from the JVM used to run Gradle Profiler, see the JVM requirements and option section for details.

If you require running Gradle Profiler for builds that use Gradle 5.x, consider using previous versions of Gradle Profiler. The last version that officially supports Gradle 5.x is Gradle Profiler 0.23.0.

IDE sync support

Gradle Profiler can benchmark Gradle sync performed by IntelliJ-based IDEs. This is useful for measuring and optimizing the IDE experience when opening or refreshing Gradle projects.

Supported IDEs

• IntelliJ IDEA 2026.1 or newer
• Android Studio Quail (2026.1) or newer

Both IDEs are based on the IntelliJ platform. The profiler installs a lightweight plugin into the IDE that controls the sync lifecycle and communicates results back to the profiler.

Command-line options

• --idea-install-dir: The IntelliJ IDEA installation directory. Required when measuring an idea-sync scenario. On macOS, it is the app directory, e.g. ~/Applications/IntelliJ IDEA.app.
• --idea-sandbox-dir: The IntelliJ IDEA sandbox directory. It's recommended to use it since it isolates the IDE process from your other IDE processes. By default, this is set to <output-dir>/idea-sandbox. If you want the IDE to keep old data (e.g. indexes), set and reuse your own folder.
• --no-idea-sandbox: Do not use the IntelliJ IDEA sandbox; instead use the default IDE folders for the IDE data.
• --studio-install-dir: The Android Studio installation directory. Required when measuring an studio-sync scenario. On macOS, it is the app directory, e.g. ~/Applications/Android Studio.app.
• --studio-sandbox-dir: The Android Studio sandbox directory. By default, this is set to <output-dir>/studio-sandbox.
• --no-studio-sandbox: Do not use the Android Studio sandbox; instead use the default IDE folders for the IDE data.

Scenario file blocks

Inside an idea-sync or studio-sync block:

• ide-jvm-args: JVM arguments for the IDE process. Defaults to ["-Xms256m", "-Xmx4096m"].
• idea-properties: Additional entries to write to the IDE's idea.properties file. Useful for setting registry values.

To invalidate IDE caches between runs, use the scenario-level clear-ide-cache-before key.

For Android Studio, swap --idea-install-dir for --studio-install-dir and use the matching scenario block:

myIdeaSync {
    idea-sync {
        ide-jvm-args = ["-Xms256m", "-Xmx4096m"]
    }
}

myStudioSync {
    studio-sync {
        ide-jvm-args = ["-Xms256m", "-Xmx4096m"]
    }
}

[!NOTE] For Android Studio projects, make sure a local.properties file exists with sdk.dir pointing to your Android SDK.

Deprecated options

The following options are still accepted but deprecated. A warning will be printed when they are used:

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 HOCON 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.

> gradle-profiler --benchmark --scenario-file performance.scenarios clean_build

Here is an example:

# Can specify scenarios to use when none are specified on the command line
default-scenarios = ["assemble"]

# Scenarios are run in alphabetical order
assemble {
    # Show a slightly more human-readable title in reports
    title = "Assemble"
    # Run the 'assemble' task
    tasks = ["assemble"]
}
clean_build {
    title = "Clean Build"
    versions = ["3.1", "/Users/me/gradle"]
    tasks = ["build"]
    gradle-args = ["--parallel"]
    system-properties {
        "key" = "value"
    }
    cleanup-tasks = ["clean"]
    run-using = tooling-api // value can be "cli" or "tooling-api"
    daemon = warm // value can be "warm", "cold", or "none"
    build-ops-trace = true // produce full Gradle build operations trace
    measured-build-ops = ["org.gradle.api.internal.tasks.SnapshotTaskInputsBuildOperationType"] // see --measure-build-op
    // To specify the measurement kind, use an object instead of a string:
    measured-build-ops = [
        {
            type = "org.gradle.api.internal.tasks.SnapshotTaskInputsBuildOperationType"
            measurement-kind = time_to_last_inclusive
        }
    ]

    buck {
        targets = ["//thing/res_debug"]
        type = "android_binary" // can be a Buck build rule type or "all"
    }

    warm-ups = 10
}
ideaModel {
    title = "IDEA model"
    # Fetch the IDEA tooling model
    tooling-api {
        model = "org.gradle.tooling.model.idea.IdeaProject"
    }
    # Can also run tasks
    # tasks = ["assemble"]
}
toolingAction {
    title = "IDEA model"
    # Fetch the IDEA tooling model
    tooling-api {
        action = "org.gradle.profiler.toolingapi.FetchProjectPublications"
    }
    # Can also run tasks
    # tasks = ["assemble"]
}
# For IDE-sync scenarios (`idea-sync` / `studio-sync`), see IDE sync support section.

Values are optional and default to the values provided on the command-line or defined in the build.

Task options must be specified as separate items in the tasks array, because each item is passed as a separate command-line argument to Gradle:

task_params {
    title = "Task params"
    tasks = [":app:testDebugUnitTest", "--tests", "com.example.MyTest"]
}

Gradle command-line options that are not task-specific should be specified with gradle-args:

continue_build {
    title = "Continue build"
    tasks = ["test"]
    gradle-args = ["--continue"]
}

Scenario groups

You can organize scenarios into groups to run related scenarios together. Define groups using the scenario-groups top-level element:

scenario-groups {
    smoke-tests = ["assemble", "clean_build"]
    performance-suite = ["incremental_build", "full_build", "no_op"]
}

assemble {
    tasks = ["assemble"]
}

clean_build {
    cleanup-tasks = ["clean"]
    tasks = ["build"]
}

# ... definition of other scenarios ...

To run scenarios from a specific group:

> gradle-profiler --benchmark --scenario-file performance.scenarios --group smoke-tests

This will run only the scenarios defined in the smoke-tests group (assemble and clean_build).

Benchmark options

• iterations: Number of builds to actually measure
• warm-ups: Number of warmups to perform before measurement
• jvm-args: Sets or overrides the jvm arguments set by org.gradle.jvmargs in gradle.properties.
• build-ops-trace: When set to true, produces a build operations trace: raw textual log <scenario-name>-log.txt and <scenario-name>.perfetto.proto Perfetto trace. Note that the formats and contents are not stable and may change in the future without any notice.

Profiling change handling

How a build tool handles changes to the source code can have a significant impact on the performance of the build. Gradle Profiler can simulate different kinds of changes to the source code to measure the impact of these changes on the build performance. These changes are applied by mutators at different points in the build benchmark process. Some mutators execute at a specific point, others can be configured to execute at a specific point, specified by the schedule parameter:

• SCENARIO: before the scenario is executed,
• CLEANUP: before cleaning preceding each build invocation,
• BUILD: before the build invocation (after cleanup).

Source code mutators

These mutations are applied before each build, and they introduce different kinds of change to the source code.

• apply-abi-change-to: Add a public method to a Java or Kotlin source class. Each iteration adds a new method and removes the method added by the previous iteration.
• apply-android-layout-change-to: Add a hidden view with id to an Android layout file. Supports traditional layouts as well as Databinding layouts with a ViewGroup as the root element.
• apply-android-manifest-change-to: Add a permission to an Android manifest file.
• apply-android-resource-change-to: Add a string resource to an Android resource file. Each iteration adds a new resource and removes the resource added by the previous iteration.
• apply-android-resource-value-change-to: Change a string resource in an Android resource file.
• apply-build-script-change-to: Add a statement to a Groovy or Kotlin DSL build script, init script or settings script. Each iteration adds a new statement and removes the statement added by the previous iteration.
• apply-cpp-change-to: Add a function to a C/C++ source file. Each iteration adds a new function and removes the function added by the previous iteration.
• apply-h-change-to: Add a function to a C/C++ header file. Each iteration adds a new function declaration and removes the function added by the previous iteration.
• apply-kotlin-composable-change-to: Add a @Composable function to a Kotlin source file.
• apply-non-abi-change-to: Change the body of a public method in a Java or Kotlin source class.
• apply-project-dependency-change-to: Add project dependencies to a Groovy or a Kotlin DSL build script. Each iteration adds a new combination of projects as dependencies and removes the projects added by the previous iteration.
• apply-property-resource-change-to: Add an entry to a properties file. Each iteration adds a new entry and removes the entry added by the previous iteration.

Cache cleanup

When simulating scenarios like ephemeral builds, it is important to make sure caches are not present. These mutators can be scheduled to execute at different points in the build benchmark process, specified by the schedule parameter.

• clear-ide-cache-before: Invalidates the IDE caches. Scheduling to run before cleanup (CLEANUP) is not supported. Only applies to IDE sync scenarios (see IDE sync support). The deprecated alias clear-android-studio-cache-before is still accepted and prints a warning.
• clear-build-cache-before: Deletes the contents of the build cache at the given schedule.
• clear-configuration-cache-state-before: Deletes the contents of the .gradle/configuration-cache-state directory.
• clear-gradle-user-home-before: Deletes the contents of the Gradle user home directory. The mutator retains the wrapper cache in the Gradle user home, since the downloaded wrapper in that location is used to run Gradle. Requires to use the none daemon option to use with CLEANUP or BUILD schedules.
• clear-jars-cache-before: Deletes the contents of the instrumented jars cache.
• clear-project-cache-before: Deletes the contents of the .gradle and buildSrc/.gradle project cache directories.
• clear-transform-cache-before: Deletes the contents of the transform cache.
• show-build-cache-size: Shows the number of files and their size in the build cache before scenario execution, and after each cleanup and build round.

File operations

• copy-file: Copies a file or a directory from one location to another. Has to specify a source and a target path; when relative they are resolved against the directory specified by root (see below). Can take an array of operations. Defaults to SCENARIO schedule.
• clear-dir: Clears the contents of a directory without deleting the directory itself. Has to specify a target path; when relative it is resolved against the directory specified by root (see below). Optionally accepts a keep list of names, which are direct children of target and which will not be deleted. Can take an array of operations. Defaults to SCENARIO schedule.
• delete-file: Deletes a file or a directory. Has to specify a target path; when relative it is resolved against the directory specified by root (see below). Can take an array of operations. Defaults to SCENARIO schedule.
• git-checkout: Checks out a specific commit for the build step, and a different one for the cleanup step.
• git-revert: Reverts a given set of commits before the build and resets it afterward.

The git-checkout and git-revert mutators refuse to start when tracked files have staged or unstaged changes, so profiling never discards local work. Commit or stash those changes before running the scenario. Untracked files are left alone.

Some file operations support the optional root parameter, which can be used to resolve relative paths:

• clear-dir
• copy-file
• delete-file

Possible values of the root parameter:

• PROJECT - the project directory (default)
• GRADLE_USER_HOME - the Gradle user home directory

They can be added to a scenario file like this:

incremental_build {
    tasks = ["assemble"]

    apply-build-script-change-to = "build.gradle.kts"
    apply-project-dependency-change-to {
        files = ["build.gradle"]
        # Default number of dependency-count is 3.
        # Gradle Profiler will simulate changes to project dependencies by generating some additional projects and then adding a combination of project dependencies to every non-generated subproject before each iteration.
        # The profiler will generate the minimal number of subprojects to allow for a unique combination of dependencies to be used for each iteration.
        # Note: Number of generated projects is calculated as binomial coefficient: "from `x` choose `dependency-count` = `iterations * files`", where number of generated projects is `x`.
        dependency-count = 3
    }
    apply-abi-change-to = "src/main/java/MyThing.java"
    apply-non-abi-change-to = ["src/main/java/MyThing.java", "src/main/java/MyOtherThing.java"]
    apply-h-change-to = "src/main/headers/app.h"
    apply-cpp-change-to = "src/main/cpp/app.cpp"
    apply-property-resource-change-to = "src/main/resources/thing.properties"
    apply-android-resource-change-to = "src/main/res/values/strings.xml"
    apply-android-resource-value-change-to = "src/main/res/values/strings.xml"
    apply-android-manifest-change-to = "src/main/AndroidManifest.xml"
    clear-build-cache-before = SCENARIO
    clear-transform-cache-before = BUILD
    show-build-cache-size = true
    clear-dir = [{
        target = "build/tmp"
    }, {
        root = GRADLE_USER_HOME # to resolve relative paths; can be PROJECT or GRADLE_USER_HOME
        target = "caches/build-cache"
        keep = ["gc.properties"] # only names of direct children are supported
    }]
    copy-file = {
        source = "../develocity.xml"
        target = ".mvn/develocity.xml"
    }
    delete-file = [{
        target = ".mvn/develocity.xml"
        schedule = CLEANUP
    }, {
        target = ".gradle"
        schedule = CLEANUP
    }]
    git-checkout = {
        cleanup = "efb43a1"
        build = "master"
    }
    git-revert = ["efb43a1"]
    jvm-args = ["-Xmx2500m", "-XX:MaxMetaspaceSize=512m"]
}

Troubleshooting scenario configuration

Gradle Profiler supports defining scenarios in the --scenario-file using HOCON format. This format is very flexible and supports advanced features like merging of objects and value substitutions.

If you encounter problems with scenario configuration, you can use the --dump-scenarios option to dump the resolved configuration. This will output the normalized scenario configuration without running any builds. This configuration is what Gradle Profiler effectively sees when resolving the definition of a given scenario. However, it does not include any values provided on the command-line, as it only considers the scenario file itself.

> gradle-profiler --scenario-file performance.scenarios --dump-scenarios clean_build

In the case of a scenario file like this:

base {
    daemon = cold
    iterations = 10
}

clean_build = ${base} {
    title = "Clean build"
    tasks = [build]
    cleanup-tasks = [clean]
}

This will output the resolved configuration (keys are always sorted alphabetically):

# Scenario 1/1 'Clean build'
clean_build {
    cleanup-tasks=[
        clean
    ]
    daemon=cold
    iterations=10
    tasks=[
        build
    ]
    title="Clean build"
}

You can specify multiple scenarios or use --group to dump all scenarios in a group. If no scenarios are specified, it will dump the default-scenarios.

The printed scenarios are valid scenario definitions that can be used as-is in scenario files.

Comparing against other build tools

You can compare Gradle against Bazel, Buck, and Maven by specifying their equivalent invocations in the scenario file. Only benchmarking mode is supported.

Maven

> gradle-profiler --benchmark --maven clean_build

clean_build {
    tasks = ["build"]
    cleanup-tasks = ["clean"]
    maven {
        # If empty, it will be inferred from MAVEN_HOME environment variable
        home = "/path/to/maven/home"
        targets = ["clean", "build"]
    }
}

Bazel

> gradle-profiler --benchmark --bazel build_some_target

build_some_target {
    tasks = ["assemble"]

    bazel {
        # If empty, it will be inferred from BAZEL_HOME environment variable
        home = "/path/to/bazel/home"
        targets = ["build" "//some/target"]
    }
}

Buck

> gradle-profiler --benchmark --buck build_binaries

build_binaries {
    tasks = ["assemble"]

    buck {
        # If empty, it will be inferred from BUCK_HOME environment variable
        home = "/path/to/buck/home"
        type = "android_binary" // can be a Buck build rule type or "all"
    }
}
build_resources {
    tasks = ["thing:processDebugResources"]

    buck {
        targets = ["//thing/res_debug"]
    }
}

TroubleShooting

Profiling with Async Profiler

No stack counts found on Linux

Running async-profiler on Linux requires setting flags for Linux kernel. See async-profiler docs for explanation. Otherwise, it causes this RuntimeException when collecting profile results:

java.lang.RuntimeException: Could not run command perl /tmp/flamegraph1180508986208029728.pl /home/user/dev/sandbox/GradleTaskTime/profile-out-2/5.6.simplified-stacks.txt --colors java --minwidth 1 --title CPU Flame Graph --countname samples
Output:
======
ERROR: No stack counts found
...