Migrate to Cloud Logging

Logging in second-generation runtimes is different from the first-generation runtimes. One of the biggest changes when upgrading to newer runtimes is that the pre-integrated logging with App Engine is not supported in second-generation runtimes, and logs are not automatically correlated. If you are migrating to the second-generation runtimes, you must use the Cloud Logging client library.

This guide describes how you can update your app to use Cloud Logging and achieve nearly the same filtering and log correlation features that were available with the logging integration in App Engine.

Cloud Logging is a real-time log-management system with storage, search, analysis, and monitoring support. Cloud Logging automatically collects logs from Google Cloud resources. You can also collect logs from your applications, resources on-premises, and resources from other cloud providers.

Key differences

The following table covers differences in logging between first and second-generation runtimes:

Before you start migrating

1. Enable the Cloud Logging API in the project that contains your app.

   Enable the API

2. Make sure your app has permission to write logs.

   By default, your app's default service account has permission to write logs.

   If your app uses a different service account , or if you have changed permissions for the default service account, make sure the account you use has the logging.logEntries.create permission to write logs.

3. Familiarize yourself with the different types of logs in App Engine.

Overview of the migration process

To migrate your app to use Cloud Logging:

1. Install the Cloud Client Libraries for Cloud Logging
2. Write logs with Cloud Logging
3. Correlate request logs with app logs
4. View logs
5. Test your app

Installing the Cloud Client Libraries for Cloud Logging

To install and update your configuration files, add the Cloud Client Libraries for Cloud Logging to your list of dependencies in the requirements.txt file, like the following:

 google-cloud-logging 

Write logs with the standard Python logging module

In each file that writes log entries:

1. Import the Cloud Logging client library.
2. Instantiate the Cloud Logging client .
3. Run the Cloud Logging client's setup_logging() method, which attaches its default listener as the logging handler for the Python root logger.

For example:

  # Imports the Cloud Logging client library 
 import 
  
 google.cloud.logging 
 # Instantiates a client 
 client 
 = 
 google 
 . 
 cloud 
 . 
 logging 
 . 
  Client 
 
 () 
 # Retrieves a Cloud Logging handler based on the environment 
 # you're running in and integrates the handler with the 
 # Python logging module. By default this captures all logs 
 # at INFO level and higher 
 client 
 . 
  setup_logging 
 
 () 
 

After the handler is attached, any logs at INFO level or higher which are emitted in your application will be sent to Logging by default:

  # Imports Python standard library logging 
 import 
  
 logging 
 # The data to log 
 text 
 = 
 "Hello, world!" 
 # Emits the data using the standard logging module 
 logging 
 . 
 warning 
 ( 
 text 
 ) 
 

Correlate request logs with app logs

Some features that are available in the first-generation runtimes such as, automatic correlation of request logs with app logs, are not available in the second-generation runtimes.

Apps using second-generation runtimes can achieve similar nested logging behavior to that of first-generation runtimes by either:

• Setting up the Cloud Logging client in your application and correlating logs.
• Using a trace identifier with stdout and stderr .

The logging behavior in first-generation and second-generation runtimes differ in the following ways:

• In first-generation runtimes, App Engine embeds all app logs emitted while handling a request into the protoPayload.line.logMessage field of the request log. These logs are visible in Logs Explorer through appengine.googleapis.com/request_log .

  The following image shows correlated request and app logs in the first-generation runtimes:

  

• In second-generation runtimes, App Engine omits the protoPayload.line attribute in the request log. The contents of the app logs are not present within the JSON request logs in Logs Explorer. Each app log will appear separately by its log name in Logs Explorer.

  The following image shows separate request and app logs in the second-generation runtimes:

  

The following sections covers how to either use the Cloud Logging client or structured logging with stdout and stderr for correlating logs.

Use the Python logging module

To add request-correlation to app logs logged by the Python logging module, set up the Cloud Logging client library .

When you run the client.setup_logging() method at application startup, this method adds the trace field and the HTTP request details to app logs written by the Python logging module such as, logging.info() and logging.error() . These logs are routed to logs/python .

App Engine also adds this trace field to the associated request log, which makes it possible to view correlated log entries in the Log Explorer .

Use stdout and stderr

If you use stdout and stderr to write log entries, these entries appear in the Logs Explorer. However, to enable filtering and correlation with request logs, you need to format the entries as a JSON object and provide specific metadata. For more information about this approach, see Write structured logs to stdout and stderr . This approach adds the request's trace identifier in application logs by:

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

View logs

You can view app logs and request logs in several ways:

• Use Logs Explorer from Cloud Logging in the Google Cloud console.
• Use the Google Cloud CLI to view logs using gcloud.
• Read logs programmatically using various methods.

Use Logs Explorer

You can view your app and request logs using the Logs Explorer :

1. Go to Logs Explorerin the Google Cloud console:

   Go to Logs Explorer

2. Select an existing Google Cloud project at the top of the page.

3. In Resource Type, select GAE Application.

You can filter the Logs Explorer by App Engine service, version and other criteria. You can also search the logs for specific entries. See Using the Logs Explorer for details.

If you send simple text entries to standard output, you cannot use the Logs Viewer to filter app entries by severity, nor can you see which app logs correspond to specific requests. You can still use other types of filtering in the Logs Explorer, such as text and timestamp.

View correlated log entries in the Logs Explorer

In the Logs Explorer, to view the child log entries correlated with a parent log entry, expand the log entry.

For example, to display your App Engine request log entry and application log entries, do the following:

1. In the navigation panel of the Google Cloud console, select Logging, and then select Logs Explorer:

   Go to Logs Explorer

2. In Resource Type, select GAE Application.

3. To view and correlate request logs, in Log Name, select request_log. Alternatively, to correlate by request logs, click Correlate byand select request_log.

   

4. In the Query resultspane, to expand a log entry, click Expand. On expanding, each request log will show the associated app logs.

After creating a filter for the logs, each request log shows corresponding app logs as child logs. Logs Explorer achieves this by correlating the trace field in app logs and a given request log, assuming the application uses the google-cloud-logging library.

The following image shows app logs grouped by the trace field:

Use the Google Cloud CLI

To view your App Engine logs from the command line, use the following command:

gcloud  
app  
logs  
tail

For more information, see gcloud app logs tail .

Reading logs programmatically

If you want to read the logs programmatically, you can use one of these methods:

• Use a log sink to Pub/Sub and a script to pull from Pub/Sub .
• Call the Cloud Logging API through the client library for your programming language.
• Call the Cloud Logging API REST endpoints directly.

Test your app

Migration is successful if you are able to deploy your app without errors. To verify that Cloud Logging is working, follow these steps:

1. Go to Logs Explorer and expand a request log entry.

   Go to Logs Explorer

2. Ensure that the app logs generated by your app when processing a request, are nested within the request log.

3. If all your app endpoints work as expected, use traffic splitting to slowly ramp up traffic for your updated app. Monitor the app closely for any issues before routing more traffic to the updated app.