Skip to content

writing application logs

Jump to bottom
ludoch edited this page Apr 15, 2026 · 2 revisions

Write and view logs

This page describes the logs that are available for App Engine apps, and how to write, correlate, and view log entries.

App Engine collects two types of logs:

  • Request log: Logs of requests sent to your app. By default, App Engine automatically emits a log entry for each HTTP request an app receives.

  • App log: Log entries that are emitted by an App Engine app based on the log entries you write to a supported framework or file.

App Engine automatically sends both the request logs and app logs to the Cloud Logging agent.

Note: If you are upgrading from the first-generation runtime to the second-generation runtime, see Migrate to Cloud Logging for more details and examples.

Write app logs

App Engine automatically emits logs for requests sent to your app, so there is no need to write request logs. This section covers how to write app logs.

When you write app logs from your App Engine app, the logs are picked up automatically by Cloud Logging, as long as the logs are written using the following methods:

To write log entries, see the Cloud Logging guide for Setting up language runtimes.

Integrate with Cloud Logging

You can integrate your App Engine app with Cloud Logging. This approach lets you use all the features offered by Cloud Logging and requires only a few lines of Google-specific code.

The Cloud Logging library for Go exposes a higher-level layer for working with Cloud Logging. For more information, see Setting up Cloud Logging for Go.

You can integrate the Logback appender or java.util.logging with Cloud Logging. Using the Logback appender, you can use Cloud Logging with the SLF4J logging facade.

For more information on using Cloud Logging from Java applications with the Logback appender, or the java.util.logging handler, or to integrate the Cloud Logging library for Java directly, see Setting up Cloud Logging for Java.

For Node.js applications, plugins are maintained for the following popular logging libraries:

  • Winston is a general-purpose library, implementing a variety of log formatters and transports.

  • Bunyan specializes in structured JSON logs. Format logs by piping to the Bunyan command line.

You can also use the {{client_lib_name}} library for Node.js directly, or create your own integrations with your preferred logging library. For instructions and code samples, see Setting up Cloud Logging for Node.js.

The Cloud Logging library for PHP provides a simple PSR-3 logger implementation for PHP web frameworks. To write logs from your app, add the Cloud Logging library for PHP to your composer.json file:

composer require google/cloud-logging

For detailed installation instructions, and writing logs to Cloud Logging from PHP applications using the Cloud Logging library for PHP directly, see Setting up Cloud Logging for PHP.

You can write logs to Cloud Logging from Ruby applications by using the Cloud Logging library for Ruby, or by using the {{client_lib_name}} for Ruby directly. For more information, see Setting up Cloud Logging for Ruby.

You can write logs to Cloud Logging by integrating the standard ASP.NET logger or using Log4Net with Cloud Logging. For more information, see Using ASP.NET or calling the API.

You can write logs to Cloud Logging from Python applications by using the standard Python logging handler, or by using the Cloud Logging API client library for Python directly. When you use the standard Python logging handler, you must attach a Cloud Logging handler to the Python root handler. For more information, see Setting up Cloud Logging for Python.

Important: The {{logs_explorer}} does not display an app log entry that exceeds 16 kilobytes.

Write structured logs to stdout and stderr

By default, App Engine uses the Cloud Logging client library to send logs. However, this method doesn't support structured logging. You can only write structured logs using stdout/stderr. Additionally, you can also send text strings to stdout and stderr. By default, the log payload is a text string stored in the textPayload field of the log entry. The strings appear as messages in the {{logs_explorer}}, the command line, and the Cloud Logging API, and are associated with the App Engine service and version that emitted them.

To get more value from the logs, you can filter these strings in the {{logs_explorer}} by severity level. To filter these strings, you need to format the strings as structured data. To do this, you write logs in the form of a single line of serialized JSON. App Engine picks up and parses this serialized JSON line, and places it into the jsonPayload field of the log entry instead of textPayload.

The following snippets demonstrate writing such structured logs.

Note: These snippets were originally written for Cloud Run. They are equally applicable to App Engine.

