You can use warmup requests to reduce request and response latency during the time when your app's code is being loaded to a newly created instance.
App Engine frequently needs to load your app's code into a fresh instance. Loading an instance can happen in the following situations:
- When you redeploy a version of your app.
- When new instances are created due to the load from requests exceeding the capacity of the current set of running instances.
- When maintenance and repairs of the underlying infrastructure or physical hardware occur.
Loading your app's code to a new instance can result in loading requests. Loading requests can result in increased request latency for your users, but you can avoid this latency using warmup requests. Warmup requests load your app's code into a new instance before any live requests reach that instance.
If warmup requests are enabled for your application, App Engine attempts to detect when your application needs a new instance and initiates a warmup request to initialize a new instance. However, these detection attempts do not work in every case. As a result, you might encounter loading requests, even if warmup requests are enabled in your app. For example, if your app is serving no traffic, the first request to the app will always be a loading request, not a warmup request.
Warmup requests use instance hours like any other request to your
App Engine application. In most cases where warmup requests are enabled,
you won't notice an increase in instance hours because your application is
simply initializing in a warmup request instead of a loading request. Your
instance hour usage can increase if you decide to do more work, such as
pre-caching during a warmup request. If you set
min_idle_instances
to greater than 0
, you might encounter warmup requests when those instances
first start, but they will remain available after that time.
Enabling warmup requests
Warmup requests are used by the App Engine scheduler, which
controls the auto scaling of instances based on user-supplied configuration.
In the App Engine Java runtime, warmup requests are enabled by
default, and so App Engine issues GET
requests to /_ah/warmup
, which allows
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 theweb.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
When warmup requests are enabled, the scheduler starts up instances when it determines that more instances are needed. The scheduler uses warmup requests to start your app, so you'll see logs even if your app doesn't process those warmup requests.
The following message indicates warmup requests in the /_ah/warmup
logs:
This request caused a new process to be started for your application, and thus caused your application code to be loaded for the first time. This request may thus take longer and use more CPU than a typical request for your application.
Note that warmup requests are not guaranteed to be called. In some situations loading requests are sent instead: for example, if the instance is the first one being started up, or if there is a steep ramp-up in traffic. However, there will be a "best effort" attempt to send requests to already warmed-up instances if warmup requests are enabled.
In Java 8, warmup requests are enabled by default. To enable them,
add - warmup
to the
inbound_services
directive in appengine-web.xml
. Because by default,
warmups are enabled, you only need to explicitly enable them if you have
previously deployed an application with warmup requests disabled in the appengine-web.xml
.
If this is the case, you need to set the <warmup-requests-enabled>
value to
true
and then redeploy.
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:
Register a
ServletContextListener
in yourweb.xml
file.<listener> <listener-class>com.company.MyListener</listener-class> </listener>
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>