Python 2 不再受社区支持。我们建议您将 Python 2 应用迁移到 Python 3

迁移到 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 环境中的可移植性。

    • 将条目写入 stdoutstderr。这些条目显示在日志浏览器中,但要启用过滤和关联请求日志,您需要将条目设置为 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
     googleapis_common_protos
    

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

    Python 2 应用需要 googleapis_common_protos 才能访问 Google Cloud 服务

  2. 在您应用的 app.yaml 文件的 libraries 部分中,指定 Google RPC 和 SSL 库:

    libraries:
    - name: grpcio
      version: 1.0.0
    - name: ssl
      version: latest
    
  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 根日志记录器的日志记录处理程序进行连接。

例如:

# 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.get_default_handler()
client.setup_logging()

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

# 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. 如果应用运行正常(没有错误),请使用流量拆分功能为更新后的应用缓慢增加流量。请先仔细监控应用是否存在任何问题,然后再将更多流量路由到更新后的应用。