Gradle Profiler

YourKit is a commercial profiler. Integration is currently limited to sampling and instrumentation. Ensure the YOURKIT_HOME environment variable is set.

Available Profiler Modes:

• --profile yourkit: Uses CPU sampling instrumentation by default.
• --profile yourkit-tracing: Switches to CPU tracing.
• --profile yourkit-heap: Switches to memory allocation profiling.

Note: All probes are disabled when using sampling or memory allocation profiling.

Configuration:

• The connection port (default 10021) can be overridden via the system property org.gradle.profiler.yourkit.port.

JProfiler is a commercial profiler supporting sampling and instrumentation. Use --profile jprofiler to start.

Configuration Options:

• --jprofiler-config <mode>: Set mode to sampling-all (samples all methods) or instrumentation (switches to CPU instrumentation). Default is sampling only packages containing gradle.
• --jprofiler-alloc: Enable memory allocation recording.
• --jprofiler-monitors: Enable monitor usage recording.
• --jprofiler-probes <ids>: Enable specific probes (e.g., --jprofiler-probes builtin.FileProbe).
• --jprofiler-heapdump: Enable heap dump after build.
• --jprofiler-session <sessionId>: Use a specific JProfiler session.
• --jprofiler-home <path>: Specify a different JProfiler installation.
• --jprofiler-config: (Note: The documentation lists sampling-all and instrumentation as arguments to --jprofiler-config).

You can group related scenarios together using the scenario-groups top-level element in your HOCON scenario file. This allows you to run a subset of scenarios at once.

To run only the scenarios belonging to a specific group, use the --group flag.

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"]
}

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

JFR provides low-overhead CPU, allocation, IO wait, and lock profiling. It is available on Oracle JDK (since Java 7) and OpenJDK (since Java 11+). It is the only low-overhead allocation profiler for Windows, though it does not sample native method calls.

Usage: Use --profile jfr to enable. You can customize settings using --jfr-settings <path-to-jfc-or-template>, where templates include built-in names like profile.

To get deep insight into build performance, use the --profile option with a specific profiler name. The app runs the build several times to warm up the daemon, then enables the profiler and runs the build. Results are stored in profile-out/ by default. If using Async Profiler or JFR, flame graphs are automatically generated. If profiling multiple scenarios or versions, differential flame graphs are also created.

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

Chrome traces provide a low-level event dump (e.g., project evaluation, task execution) and display CPU load, memory usage, and GC activity. Requires Gradle 3.3+.

Usage: Add --profile chrome-trace. Open the resulting file in Google Chrome at chrome://tracing.

Benchmarking records the execution time of a build multiple times to calculate the mean and standard error. It has zero impact on execution time and is ideal for before/after comparisons.

To run a benchmark, use the --benchmark flag, specify the project directory with --project-dir, and provide the tasks to run:

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

Key Details:

• <root-dir-of-build> is the directory containing the build.
• <task> is the task name (as used in the gradle command).
• Results are written to profile-out/benchmark.html and profile-out/benchmark.csv.
• The profiler uses the default Gradle version, Java installation, and JVM args specified in your build (e.g., via the Gradle wrapper).

Running the full ./gradlew test suite is slow and not recommended for local development. Instead, use Gradle's test filtering to run specific test classes or methods.

The project uses the Spock (Groovy) framework for testing. Most tests are located in src/test/groovy.

./gradlew :test --tests 'org.gradle.profiler.CommandLineIntegrationTest.can show version with #option'

To build and run Gradle Profiler, you must have the following Java versions installed:

• Java 17: Required for the core build and execution.
• Java 11: Required specifically for running Gradle cross-version tests.

To install the gradle-trace-converter-app from the root of the gradle-profiler repository:

1. Run the installation task: ./gradlew :gradle-trace-converter-app:install This installs the distribution to subprojects/gradle-trace-converter-app/distribution.

2. Add the bin/ directory within that distribution to your $PATH, or create an alias in your shell startup script (e.g., .zshrc, .bashrc).

You can specify a custom installation location using the gtc.install.dir property.

Example:

./gradlew :gradle-trace-converter-app:install -Pgtc.install.dir=/usr/local/bin