迁移到 Cloud Logging

第二代运行时中的日志记录与第一代运行时不同。升级到较新版本的运行时后，最大的变化之一是第二代运行时不支持与 App Engine 预先集成的日志记录，且日志不会自动关联。如果您要迁移到第二代运行时，则必须使用 Cloud Logging 客户端库。

本指南介绍了如何更新应用以使用 Cloud Logging，并实现几乎与 App Engine 中的日志记录集成相同的过滤和日志关联功能。

Cloud Logging 是一个实时日志管理系统，支持存储、搜索、分析和监控。Cloud Logging 会自动从 Google Cloud 资源中收集日志。您还可以从应用、本地资源以及从其他云提供商资源收集日志。

主要区别

下表介绍了第一代和第二代运行时在日志记录方面的差异：

	第一代运行时	第二代运行时
请求和应用日志（也称为应用程序日志）	App Engine 会将所有应用日志嵌入请求日志中。第一代运行时中的日志记录使用请求日志的 protoPayload.line.logMessage 字段来嵌入应用日志。	App Engine 不会在关联的请求日志中嵌入应用日志。App Engine 会忽略请求日志中的 protoPayload.line 属性。应用日志根据您的记录方法进行路由： stdout 和 stderr：将日志（如 print()）路由到 logs/stdout 或 logs/stderr。 设置 Cloud Logging 客户端后的 Python 日志记录模块：将 logging.info() 和 logging.error() 等 Python 根日志记录模块撰写的所有日志路由到 logs/python。 如果 Python 版 Cloud Logging 客户端库未设置相关性，则 Python 根日志记录模块默认路由到 logs/stderr。
在 Logs Explorer 中查看日志	第一代运行时仅包含一种日志类型 appengine.googleapis.com/request_log。展开请求日志后，您可以看到其下方嵌套的应用日志。	第二代运行时包含来自多种日志类型（例如 appengine.googleapis.com/request_log、stdout、stderr、logs/python 等等）的日志，具体取决于应用发出日志的方式。您还可以在 /var/log/google_init.log 中找到 Google 内部日志。 由于应用日志不会自动与请求日志关联，因此需要执行其他步骤以在 Logs Explorer 中显示请求和应用日志的嵌套视图。如需了解详情，请参阅将请求日志与应用日志相关联以及在 Logs Explorer 中查看相关日志。
Cloud Trace 集成	与 Cloud Trace 自动集成，以便收集延迟数据。	必须手动将应用与 Cloud Trace 集成，才能从 App Engine 收集延迟时间数据。如需了解详情，请参阅对 Cloud Trace 进行插桩。
错误级别相关性	记录在 App Engine 请求日志中抛出的具有 ERROR 严重级别的错误。Error Reporting 会自动在 Error Reporting 信息中心内关联这些详细信息。	默认情况下，App Engine 不会在第二代运行时中集成 Error Reporting。如需设置与 Error Reporting 的日志记录集成，请参阅使用客户端库对应用进行插桩处理。
严重级别	Logs Explorer 会为请求日志分配严重级别，严重级别表示与请求日志条目关联的任何应用日志条目的最高严重级别。例如，如果请求导致您的应用发出警告日志条目，则日志浏览器会在请求日志条目旁边显示一个警告图标。展开请求条目时，您会看到请求条目内嵌套的警告日志条目。	默认情况下，所有请求日志的严重级别均为 DEFAULT 或 INFO。即使您的请求日志与应用日志相关联，并且 Logs Explorer 配置为查看相关日志，请求日志也不会反映关联应用日志的严重性。
Logservice API	Logservice API 是捆绑服务 SDK 的一部分。	已从捆绑服务 SDK 中移除 Logservice API。如需了解详情，请参阅可用 API 列表。

开始迁移之前

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

   启用该 API

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

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

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

3. 熟悉 App Engine 中不同类型的日志。

迁移过程概览

如需迁移应用以使用 Cloud Logging，请执行以下操作：

1. 安装适用于 Cloud Logging 的 Cloud 客户端库
2. 使用 Cloud Logging 写入日志
3. 将请求日志与应用日志相关联
4. 查看日志
5. 测试应用

安装 Cloud Logging 的 Cloud 客户端库

如需安装和更新配置文件，请将 Cloud Logging 的 Cloud 客户端库添加到 requirements.txt 文件中的依赖项列表，如下所示：

google-cloud-logging

使用标准 Python 日志记录模块写入日志

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

1. 导入 Cloud Logging 客户端库。
2. 实例化 Cloud Logging 客户端。
3. 运行 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.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)

将请求日志与应用日志相关联

第一代运行时中可用的某些功能（例如自动关联请求日志与应用日志）在第二代运行时中不可用。

使用第二代运行时的应用可通过以下任一方式实现与第一代运行时类似的嵌套日志记录行为：

• 在应用中设置 Cloud Logging 客户端并关联日志。
• 将 trace 标识符与 stdout 和 stderr 搭配使用。

第一代和第二代运行时中的日志记录行为在以下方面有所不同：

• 在第一代运行时中，App Engine 会将处理请求时发出的所有应用日志嵌入到请求日志的 protoPayload.line.logMessage 字段中。这些日志可通过 appengine.googleapis.com/request_log 在 Logs Explorer 中查看。

  下图显示了第一代运行时中的相关请求和应用日志：

  

