Configuring Warmup Requests to Improve Performance

This guide describes how to configure your app to handle warmup requests. With warmup requests enabled, the App Engine infrastructure issues GET requests to /_ah/warmup, which allow you to respond and initialize your application's code as it requires. You can respond to warmup requests by using one of the following methods:

Using a <load-on-startup> servlet
The easiest way to provide warmup logic is to mark your own servlets as <load-on-startup> in the web.xml configuration file.
Using a ServletContextListener
Allows you to run custom logic before any of your servlets is first invoked either through a warmup request or a loading request.
Using a custom warmup servlet
Using a custom warmup servlet invokes the servlet's service method only during a warmup request rather than during loading requests.

You might need to implement your own handler for /_ah/warmup depending on which of these methods you choose.

Before you begin

Verify that warmup requests are enabled. Warmup requests are enabled by default. If you turned off warmup requests in the appengine-web.xml file, you need to set the <warmup-requests-enabled> value to true.

Using a <load-on-startup> servlet

The easiest way to provide warmup logic is to mark your own servlets as <load-on-startup> in web.xml. This method requires no changes to your application code, and initializes all specified servlets when your application initializes.

In your web.xml file, for the servlets that you want to load on startup, add the <load-on-startup>1</load-on-startup> element to your <servlet> element. For example:

<servlet>
  <servlet-name>my-servlet</servlet-name>
  <servlet-class>com.company.MyServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>

These lines load the specified servlet class and invoke the servlet's init() method. The warmup request initializes the specified servlets before servicing any live requests. However, if there is no warmup request, the servlets specified in <load-on-startup> are registered upon the first request to a new instance, which result in a loading request. As noted earlier, App Engine might not issue a warmup request every time your application needs a new instance.

Using a ServletContextListener

If you have custom logic that you want to run before any of your servlets is invoked:

  1. Register a ServletContextListener in your web.xml file.

    <listener>
      <listener-class>com.company.MyListener</listener-class>
    </listener>
    
  2. Supply a class alongside your servlet and filter code:

    public class MyListener implements ServletContextListener {
      public void contextInitialized(ServletContextEvent event) {
        // This will be invoked as part of a warmup request, or
        // the first user request if no warmup request was invoked.
      }
      public void contextDestroyed(ServletContextEvent event) {
        // App Engine does not currently invoke this method.
      }
    }
    

The ServletContextListener runs during a warmup request. If there is no warmup request, it runs upon the first request to a new instance. This might result in loading requests.

Using a custom warmup servlet

The custom warmup servlet invokes the servlet's service method only during a warmup request. By placing expensive logic in a custom warmup servlet, you can avoid increased load times on loading requests.

To create a custom warmup servlet, simply override the built-in servlet definition for _ah_warmup in web.xml:

<servlet>
  <servlet-name>_ah_warmup</servlet-name>
  <servlet-class>com.company.MyWarmupServlet</servlet-class>
</servlet>