迁移到 Cloud Logging

只需几行代码，您就可以将应用更新为使用 Cloud Logging，并实现几乎与 App Engine 日志记录服务相同的过滤和日志关联功能。

要迁移到 Cloud Logging，请将 AppEngineHandler 日志处理程序连接到 Python 日志记录模块，然后继续使用 Python 日志记录模块写入日志条目。您可以在 Python 2 应用中进行这些更新，并在您的应用在 Python 2 或 Python 3 运行时中运行相同的日志记录行为。

App Engine 日志记录与 Cloud Logging 之间的主要区别

• App Engine 日志记录要求您使用 Python 日志记录模块写入应用日志条目。Cloud Logging 支持以下所有方法：

  • （推荐）使用 Python 日志记录模块，其中将 AppEngineHandler 用作日志记录处理程序。这种惯用的方法只需要几行额外的代码行即可注册 Cloud Logging 处理程序，因此可以提高您的应用在其他 Python 环境中的可移植性。

  • 将条目写入 stdout 或 stderr。这些条目显示在日志浏览器中，但要启用过滤和关联请求日志，您需要将条目设置为 JSON 对象格式并提供特定的元数据。如需详细了解此方法，请参阅结构化日志记录。

  • 直接使用 Cloud Logging 客户端库。如果您使用 AppEngineHandler，则此方法可实现与使用 Python 日志记录模块相同的结果，但从此库更改为其他日志记录框架可能需要对代码进行重大更新。

• 使用 App Engine 日志记录时，日志浏览器会为请求日志分配严重级别，严重级别表示与请求关联的任何应用日志条目的最高严重级别。例如，如果请求导致您的应用发出警告日志条目，则日志浏览器会在请求日志条目旁边显示一个警告图标。展开请求条目时，您会看到请求条目内嵌套的警告日志条目。

  使用 Cloud Logging 时，日志查看器不会向请求日志分配严重级别。展开请求条目后，您会看到请求条目内嵌套的应用条目，并且这些应用条目会显示严重度图标。但是，请求条目本身不会显示严重度图标，也无法按严重级别进行过滤。

• App Engine 和 Cloud Logging 的配额和数据保留是相同的，但如果您超过日志数据的免费配额，则 Cloud Logging 价格可能与 App Engine 日志价格不同。

开始迁移之前

1. 在包含您的应用的项目中启用 Cloud Logging API。

   启用该 API

2. 确保您的应用有权写入日志。

   默认情况下，应用的默认服务帐号有权写入日志。

   如果您的应用使用其他服务帐号或用户帐号，或者您更改了默认服务帐号的权限，请确保您使用的帐号具有写入日志的权限。

迁移过程概览

要迁移 Python 应用以使用 Cloud Logging 而不是 App Engine 日志记录，请执行以下操作：

1. 安装 Cloud Logging 的 Cloud 客户端库。

2. 将 AppEngineHandler 连接到 Python 日志记录模块。

3. 将您的应用部署到 App Engine，并确认日志记录是否按预期正常运行。

安装 Cloud Logging 的 Cloud 客户端库

要让 AppEngineHandler 在您的应用在 App Engine 中运行时对其可用，请执行以下操作：

1. 在 app.yaml 文件所在的文件夹中创建 requirements.txt 文件，并添加以下行：

    google-cloud-logging==1.14.0
   

   我们建议您使用 1.14.0 版的 Cloud Logging 客户端库，因为它支持 Python 2.7 应用。

2. 在应用的 app.yaml 文件的 libraries 部分中指定所需的 Google RPC 和 setuptools 库以及可选 SSL 库：

   libraries:
   - name: grpcio
     version: 1.0.0
   - name: setuptools
     version: 36.6.0
   - name: ssl
     version: latest
   

   某些客户端库不需要 SSL 库。如果您没有为需要 SSL 库的客户端库添加 SSL 库，当您的应用收到请求时，您会在日志浏览器中看到 SSL 错误。

3. 创建一个用于存储第三方库的目录，如 lib/。然后使用 pip install 将库安装到该目录中。 例如：

     pip install -t lib -r requirements.txt
     

4. 在 app.yaml 文件所在的文件夹中创建 appengine_config.py 文件。将以下内容添加到 appengine_config.py 文件：

   # appengine_config.py
   import pkg_resources
   from google.appengine.ext import vendor
   
   # Set path to your libraries folder.
   path = 'lib'
   # Add libraries installed in the path folder.
   vendor.add(path)
   # Add libraries to pkg_resources working set to find the distribution.
   pkg_resources.working_set.add_entry(path)
   

   上例中的 appengine_config.py 文件假定 lib 文件夹位于当前工作目录中。如果您无法保证 lib 始终位于当前工作目录中，请指定 lib 文件夹的完整路径。例如：

   import os
   path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
   

对于本地开发，我们建议您在虚拟环境（如 Python 2 的 virtualenv）中安装依赖项。

将 AppEngineHandler 连接到 Python 日志记录模块

在写入日志条目的每个文件中：

1. 导入 Cloud Logging 客户端库。
2. 实例化 Cloud Logging 客户端。

3. 检索适合当前环境的 Cloud Logging 处理程序。当您的应用在 App Engine 中运行时，Cloud Logging 客户端会检索 AppEngineHandler。

   AppEngineHandler 会将这些条目格式化为 JSON 对象，并提供所需的元数据，以支持按严重度进行过滤并将您的应用条目与请求日志条目相关联。

4. 运行 Cloud Logging 客户端的 setup_logging() 方法，该方法会将其默认监听器作为 Python 根日志记录器的日志记录处理程序进行连接。

例如：

samples/snippets/handler.py

在 GitHub 上查看

# 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()

连接处理程序后，应用中生成的所有处于INFO 级别或更高级别的日志都将默认发送至 Logging：

samples/snippets/handler.py

在 GitHub 上查看

# 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)

部署应用

准备好部署应用后，您应该执行以下操作：

1. 在 App Engine 上测试应用。

   要测试更新并确认已指定严重级别并将应用条目与请求条目关联，唯一的方法是将应用部署到 Python 3 运行时。

   如果您将更新部署到 Python 2 运行时，App Engine 日志记录服务将侦听来自 Python 根日志记录器的条目，并为日志浏览器设置相应格式。

   如果您在本地运行应用，则 Cloud Logging 不使用 AppEngineHandler，并且 App Engine 无法写入请求条目。

2. 查看日志浏览器，并确认已为应用的条目分配严重级别。展开请求条目，并确认您的应用在处理请求时写入的条目是否嵌套在请求条目下方。

3. 如果应用运行正常（没有错误），请使用流量拆分功能为更新后的应用缓慢增加流量。请先仔细监控应用是否存在任何问题，然后再将更多流量路由到更新后的应用。