How Requests are Handled

This document describes how your App Engine application receives requests and sends responses. For more details, see the [Request Headers and Responses reference](/appengine/docs/standard/java/reference/request-response-headers).

If your application uses services, you can address requests to a specific service or a specific version of that service. For more information about service addressability, see How Requests are Routed.

Handling requests

Your application is responsible for starting a webserver and handling requests. You can use any web framework that’s available for your development language.

When App Engine receives a web request for your application, it invokes the servlet that corresponds to the URL, as described in the application's web.xml file in the WEB-INF/ directory. It uses the Java Servlet API, to provide the request data to the servlet and accept the response data. Note that applications running in the Java 7 runtime are based on the Java Servlet 2.5 specification, but applications running in the Java 8 runtime can be based on either the Java Servlet 3.1 specification or the Java Servlet 2.5 specification.

App Engine runs multiple instances of your application, each instance has its own web server for handling requests. Any request can be routed to any instance, so consecutive requests from the same user are not necessarily sent to the same instance. The number of instances can be adjusted automatically as traffic changes.

By default, each web server processes only one request at a time. To dispatch multiple requests to each web server in parallel, mark your application as threadsafe by adding a <threadsafe>true</threadsafe> element to your appengine-web.xml.

The following example servlet class displays a simple message on the user's browser.

Java 8

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(name = "requests", description = "Requests: Trivial request", urlPatterns = "/requests")
public class RequestsServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    resp.setContentType("text/plain");
    resp.getWriter().println("Hello, world");
  }
}

Java 7

public class RequestsServlet extends HttpServlet {
  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp)
          throws IOException {
    resp.setContentType("text/plain");
    resp.getWriter().println("Hello, world");
  }
}

Quotas and limits

App Engine automatically allocates resources to your application as traffic increases. However, this is bound by the following restrictions:

  • App Engine reserves automatic scaling capacity for applications with low latency, where the application responds to requests in less than one second. Applications with very high latency, such as over one second per request for many requests, and high throughput require Silver, Gold, or Platinum support. Customers with this level of support can request higher throughput limits by contacting their support representative.

  • Applications that are heavily CPU-bound may also incur some additional latency in order to efficiently share resources with other applications on the same servers. Requests for static files are exempt from these latency limits.

Each incoming request to the application counts toward the Requests limit. Data sent in response to a request counts toward the Outgoing Bandwidth (billable) limit.

Both HTTP and HTTPS (secure) requests count toward the Requests, Incoming Bandwidth (billable), and Outgoing Bandwidth (billable) limits. The GCP Console Quota Details page also reports Secure Requests, Secure Incoming Bandwidth, and Secure Outgoing Bandwidth as separate values for informational purposes. Only HTTPS requests count toward these values. For more information, see the Quotas page.

The following limits apply specifically to the use of request handlers:

Limit Amount
request size 32 megabytes
response size 32 megabytes
request duration 60 seconds
maximum total number of files (app files and static files) 10,000 total
1,000 per directory
maximum size of an application file 32 megabytes
maximum size of a static file 32 megabytes
maximum total size of all application and static files first 1 gigabyte is free
$ 0.026 per gigabyte per month after first 1 gigabyte

Response limits

Dynamic responses are limited to 32MB. If a script handler generates a response larger than this limit, the server sends back an empty response with a 500 Internal Server Error status code. This limitation does not apply to responses that serve data from the Blobstore or Google Cloud Storage .

Request headers

An incoming HTTP request includes the HTTP headers sent by the client. For security purposes, some headers are sanitized or amended by intermediate proxies before they reach the application.

For more information, see the [Request headers reference](/appengine/docs/standard/java/reference/request-response-headers#request_headers).

Request responses

App Engine calls the servlet with a request object and a response object, then waits for the servlet to populate the response object and return. When the servlet returns, the data on the response object is sent to the user.

There are limits that apply to the response you generate, and the response may be modified before it is returned to the client.

For more information, see the Request responses reference.

Streaming Responses

App Engine does not support streaming responses where data is sent in incremental chunks to the client while a request is being processed. All data from your code is collected as described above and sent as a single HTTP response.

Response compression

If the client sends HTTP headers with the original request indicating that the client can accept compressed (gzipped) content, App Engine compresses the handler response data automatically and attaches the appropriate response headers. It uses both the Accept-Encoding and User-Agent request headers to determine if the client can reliably receive compressed responses.

Custom clients can indicate that they are able to receive compressed responses by specifying both Accept-Encoding and User-Agent headers with a value of gzip. The Content-Type of the response is also used to determine whether compression is appropriate; in general, text-based content types are compressed, whereas binary content types are not.

When responses are compressed automatically by App Engine, the Content- Encoding header is added to the response.

Specifying a request deadline

A request handler has a limited amount of time to generate and return a response to a request, typically around 60 seconds. Once the deadline has been reached, the request handler is interrupted.

The Java runtime environment interrupts the servlet by throwing a com.google.apphosting.api.DeadlineExceededException. If there is no request handler to catch this exception, the runtime environment will return an HTTP 500 server error to the client.

If there is a request handler and the DeadlineExceededException is caught, then the runtime environment gives the request handler time (less than a second) to prepare a custom response. If the request handler takes more than a second after raising the exception to prepare a custom response, a HardDeadlineExceededError will be raised.

Both DeadlineExceededExceptions and HardDeadlineExceededErrors will force termination of the request and kill the instance.

To find out how much time remains before the deadline, the application can import com.google.apphosting.api.ApiProxy and call ApiProxy.getCurrentEnvironment().getRemainingMillis(). This is useful if the application is planning to start on some work that might take too long; if you know it takes five seconds to process a unit of work but getRemainingMillis() returns less time, there's no point starting that unit of work.

While a request can take as long as 60 seconds to respond, App Engine is optimized for applications with short-lived requests, typically those that take a few hundred milliseconds. An efficient app responds quickly for the majority of requests. An app that doesn't will not scale well with App Engine's infrastructure.

Refer to Dealing with DeadlineExceededErrors for common DeadlineExceededError causes and suggested workarounds.

on the main thread. For more information, see Why is Thread.stop deprecated?. To be safe, you should not rely on the DeadlineExceededException, and instead ensure that your requests complete well before the time limit (using getRemainingMillis() if necessary).

Logging

Your application can write information to the application logs using java.util.logging.Logger. Log data for your application can be viewed in the GCP Console Logs page, or downloaded using appcfg.sh request_logs. Each request logged is assigned a request ID, a globally unique identifier based on the request's start time. The GCP Console can recognize the Logger class's log levels, and interactively display messages at different levels.

Everything the servlet writes to the standard output stream (System.out) and standard error stream (System.err) is captured by App Engine and recorded in the application logs. Lines written to the standard output stream are logged at the "INFO" level, and lines written to the standard error stream are logged at the "WARNING" level. Any logging framework (such as log4j) that logs to the output or error streams will work. However, for more fine-grained control of the log level display in the GCP Console, the logging framework must use a java.util.logging adapter.

Java 7

public class LoggingServlet extends HttpServlet {
  private static final Logger log = Logger.getLogger(LoggingServlet.class.getName());

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp)
        throws IOException {
    log.info("An informational message.");
    log.warning("A warning message.");
    log.severe("An error message.");
    // ...
  }
} 

