Step-by-Step Guide to Installing Judoscale for Spring Boot

Requirements

• Java 21 or later
• Spring Boot 3.2 or later

Guided Install

When you launch Judoscale for the first time, you’ll be prompted to install a package that’s specific to your app’s language and framework. In the package installation modal, select “Java” for your language and “Spring Boot” for your framework.

Based on your selections, you’ll see instructions for installing the correct package and integrating it with your application.

Maven

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.judoscale</groupId>
    <artifactId>judoscale-spring-boot-starter</artifactId>
    <version>x.x.x</version>
</dependency>

Gradle

Add the dependency to your build.gradle:

implementation 'com.judoscale:judoscale-spring-boot-starter:+'

Or for Kotlin DSL (build.gradle.kts):

implementation("com.judoscale:judoscale-spring-boot-starter:+")

Configuration

The library is enabled automatically when the JUDOSCALE_URL environment variable is set. This is configured automatically when using the Heroku Judoscale add-on, or you can find your unique API URL in your Judoscale dashboard.

Optional Configuration

You can configure the library via application.properties or application.yml:

# Judoscale is enabled by default when JUDOSCALE_URL is set.
# Set to false to explicitly disable.
judoscale.enabled=true

To enable debug logging:

logging.level.com.judoscale=DEBUG

Or via environment variable:

LOGGING_LEVEL_COM_JUDOSCALE=DEBUG

Verification

Once you’ve committed and deployed these changes, click the button at the bottom of the modal to verify your package setup.

Once verified, the modal will close, and Judoscale will begin collecting throughput and request queue time metrics.

Note that autoscaling is still turned off. You’ll want to review your configuration before enabling autoscaling.

How It Works

Once configured, the library works automatically. It will:

1. Measure request queue time — Captures the time requests spend waiting in your platform’s router queue before reaching your application.
2. Measure web utilization — Captures how often your web servers are busy handling requests.
3. Report metrics — Sends collected metrics to the Judoscale API every 10 seconds.

Note: The library is automatically disabled in development or any environment where JUDOSCALE_URL is not set. It’s safe to include in your project without affecting local development.

Queue Time and Tomcat Concurrency

When autoscaling a Spring Boot application, it’s important to understand how Tomcat’s thread concurrency affects your queue time metrics.

Tomcat’s default thread pool size is 200. Queue time measures how long a request waits between the load balancer and Tomcat picking it up. With such a high concurrency threshold, Tomcat can handle many simultaneous requests before any start queuing—which means you’ll only see queue time increase once all 200 threads are busy.

For most applications, this is a lot of traffic. If your app rarely saturates 200 threads, queue time may not be a reliable indicator of when to scale.

When Queue Time Works Well

If you’ve configured Tomcat to use fewer threads (e.g., via server.tomcat.threads.max), queue time becomes a more sensitive and reliable metric. With a lower concurrency threshold, requests will start queuing sooner, giving Judoscale earlier signals to scale up.

Our Recommendation: Use Both Metrics

With the default concurrency of 200, we highly recommend enabling the utilization metric alongside queue time. Utilization tracks how often your web server is busy handling requests—if any threads are active, the server is considered busy. This provides a proactive signal before requests start queuing.

Using both metrics together gives you the best of both worlds:

• Utilization helps scale up proactively as your server stays busy
• Queue time acts as a safety net, ensuring you scale when requests actually start waiting

Learn more about the utilization metric and how to configure it in our Understanding Utilization guide.

Accessing Queue Time

As Judoscale captures queue time for each request, you can access this metric for your own logging or analysis via a request attribute:

@GetMapping("/example")
public String example(HttpServletRequest request) {
    Long queueTime = (Long) request.getAttribute("judoscale.queue_time");
    if (queueTime != null) {
        logger.info("Request waited {}ms in queue", queueTime);
    }
    return "Hello!";
}

Troubleshooting

If metrics aren’t being reported, check the following:

1. Ensure the JUDOSCALE_URL environment variable is set
2. Enable debug logging to see detailed information about metric collection
3. Verify your Spring Boot version is 3.2 or later
4. Check that Java 21 or later is being used

For additional help, see our troubleshooting guide or contact us.