The structure for each log entry is provided by an Entry type:

Enable JSON logging with Logback and SLF4J by enabling the Logstash JSON Encoder in your logback.xml configuration.

Customize standard field names to exclude unwanted content from ingestion in the logs payload. For a list of field names and expected data formats see Use the logging agent.

In the standard environment, writing structured logs to stdout and stderr don't count against the log ingestion requests per minute quota in the Cloud Logging API.

Special JSON fields in messages

When you provide a structured log as a JSON dictionary, some special fields are stripped from the jsonPayload and are written to the corresponding field in the generated LogEntry as described in the documentation for special fields.

For example, if your JSON includes a severity property, it is removed from the jsonPayload and appears instead as the log entry's severity. The message property is used as the main display text of the log entry if present.

Correlate request logs with app logs

After you've formatted the entries as a JSON object and provided specific metadata, you can enable filtering and correlation with request logs. To correlate the request log entries with the app log entries, you need the request's trace identifier. Follow the instructions to correlate log messages:

  1. Extract the trace identifier from the X-Cloud-Trace-Context request header.
  2. In your structured log entry, write the ID to a field named logging.googleapis.com/trace. For more information about the X-Cloud-Trace-Context header, see Forcing a request to be traced.

To view correlated logs, see View correlated log entries in the {{logs_explorer}}.

Correlate request logs with app logs

By default, logs are not correlated in the second-generation runtimes. These runtimes require the use of the {{client_lib_name}}. These libraries don't support nesting, and require you to correlate your logs.

Use stdout and stderr

After you've formatted the entries as a JSON object and provided specific metadata, you can enable filtering and correlation with request logs. To correlate the request log entries with the app log entries, you need the request's trace identifier. Follow the instructions to correlate log messages:

  1. Extract the trace identifier from the X-Cloud-Trace-Context request header.
  2. In your structured log entry, write the ID to a field named logging.googleapis.com/trace. For more information about the X-Cloud-Trace-Context header, see Forcing a request to be traced.

To view correlated logs, see View correlated log entries in the {{logs_explorer}}.

View logs

Pricing, quotas, and logs retention policy

For information about pricing that applies to both request and app logs, see Pricing for Cloud Logging.

For the logs retention policy and the maximum size of log entries, see Quotas and limits. If you want to store your logs for a longer period, you can export your logs to Cloud Storage. You can also export your logs to {{bigquery_name}} and {{pubsub_name}} for further processing.

Managing log resource usage

You can control the amount of logging activity from your app logs by writing more or fewer entries from your app's code. Request logs are created automatically, so to manage the number of request log entries associated with your app, Use the logs exclusion feature from Cloud Logging.

Known issues

The following are some logging issues in the second-generation runtimes:

  • Sometimes app log entries are not correlated with the request log. This happens the first time your app receives a request and any other time App Engine writes status messages to your app's log. For more information, see https://issuetracker.google.com/issues/138365527.

  • When you route logs from log sink to Cloud Storage, the Cloud Storage destination only contains request logs. App Engine writes app logs to different folders.

  • {{bigquery_name}} fails to ingest logs due to the @type field in request logs. This disrupts the auto-schema detection, since {{bigquery_name}} doesn't allow @type in field names. To resolve this, you must manually define the schema, and remove the @type field from request logs.

  • If you use the logging REST APIs, a background thread writes logs to Cloud Logging. If the main thread isn't active, the instance doesn't get CPU time, which causes the background thread to stop. Log processing time is delayed. At some point, the instance is removed and any unsent logs are lost. To avoid losing logs, use one of the following options:

  • Configure the Cloud Logging SDK to use gRPC. With gRPC, the logs are sent to Cloud Logging immediately. However this can increase the required CPU limits. * Send log messages to Cloud Logging using stdout/stderr. This pipeline is outside the App Engine instance and doesn't get throttled.

What's next

  • See Monitor and alert latency to learn how to use Cloud Logging to view logs for debugging errors, and how to use Cloud Trace to understand app latency.

Clone this wiki locally