• 在第二代运行时中，App Engine 会忽略请求日志中的 protoPayload.line 属性。应用日志的内容不在 Logs Explorer 的 JSON 请求日志中。在 Logs Explorer 中，每个应用日志将按其日志名称单独显示。

  下图显示了第二代运行时中的单独的请求和应用日志：

  

以下部分介绍了如何将 Cloud Logging 客户端或结构化日志记录与 stdout 和 stderr 搭配使用来关联日志。

使用 Python 日志记录模块

如需向 Python 日志记录模块记录的应用日志添加请求相关性，请设置 Cloud Logging 客户端库。

如果您在应用启动时运行 client.setup_logging() 方法，此方法会将 trace 字段以及 HTTP 请求详细信息写入 logging.info() 和 logging.error() 等 Python logging 模块撰写的应用日志。这些日志将路由到 logs/python。

App Engine 还会将此 trace 字段添加到关联的请求日志中，以便在 Logs Explorer 中查看相关日志条目。

使用 stdout 和 stderr

如果您使用 stdout 和 stderr 写入日志条目，则这些条目会显示在 Logs Explorer 中。但是，要启用过滤和关联请求日志，您需要将条目设置为 JSON 对象格式并提供特定的元数据。如需详细了解此方法，请参阅将结构化日志写入 stdout 和 stderr。此方法通过以下方式在应用日志中添加请求的跟踪记录标识符：

1. 从 X-Cloud-Trace-Context 请求标头中提取跟踪记录标识符。
2. 将 ID 写入结构化日志条目中名为 logging.googleapis.com/trace 的字段。如需详细了解 X-Cloud-Trace-Context 标头，请参阅强制跟踪请求。

查看日志

您可以通过多种方式查看应用日志和请求日志：

• 在 Google Cloud 控制台中，通过 Cloud Logging 使用 Logs Explorer。
• 使用 Google Cloud CLI 通过 gcloud 查看日志
• 使用各种方法以编程方式读取日志。

使用 Logs Explorer

您可以使用 Logs Explorer 查看您的应用和请求日志：

1. 在 Google Cloud 控制台中打开 Logs Explorer。

   转到日志浏览器

2. 在页面顶部选择一个现有 Google Cloud 项目。

3. 在资源类型中，选择 GAE 应用。

您可以按 App Engine 服务、版本和其他条件过滤日志浏览器。您还可以在日志中搜索特定条目。如需了解详情，请参阅使用日志浏览器。

如果您向标准输出发送简单文本条目，则无法使用日志查看器按严重程度过滤应用条目，也无法查看与特定请求对应的应用日志。您仍然可以在日志浏览器中使用其他类型的过滤，例如文本和时间戳。

在 Logs Explorer 中查看相关日志条目

在 Logs Explorer 中，如需查看与父级日志条目关联的子日志条目，请展开日志条目。

例如，要显示 App Engine 请求日志条目和应用日志条目，请执行以下操作：

1. 在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择 Logs Explorer：

   转到日志浏览器

2. 在资源类型中，选择 GAE 应用。

3. 如需查看和关联请求日志，请在日志名称中选择 request_log。或者，如需按请求日志进行关联，请点击关联依据，然后选择 request_log。

   

4. 在查询结果窗格中，如需展开日志条目，请点击展开。展开后，每个请求日志都会显示关联的应用日志。

为日志创建过滤条件后，每个请求日志会将相应的应用日志显示为子日志。为实现此目的，Logs Explorer 会将应用日志中的 trace 字段与给定请求日志相关联（假设应用使用 google-cloud-logging 库）。

下图显示了按 trace 字段分组的应用日志：

使用 Google Cloud CLI

如需从命令行查看 App Engine 日志，请使用以下命令：

gcloud app logs tail

如需了解详情，请参阅 gcloud app logs tail。

以编程方式读取日志

如果要以编程方式读取日志，可以使用以下方法之一：

• 使用到 Pub/Sub 的日志接收器和脚本从 Pub/Sub 中拉取。
• 通过与您的编程语言对应的客户端库调用 Cloud Logging API。
• 直接调用 Cloud Logging API REST 端点。

了解实例扩缩日志

为您的应用启动新实例后，Cloud Logging 会在 varlog/system 日志名称下添加日志条目，以反映创建每个实例的原因。日志条目遵循以下格式：

Starting new instance. Reason: REASON - DESCRIPTION

下表详细介绍了实例说明：

原因	说明
CUSTOMER_MIN_INSTANCE	客户为应用配置的实例数下限。
SCHEDULED	由于配置的扩缩因子（例如，CPU 利用率、请求吞吐量等）及其目标而启动实例。
OVERFLOW	由于未找到适合当前流量的现有容量而启动实例。

测试您的应用

如果您能够部署应用并且没有出现错误，则迁移成功。如需验证 Cloud Logging 是否正常运行，请按照以下步骤操作：

1. 转到 Logs Explorer 并展开请求日志条目。

   转到日志浏览器

2. 确保应用在处理请求时生成的应用日志嵌套在请求日志中。

3. 如果所有应用端点都按预期运行，请使用流量拆分为更新后的应用缓慢增加流量。请先仔细监控应用是否存在任何问题，若无再将更多流量路由到更新后的应用。