Using Stackdriver Logging in App Engine apps

Priya Agrawal, Deepak Tiwari, Doug Anderson

Stackdriver Logging provides facilities for importing, viewing, storing, and retrieving logs from apps running on the Google Cloud Platform.

This page summarizes the logs available in Stackdriver Logging from App Engine.

What is available

Stackdriver Logging includes the following features for App Engine:

  • Request logs, app logs, shutdown logs, runtime logs, and audit logs for App Engine apps.
  • A logs API for accessing logs of apps in the standard environment (Python, Java, PHP, Go).

Audit Logs

App Engine writes Admin Activity audit logs, cloudaudit.googleapis.com/activity, called activity in the Logs Viewer.

Stackdriver Logging and the standard environment

The App Engine standard environment produces the following logs:

  • Request logs, appengine.googleapis.com/request_log, called request_log in the Logs Viewer. This log records requests sent to all App Engine apps. The request log is provided by default and you cannot opt out of receiving it. For more details, see the RequestLog type.

  • App logs consist of additional app information included in the request logs. The information is provided by default and you cannot opt out of receiving it. For more details, see the LogLine type.

  • Third-party package logs. Some third-party package logs are also produced, including appengine.googleapis.com/nginx.request, called nginx.request in the Logs Viewer.

Log entries from App Engine use the resource type gae_app.

Fields in request logs

For the App Engine standard environment request log, the following predefined names can be used as Logs Viewer field labels; see Field path identifiers for more information. All fields contain string values except for status and bytes.

Field name Contents
bytes The number of bytes in the response to the client. Example: 138.
method The HTTP method. Example: GET.
path The path appended to your host's address. Example: /service/local.
protocol The protocol used. Example: HTTP/1.1.
querystring The query string on the request, if any. Example: ?copies=3.
remotehost The host making the request. Example: 192.168.100.1.
request_id The RFC 1413 client ID.
status The numeric status code returned to the client: Example: 200.
user An authorized user, if any.
useragent The browser or other agent making the requests. Example: Stackdriver_terminus_bot.

Stackdriver Logging and the flexible environment

When a request is sent to your app running in App Engine, request and response details are logged automatically, and can be viewed in the Google Cloud Platform Console Logs Viewer.

When your app handles a request, it can also write its own logging messages by using the appropriate Google Cloud Client library or by writing to stdout and stderr. These files are automatically collected and can be viewed in the Logs Viewer. Only the most recent entries to stdout and stderr are retained, in order to limit their size.

The App Engine flexible environment produces the following logs:

  • Request logs record requests sent to all App Engine apps. The request log is provided by default and you cannot opt out of receiving it.

  • App logs record activity by software within the App Engine app. The log is provided by default and you cannot opt out of receiving it.

  • Runtime logs are provided from the flexible environment using a preinstalled Logging agent.

Logs from the flexible environment include resources of type gae_app.

App logs and request logs

Request and app logs are stored separately in the flexible environment.

Log type Payload type Purpose
request text Requests made to your apps in the flexible environment.
app text or structured App logs entries from your apps in the flexible environment.

Linking app logs and requests

In the App Engine flexible environment, app logs can be correlated with a particular request. Following are the requirements:

  1. The "parent" log entry must include a value for httpRequest.requestUrl.

  2. The "child" log entry must have a different log name than the parent. Typically, the child log entry is an app log entry in the app log, whereas the parent log entry is in the request log. The values for resource.type, resource.labels, and trace must be the same in the parent and its child(ren).

  3. The child log entry's timestamp must be within the time interval covered by the parent request. It must be earlier than parent.timestamp and later than parent.timestamp - parent.httpRequest.latency.

For more information on log entries, see the LogEntry data type in Stackdriver Logging.

Runtime logs

The App Engine flexible environment can write additional logs from the runtimes.

Following are some of the logs that are configured by default:

Log name Purpose
activity Shows audit log information.
monitoring.* Information from the container where your app is running.
nginx.error Shows errors surfaced from within the nginx process.
nginx.health_check Shows nginx logs specifically for health checks. Reduces noise in the request logs.
nginx.request Shows logs from the nginx proxy as they are passed through to the app container.
shutdown.log Information logged on shutdown.
stdout Standard output from your app container.
stderr Standard error from your app container.
vm.events Operational events related to instances.
vm.shutdown Information logged on shutdown.
vm.syslog The VM syslog, outside of the app container.

VM events logging

You can gain insight into events related to your App Engineflexible environment instances using the vm.events stream in Logging. The following events are logged in this stream:

  • Instance creation
  • Instance termination (and why, reported on a best-effort basis)
  • Instance health check aggregate statistics reported approximately every minute
  • Instance unlocked for debugging or instance was accessed via SSH

Note that the vm.events stream may not report events in chronological order.

Shutdown logs

You can get diagnostic information when your app container is stopped. For example, this might happen if an app is unresponsive due to a deadlock or high load and has stopped returning requests, including health checks.

To help diagnose issues, you can get debug information, such as thread traces and heap statistics, from the app container through Stackdriver Logging (available in stdout and vm.shutdown streams).

In vm.shutdown, there are logs from Docker containers including the app container and other sidecar containers, such as nginx, for both healthy and unhealthy shutdown.

If your app is unhealthy, you can get other logs in vm.shutdown such as:

  • App stdout and stderr
  • Tail of app logs
  • Additional debug information: machine type, memory and disk usage, etc.

In the Java runtime, shutdown logging for the app container is built into the JVM. For more information, see the documentation.

In the Python runtime, faulthandler was added to the Python standard library in Python 3.3 and a backport is available for Python 2.7.

Using the Logs Viewer

The Logs Viewer provides a web-based UI to navigate, display, and search your logs. With the Logs Viewer you can view and search logs from all your instances and apply filters to narrow in on a specific event, regardless of where it was generated.

To view logs:

  1. In the Google Cloud Platform Console, go to the Logging page.

  2. Ensure that App Engine is selected in the dropdown menu.

Filtering and finding logs

You can choose to view only those logged events that are above a certain severity. Debug events are considered the lowest severity, Critical events are considered the highest. For instance, if you select a minimum severity of 'Warning', all warning, error, and critical log events will be displayed.

When viewing the Request log, you can combine field filters (for example, status:, protocol:, and so forth) and regular expressions in the same query, using the filter text box in the Logs Viewer. In addition, you can add and remove filters to help drill down and then zoom out again until you find what you’re looking for. Simply modify the query and press Enter to refresh the logs.

When you click the search bar, the Logs Viewer shows possible completions for filter fields as you type.

Filters of the same type are ORed together, while different filter types are ANDed together. So for example, status:400 status:500 regex:quota would produce all requests that returned HTTP status of either 400 OR 500, AND have the word quota in the log.

Search or scroll through all of your logs

When you scroll through your logs in the new Logs Viewer, results are fetched until the console window is full. To retrieve additional logs that match the query, scroll down for newer results or up for older ones.

This provides you with a continuous view of your events to enable you to move forward and backward in time without requiring you to click Next or refresh the console. While results are being fetched you will see a Loading… indicator at the top or bottom of the viewer.

You can also click the refresh icon to load the latest logs, or click the play icon to live stream the logs for all of your logs from all of your instances.

Downloading logs from App Engine

For download information, see the log downloading instructions for Python, Java, or Go, and PHP.

How to read the request log

The request log fields are documented in the Logs API pages for Python, Java, Go, and PHP.

Writing app logs from your app

Writing app logs is described in the Logs pages for Python, Java, Go, and PHP.

Was this page helpful? Let us know how we did:

Send feedback about...

App Engine Documentation