Background Monitoring Patterns

This guide provides advanced patterns for monitoring and managing long-running background builds using gradle, query_build, and wait_build.

Common Monitoring Patterns

1. Waiting for a Log Message

The most common pattern for background builds (like dev servers) is to wait for a specific log message that indicates the build is ready using wait_build.

{
  "buildId": "BUILD_ID",
  "timeout": 60,
  "waitFor": "Started Application"
}

timeout: Max seconds to wait for the message.
waitFor: A regex pattern to match in the build logs.

2. Waiting for Task Completion

If you want to wait for a specific task to finish in a background build.

{
  "buildId": "BUILD_ID",
  "timeout": 120,
  "waitForTask": ":app:assemble"
}

waitForTask: The path of the task to wait for.

3. Monitoring Progress Without Waiting

To check the current status of a background build without waiting for a specific event using query_build.

{
  "buildId": "BUILD_ID"
}

This returns a summary of the current build state (e.g., BUILD IN PROGRESS, SUCCESS, FAILURE), failures, and problems.
Example: query_build(buildId="ID")

4. Inspecting Active Builds (Build Dashboard)

To see all currently running background builds and recent history.

{}

Call query_build() with no arguments to see the dashboard.
This is the easiest way to find BuildIds for active or recently finished builds.

Advanced Management

1. Stopping a Background Build

Always stop background builds when they are no longer needed to free up resources.

{
  "stopBuildId": "BUILD_ID"
}

2. Continuous Builds

For continuous builds (e.g., gradle build --continuous), use the background pattern and wait for the "Waiting for changes" message.

// Start the build
{
  "commandLine": ["build", "--continuous"],
  "background": true
}

// Wait for the first build to finish
{
  "buildId": "BUILD_ID",
  "timeout": 120,
  "waitFor": "Waiting for changes"
}

3. Handling Timeouts

If a build takes longer than the timeout time, wait_build will return the current status. You can then call it again with a new timeout time if needed.

Troubleshooting Background Builds

Build Fails Immediately: If a background build fails quickly, check the failures and console output using query_build.
Log Message Not Found: Ensure the waitFor regex is correct and that the message is actually being printed to the console.
Resource Exhaustion: If you have too many background builds running, stop the ones you don't need using stopBuildId.

Functional Identity with Foreground Execution

Monitoring a background build using query_build or wait_build provides exactly the same rich diagnostic data as a foreground build. The primary difference is control flow: background execution allows you to yield control and perform other tasks, whereas foreground execution blocks until completion. Both methods utilize progressive disclosure to ensure session history remains clean and focused.

3.1 KiB Raw Blame History