Java 8

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(
    name = "RequestLogging",
    description = "Requests: Logging example",
    urlPatterns = "/requests/log"
)
public class LoggingServlet extends HttpServlet {

  private static final Logger log = Logger.getLogger(LoggingServlet.class.getName());

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    log.info("An informational message.");
    log.warning("A warning message.");
    log.severe("An error message.");
    // ...
  }
}

The App Engine Java SDK includes a template logging.properties file, in the appengine-java-sdk/config/user/ directory. To use it, copy the file to your WEB-INF/classes directory (or elsewhere in the WAR), then the system property java.util.logging.config.file to "WEB-INF/logging.properties" (or whichever path you choose, relative to the application root). You can set system properties in the appengine-web.xml file, as follows:

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    ...

    <system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/logging.properties" />
    </system-properties>

</appengine-web-app>

The servlet logs messages using the INFO log level (using log.info()). The default log level is WARNING, which suppresses INFO messages from the output. To change the log level, edit the logging.properties file. See the Guestbook Form application for a specific example on how to set log levels.

The Google Plugin for Eclipse new project wizard creates these logging configuration files for you, and copies them to WEB-INF/classes/ automatically. For java.util.logging, you must set the system property to use this file.

The environment

All system properties and environment variables are private to your application. Setting a system property only affects your application's view of that property, and not the JVM's view.

You can set system properties and environment variables for your app in the deployment descriptor.

App Engine sets several system properties that identify the runtime environment:

  • com.google.appengine.runtime.environment is "Production" when running on App Engine, and "Development" when running in the development server.

    In addition to using System.getProperty(), you can access system properties using our type-safe API. For example:

    if (SystemProperty.environment.value() ==
        SystemProperty.Environment.Value.Production) {
        // The app is running on App Engine...
    }
    
  • com.google.appengine.runtime.version is the version ID of the runtime environment, such as "1.3.0". You can get the version by invoking the following: String version = SystemProperty.version.get();

  • com.google.appengine.application.id is the application's ID. You can get the ID by invoking the following: String ID = SystemProperty.applicationId.get();

  • com.google.appengine.application.version is the major and minor version of the currently running application service, as "X.Y". The major version number ("X") is specified in the service's appengine-web.xml file. The minor version number ("Y") is set automatically when each version of the app is uploaded to App Engine. You can get the ID by invoking the following: String ID = SystemProperty.applicationVersion.get();

    On the development web server, the major version returned is always the default service's version, and the minor version is always "1".

App Engine also sets the following system properties when it initializes the JVM on an app server:

  • file.separator
  • path.separator
  • line.separator
  • java.version
  • java.vendor
  • java.vendor.url
  • java.class.version
  • java.specification.version
  • java.specification.vendor
  • java.specification.name
  • java.vm.vendor
  • java.vm.name
  • java.vm.specification.version
  • java.vm.specification.vendor
  • java.vm.specification.name
  • user.dir

Instance IDs

You can retrieve the ID of the instance handling a request using this code:

com.google.apphosting.api.ApiProxy.getCurrentEnvironment().getAttributes().get("com.google.appengine.instance.id")

In the production environment, a logged-in admin can use the ID in a url: http://[INSTANCE_ID].myApp.appspot.com/. The request will be routed to that specific instance. If the instance cannot handle the request it returns an immediate 503.

Request IDs

At the time of the request, you can save the request ID, which is unique to the request. The request ID can be used later to correlate a request with the logs for that request.

The following code shows how to get the request ID in the context of a request:

com.google.apphosting.api.ApiProxy.getCurrentEnvironment().getAttributes().get("com.google.appengine.runtime.request_log_id")

Send feedback about...

App Engine standard environment for Java