Package com.patbaumgartner.greener.gradle

Class MeasureEnergyTask

java.lang.Object
org.gradle.api.internal.AbstractTask
org.gradle.api.DefaultTask
com.patbaumgartner.greener.gradle.MeasureEnergyTask
All Implemented Interfaces:
Comparable<org.gradle.api.Task>, org.gradle.api.internal.DynamicObjectAware, org.gradle.api.internal.TaskInternal, org.gradle.api.Named, org.gradle.api.plugins.ExtensionAware, org.gradle.api.Task, org.gradle.util.Configurable<org.gradle.api.Task>
@DisableCachingByDefault(because="Energy measurement depends on live system state") public abstract class MeasureEnergyTask extends org.gradle.api.DefaultTask
Gradle task that measures the energy consumption of a Spring Boot application using Joular Core.

This task mirrors the Maven greener:measure goal.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.gradle.api.Named

    org.gradle.api.Named.Namer

  • Field Summary

    Fields inherited from interface org.gradle.api.Task

    TASK_ACTION, TASK_CONSTRUCTOR_ARGS, TASK_DEPENDS_ON, TASK_DESCRIPTION, TASK_GROUP, TASK_NAME, TASK_OVERWRITE, TASK_TYPE

  • Constructor Summary

    Constructors
    Constructor
    Description
    MeasureEnergyTask()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract org.gradle.api.provider.ListProperty<String>
    getAppArgs()
    Additional application arguments passed to the Spring Boot process.
    abstract org.gradle.api.provider.Property<Boolean>
    getAutoUpdateBaseline()
    When true, the measurement result is automatically promoted to the baseline after a successful run.
    abstract org.gradle.api.file.RegularFileProperty
    getBaselineFile()
    Path to the JSON baseline file.
    abstract org.gradle.api.provider.Property<String>
    getBaseUrl()
    Base URL of the Spring Boot application.
    abstract org.gradle.api.provider.Property<String>
    getBranch()
    Branch name to record in the baseline when auto-updating.
    abstract org.gradle.api.provider.Property<String>
    getCommitSha()
    Git commit SHA to record in the baseline when auto-updating.
    abstract org.gradle.api.provider.Property<String>
    getExternalTrainingCommand()
    Optional external command used as the training workload (e.g.
    abstract org.gradle.api.file.RegularFileProperty
    getExternalTrainingScriptFile()
    Path to an external shell script file used as the training workload.
    abstract org.gradle.api.provider.Property<Boolean>
    getFailOnRegression()
    When true, the build is failed if energy consumption regressed beyond getThreshold().
    abstract org.gradle.api.provider.Property<String>
    getHealthCheckPath()
    Health-check path used to detect application readiness.
    abstract org.gradle.api.provider.Property<Integer>
    getIdleProbeSeconds()
    Idle-baseline window (seconds) measured before workload.
    abstract org.gradle.api.provider.Property<Integer>
    getIterations()
    Number of independent measurement iterations.
    abstract org.gradle.api.file.RegularFileProperty
    getJoularCodeJavaAgentPath()
    Path to the Joular Code Java agent jar.
    abstract org.gradle.api.file.RegularFileProperty
    getJoularCodeJavaConfigPath()
    Path to the Joular Code Java joularcodejava.properties file.
    abstract org.gradle.api.file.RegularFileProperty
    getJoularCoreBinaryPath()
    Full path to the Joular Core binary (optional; auto-downloaded when absent).
    abstract org.gradle.api.provider.Property<String>
    getJoularCoreComponent()
    Hardware component to monitor: cpu, gpu, or all.
    abstract org.gradle.api.provider.Property<String>
    getJoularCoreVersion()
    Joular Core release version to download when getJoularCoreBinaryPath() is not set.
    abstract org.gradle.api.provider.ListProperty<String>
    getJvmArgs()
    Additional JVM arguments passed when starting the Spring Boot process.
    protected abstract org.gradle.api.file.ProjectLayout
    getLayout()
    Gets the project layout.
    abstract org.gradle.api.provider.Property<Integer>
    getMeasureDurationSeconds()
    Duration in seconds of the actual measurement window after warmup.
    protected abstract org.gradle.api.provider.ProviderFactory
    getProviders()
    Gets the provider factory.
    abstract org.gradle.api.provider.Property<com.patbaumgartner.greener.core.model.RegressionMetric>
    getRegressionMetric()
    Regression metric.
    abstract org.gradle.api.file.DirectoryProperty
    getReportOutputDir()
    Directory where the HTML report is written.
    abstract org.gradle.api.provider.Property<Integer>
    getRequestsPerSecond()
    Number of HTTP requests per second (passed as RPS environment variable).
    abstract org.gradle.api.provider.Property<Boolean>
    getSkip()
    When true, the task execution is skipped entirely.
    abstract org.gradle.api.file.RegularFileProperty
    getSpringBootJar()
    Path to the executable Spring Boot fat-jar.
    abstract org.gradle.api.provider.Property<Integer>
    getStartupTimeoutSeconds()
    Seconds to wait for the application health endpoint before aborting.
    abstract org.gradle.api.provider.Property<Double>
    getThreshold()
    Maximum allowed percentage increase in total energy before the build is failed.
    abstract org.gradle.api.provider.Property<Boolean>
    getTimestampReports()
    When true, the report output directory gets a timestamp suffix (e.g.
    abstract org.gradle.api.provider.Property<Integer>
    getTopN()
    Number of top energy-consuming methods to show in the HTML report.
    abstract org.gradle.api.provider.Property<Boolean>
    getVmMode()
    Enable Joular Core VM mode.
    abstract org.gradle.api.file.RegularFileProperty
    getVmPowerFilePath()
    Path to the VM power file that Joular Core reads when getVmMode() is true.
    abstract org.gradle.api.provider.Property<Integer>
    getWarmupDurationSeconds()
    Warmup duration in seconds.
    void
    measureEnergy()
    Runs the energy measurement workflow.

    Methods inherited from class org.gradle.api.DefaultTask

    compareTo, configure, dependsOn, doFirst, doFirst, doFirst, doLast, doLast, doLast, finalizedBy, getActions, getAnt, getDependsOn, getDescription, getDestroyables, getDidWork, getEnabled, getExtensions, getFinalizedBy, getGroup, getInputs, getLocalState, getLogger, getLogging, getMustRunAfter, getName, getOutputs, getPath, getProject, getShouldRunAfter, getState, getTaskDependencies, getTemporaryDir, getTimeout, hasProperty, mustRunAfter, onlyIf, onlyIf, onlyIf, property, setActions, setDependsOn, setDescription, setDidWork, setEnabled, setFinalizedBy, setGroup, setMustRunAfter, setOnlyIf, setOnlyIf, setOnlyIf, setProperty, setShouldRunAfter, shouldRunAfter, usesService

    Methods inherited from class org.gradle.api.internal.AbstractTask

    acceptServiceReferences, appendParallelSafeAction, doNotTrackState, doNotTrackStateIf, getAsDynamicObject, getIdentityPath, getImpliesSubProjects, getLifecycleDependencies, getOnlyIf, getReasonNotToTrackState, getReasonsNotToTrackState, getReasonTaskIsIncompatibleWithConfigurationCache, getRequiredServices, getServices, getSharedResources, getStandardOutputCapture, getTaskActions, getTaskIdentity, getTemporaryDirFactory, hasTaskActions, injectIntoNewInstance, isCompatibleWithConfigurationCache, isEnabled, isHasCustomActions, notCompatibleWithConfigurationCache, prependParallelSafeAction, restoreOnlyIf, restoreTaskActions, setImpliesSubProjects

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface org.gradle.api.Task

    doNotTrackState, notCompatibleWithConfigurationCache

  • Constructor Details

    • MeasureEnergyTask

      public MeasureEnergyTask()

  • Method Details

    • getLayout

      @Inject protected abstract org.gradle.api.file.ProjectLayout getLayout()
      Gets the project layout.
      Returns:
      the project layout

    • getProviders

      @Inject protected abstract org.gradle.api.provider.ProviderFactory getProviders()
      Gets the provider factory.
      Returns:
      the provider factory

    • getSpringBootJar

      @InputFile @PathSensitive(ABSOLUTE) @Optional public abstract org.gradle.api.file.RegularFileProperty getSpringBootJar()
      Path to the executable Spring Boot fat-jar. When omitted the task auto-detects a single jar in build/libs/.
      Returns:
      the Spring Boot jar property

    • getJvmArgs

      @Input @Optional public abstract org.gradle.api.provider.ListProperty<String> getJvmArgs()
      Additional JVM arguments passed when starting the Spring Boot process.
      Returns:
      the JVM arguments property

    • getAppArgs

      @Input @Optional public abstract org.gradle.api.provider.ListProperty<String> getAppArgs()
      Additional application arguments passed to the Spring Boot process.
      Returns:
      the application arguments property

    • getJoularCoreBinaryPath

      @InputFile @PathSensitive(ABSOLUTE) @Optional public abstract org.gradle.api.file.RegularFileProperty getJoularCoreBinaryPath()
      Full path to the Joular Core binary (optional; auto-downloaded when absent).
      Returns:
      the Joular Core binary path property

    • getJoularCoreVersion

      @Input public abstract org.gradle.api.provider.Property<String> getJoularCoreVersion()
      Joular Core release version to download when getJoularCoreBinaryPath() is not set. See Joular Core releases for available versions.
      Returns:
      the Joular Core version property

    • getJoularCoreComponent

      @Input public abstract org.gradle.api.provider.Property<String> getJoularCoreComponent()
      Hardware component to monitor: cpu, gpu, or all.
      Returns:
      the Joular Core component property

    • getJoularCodeJavaAgentPath

      @InputFile @PathSensitive(ABSOLUTE) @Optional public abstract org.gradle.api.file.RegularFileProperty getJoularCodeJavaAgentPath()
      Path to the Joular Code Java agent jar. When set, the agent is attached to the Spring Boot JVM via -javaagent: for per-method energy monitoring.
      Returns:
      the Joular Code Java agent path property

    • getJoularCodeJavaConfigPath

      @InputFile @PathSensitive(ABSOLUTE) @Optional public abstract org.gradle.api.file.RegularFileProperty getJoularCodeJavaConfigPath()
      Path to the Joular Code Java joularcodejava.properties file. Used only when getJoularCodeJavaAgentPath() is also set.
      Returns:
      the Joular Code Java config path property

    • getBaseUrl

      @Input public abstract org.gradle.api.provider.Property<String> getBaseUrl()
      Base URL of the Spring Boot application.
      Returns:
      the base URL property

    • getRequestsPerSecond

      @Input public abstract org.gradle.api.provider.Property<Integer> getRequestsPerSecond()
      Number of HTTP requests per second (passed as RPS environment variable).
      Returns:
      the requests per second property

    • getExternalTrainingCommand

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getExternalTrainingCommand()
      Optional external command used as the training workload (e.g. k6 run script.js). The APP_URL environment variable is set to getBaseUrl().
      Returns:
      the external training command property

    • getExternalTrainingScriptFile

      @InputFile @PathSensitive(ABSOLUTE) @Optional public abstract org.gradle.api.file.RegularFileProperty getExternalTrainingScriptFile()
      Path to an external shell script file used as the training workload. Takes precedence over getExternalTrainingCommand() when set.

      Available environment variables in the script: APP_URL, APP_HOST, APP_PORT, WARMUP_SECONDS, MEASURE_SECONDS, TOTAL_SECONDS, RPS.

      See examples/workloads/ for wrk, wrk2, oha, and Gatling examples.

      Returns:
      the external training script file property

    • getVmMode

      @Input public abstract org.gradle.api.provider.Property<Boolean> getVmMode()
      Enable Joular Core VM mode.

      In VM mode Joular Core cannot read RAPL counters directly and instead reads the VM's total power from a file written by the host - see getVmPowerFilePath(). The host must write the VM's instantaneous power (Watts) to that file once per second.

      Returns:
      the VM mode property

    • getVmPowerFilePath

      @InputFile @PathSensitive(ABSOLUTE) @Optional public abstract org.gradle.api.file.RegularFileProperty getVmPowerFilePath()
      Path to the VM power file that Joular Core reads when getVmMode() is true. The file must contain a single floating-point number (e.g. 45.2).
      Returns:
      the VM power file path property

    • getWarmupDurationSeconds

      @Input public abstract org.gradle.api.provider.Property<Integer> getWarmupDurationSeconds()
      Warmup duration in seconds. The application runs under load during warmup so the JIT compiler warms up, but energy data from this phase is discarded.
      Returns:
      the warmup duration property

    • getMeasureDurationSeconds

      @Input public abstract org.gradle.api.provider.Property<Integer> getMeasureDurationSeconds()
      Duration in seconds of the actual measurement window after warmup.
      Returns:
      the measure duration property

    • getStartupTimeoutSeconds

      @Input public abstract org.gradle.api.provider.Property<Integer> getStartupTimeoutSeconds()
      Seconds to wait for the application health endpoint before aborting.
      Returns:
      the startup timeout property

    • getHealthCheckPath

      @Input public abstract org.gradle.api.provider.Property<String> getHealthCheckPath()
      Health-check path used to detect application readiness.
      Returns:
      the health check path property

    • getBaselineFile

      @InputFile @PathSensitive(ABSOLUTE) @Optional public abstract org.gradle.api.file.RegularFileProperty getBaselineFile()
      Path to the JSON baseline file.
      Returns:
      the baseline file property

    • getThreshold

      @Input public abstract org.gradle.api.provider.Property<Double> getThreshold()
      Maximum allowed percentage increase in total energy before the build is failed. For example 10 means a 10 % regression is tolerated.
      Returns:
      the threshold property

    • getFailOnRegression

      @Input public abstract org.gradle.api.provider.Property<Boolean> getFailOnRegression()
      When true, the build is failed if energy consumption regressed beyond getThreshold().
      Returns:
      the fail on regression property

    • getReportOutputDir

      @OutputDirectory @Optional public abstract org.gradle.api.file.DirectoryProperty getReportOutputDir()
      Directory where the HTML report is written.
      Returns:
      the report output directory property

    • getAutoUpdateBaseline

      @Input public abstract org.gradle.api.provider.Property<Boolean> getAutoUpdateBaseline()
      When true, the measurement result is automatically promoted to the baseline after a successful run. This eliminates the need to call updateEnergyBaseline separately.
      Returns:
      the auto-update baseline property

    • getCommitSha

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getCommitSha()
      Git commit SHA to record in the baseline when auto-updating.
      Returns:
      the commit SHA property

    • getBranch

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getBranch()
      Branch name to record in the baseline when auto-updating.
      Returns:
      the branch property

    • getTimestampReports

      @Input public abstract org.gradle.api.provider.Property<Boolean> getTimestampReports()
      When true, the report output directory gets a timestamp suffix (e.g. greener-reports-20260404-153012) and a latest symlink is created pointing to the most recent run.
      Returns:
      the timestamp reports property

    • getSkip

      @Input public abstract org.gradle.api.provider.Property<Boolean> getSkip()
      When true, the task execution is skipped entirely.
      Returns:
      the skip property

    • getTopN

      @Input public abstract org.gradle.api.provider.Property<Integer> getTopN()
      Number of top energy-consuming methods to show in the HTML report.
      Returns:
      the top N property

    • getIterations

      @Input public abstract org.gradle.api.provider.Property<Integer> getIterations()
      Number of independent measurement iterations. With iterations >= 2 the comparator gains run-to-run statistics and applies Welch's t-test + Cohen's d.
      Returns:
      the iterations property

    • getRegressionMetric

      @Input public abstract org.gradle.api.provider.Property<com.patbaumgartner.greener.core.model.RegressionMetric> getRegressionMetric()
      Regression metric. ENERGY_PER_REQUEST (default) normalises by successful requests so throughput improvements don't masquerade as energy regressions; TOTAL_ENERGY compares raw Joules.
      Returns:
      the regression metric property

    • getIdleProbeSeconds

      @Input public abstract org.gradle.api.provider.Property<Integer> getIdleProbeSeconds()
      Idle-baseline window (seconds) measured before workload. Subtracted from workload energy. Set to 0 to disable.
      Returns:
      the idle-probe seconds property

    • measureEnergy

      public void measureEnergy() throws IOException, InterruptedException
      Runs the energy measurement workflow.
      Throws:
      IOException - if an I/O error occurs during measurement
      InterruptedException - if the measurement is interrupted