使用 Google Stackdriver Debug、Trace、Logging 和 Logpoints

本教程将带您了解 Google Stackdriver，借助该工具，您可以对 Google Cloud Platform 应用执行以下操作：

• 在 App Engine、Compute Engine 和 Container Engine 上运行的应用中拍摄调试快照。
• 查看应用日志。
• 设置指标、监控指标并接收提醒。
• 跟踪 API 调用，并详细了解响应时间和代码中可能存在的瓶颈。
• 向正在运行的应用添加日志点，而无需部署应用。这是一项非常独特（且希望有用）的功能。

在本教程中，我们将从头开始执行以下操作：

1. 创建 Google Cloud Platform 项目（专门用于 App Engine）
2. 设置 Google Cloud Platform 项目源代码库
3. 利用 GitHub 上提供的标准留言簿 Python 应用源代码
4. 部署代码
5. 了解如何获取正在运行的应用的调试快照
6. 查看日志记录和应用调用轨迹
7. 向当前正在运行的应用添加日志点。此功能最初是在这篇博文中介绍的：无需重启即可向应用添加应用日志

让我们开始吧。

此内容最初由 Romin Irani 创作，并发布在此处。

自定进度的环境设置

如果您还没有 Google 账号（Gmail 或 Google Apps），则必须创建一个。登录 Google Cloud Platform Console (console.cloud.google.com) 并创建一个新项目：

请记住项目 ID，它在所有 Google Cloud 项目中都是唯一名称（很抱歉，上述名称已被占用，您无法使用！）。它稍后将在此 Codelab 中被称为 PROJECT_ID。

接下来，您需要在 Cloud Console 中启用结算功能，才能使用 Google Cloud 资源。

在此 Codelab 中运行仅花费几美元，但是如果您决定使用更多资源或继续让它们运行，费用可能更高（请参阅本文档末尾的“清理”部分）。

Google Cloud Platform 的新用户有资格获享 $300 免费试用。

Google Cloud Shell

在此 Codelab 中，我们将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

基于 Debian 的这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。这意味着在本 Codelab 中，您只需要一个浏览器（没错，它适用于 Chromebook）。

如需激活 Google Cloud Shell，只需在开发者控制台中点击右上角的按钮（预配和连接到环境仅需花费一些时间）：

然后，接受服务条款并点击“启动 Cloud Shell”链接：

连接到 Cloud Shell 后，您应该会看到自己已通过身份验证，并且相关项目已设置为您的 PROJECT_ID：

gcloud auth list

命令输出

Credentialed accounts:
 - <myaccount>@<mydomain>.com (active)

注意：gcloud 是用于 Google Cloud Platform 的一款强大的统一命令行工具。如需获取完整文档，请访问 https://cloud.google.com/sdk/gcloud。它会预先安装在 CloudShell 上，相信您一定会喜欢它对 Tab 键自动补全功能的支持。

gcloud config list project

命令输出

[core]
project = <PROJECT_ID>

如果出于某种原因未设置项目，只需发出以下命令即可：

gcloud config set project <PROJECT_ID>

正在查找您的 PROJECT_ID？检查您在设置步骤中使用的 ID，或在控制台信息中心查找该 ID：

重要提示：最后，设置默认可用区和项目配置：

gcloud config set compute/zone us-central1-f

您可以选择各种不同的可用区。如需了解详情，请参阅“区域和地区”说明文档。

注意：当您在自己的机器上运行 gcloud 时，配置设置将在会话之间保持不变。但是在 Cloud Shell 中，您将需要为每个新会话或重新连接配置此设置。

查看已启用的 StackDriver API

我们来看看已为您的项目启用的 API。使用搜索栏查找 API 信息中心，如下所示。

查看已为您的项目启用的特定 API：

每个 Google Cloud Platform 项目都提供私有 Git 托管服务，但我们首先需要创建一个默认代码库才能使用。使用控制台搜索框前往“源代码库”：

点击“CREATE REPOSITORY”（创建代码库）以创建名为“default”的新代码库：

接下来，我们将使用 Cloud Shell 将此目录克隆到我们的 Google Cloud Shell 实例中。为此，我们先在 Google Cloud Shell 实例中创建一个目录，然后前往该目录，如下所示（示例输出）：

mkdir stackdriver-demo

cd stackdriver-demo/

现在，我们可以通过 gcloud 命令克隆此处的默认代码库，如下所示：

gcloud source repos clone default

您应该会看到以下控制台输出：

Cloning into '/home/gcp123_student/default'...
warning: You appear to have cloned an empty repository.
Project [qwiklabs-gcp-1234abc1234] repository [default] was cloned to [/home/gcp123_student/default].

太棒了！我们花点时间来深入了解一下已设置的 Git 远程代码库。这并非必要，只是为了让您更好地了解后台发生的情况。

前往创建的默认目录，然后运行 git remote -v 命令，如下所示

cd default

git remote -v

您应该会看到类似于以下内容的控制台输出：

origin https://source.developers.google.com/p/qwiklabs-gcp-1234abc1234/r/default (fetch)
origin https://source.developers.google.com/p/qwiklabs-gcp-1234abc1234/r/default (push)

您可以看到，此文件正确指向与我们的 GCP 项目关联的 Git 代码库。

从 GitHub 拉取留言板应用

我们将要使用的应用是一个名为 Guestbook 的标准 App Engine 应用，可在官方 Google Cloud Platform GitHub 代码库中找到。此应用也是官方入门文档的一部分。GitHub 项目位于：https://github.com/GoogleCloudPlatform/appengine-guestbook-python

现在，我们将此代码拉取到 Cloud Shell 实例中。该命令及其输出如下所示：

git pull https://github.com/GoogleCloudPlatform/appengine-guestbook-python

您应该会看到以下控制台输出：

remote: Counting objects: 485, done.
remote: Total 485 (delta 0), reused 0 (delta 0), pack-reused 485
Receiving objects: 100% (485/485), 436.42 KiB | 163.00 KiB/s, done.
Resolving deltas: 100% (195/195), done.
From https://github.com/GoogleCloudPlatform/appengine-guestbook-python
* branch HEAD -> FETCH_HEAD

现在，我们已将所有代码都放在 Google Cloud Shell 实例本地。您可以看到已从 GitHub 项目中提取的各种文件。

使用 Cloud Shell 将当前代码推送到项目 Git 代码库

现在，我们将此代码推送到 GCP 项目 Git 代码库中，以便为代码设置断点、日志点等。请注意，这不是必需的步骤，因为您可以直接与 GitHub、本地机器集成，也可以通过其他方式关联源代码。

但就本文档的目的而言，我们将把此代码推送到 GCP 项目 Git 代码库。为此，请使用标准 git push 命令，如下所示：

git push origin master

您应该会看到以下控制台输出：

Counting objects: 485, done.
Compressing objects: 100% (280/280), done.
Writing objects: 100% (485/485), 436.42 KiB | 0 bytes/s, done.
Total 485 (delta 195), reused 485 (delta 195)
remote: Storing objects: 100% (485/485), done.
remote: Processing commits: 100% (152/152), done.
To https://source.developers.google.com/p/qwiklabs-gcp-1234abc1234/r/default
* [new branch] master -> master

现在，返回 GCP Cloud 控制台，具体来说是返回“开发”部分。点击“源代码”，您应该能够看到默认代码库中的所有项目文件。输出示例如下所示：

现在，我们已准备好部署留言板 App Engine 应用。如需部署应用，请确保您位于 Google Cloud Shell 中，并且位于我们一直使用的默认目录中。使用 gcloud app deploy 命令，如下所示：

gcloud app deploy --version 1

当系统要求您选择区域时，请选择 [1] us-east1。

您应该会看到以下控制台输出：

You are about to deploy the following services:
— qwiklabs-gcp-1234abc1234/default/1 (from [/home/gcp123-student/default/app.yaml])
Deployed URL: [https://qwiklabs-gcp-1234abc1234.appspot.com]
Do you want to continue (Y/n)? Y
Beginning deployment of service [default]...
File upload done.
Updating service [default]...done.
Deployed service [default] to https://qwiklabs-gcp-1234abc1234.appspot.com]

请注意，我们为应用部署命令提供了版本参数。我们为其赋予了 "1" 的值。

由于 Guestbook 应用使用 Google Cloud Datastore 进行持久化，因此我们需要更新 Datastore 索引。指数在 index.yaml 文件中指定，我们只需使用 gcloud datastore create-indexes 命令，如下所示：

gcloud datastore create-indexes index.yaml

您应该会看到以下控制台输出：

You are about to update the following configurations:
— qwiklabs-gcp-1234abc1234/index From: [/home/gcp123_student/default/index.yaml]
Do you want to continue (Y/n)? Y

数据存储区索引可能需要一段时间才能更新。如需查看状态，请搜索“Datastore 索引”，然后点击“索引”。在构建索引期间，您会看到状态的值为“正在编制索引”，如下所示：

我们可以前往“Compute”（计算）→“App Engine”，然后点击“Versions”（版本），检查版本 1 的应用是否已部署并可供使用，如下所示：

现在一切应该都正常了，您可以前往 https://<PROJECT_ID>.appspot.com 查看项目。同样，数据存储区索引可能需要几分钟才能准备就绪，因此如果应用显示错误（例如：内部服务器错误），请稍后再试。

现在，我们登录应用并创建一些留言板条目，如下所示：

太棒了！现在，我们已准备好深入了解 Stackdriver 功能。

我们先来看看如何为正在运行的应用拍摄快照。如果您想调试特定代码、检查变量等，快照会非常有用。这一切都会在应用仍在提供服务时发生。如果您收到有关应用问题的报告，并想尝试调试并了解应用发生了什么情况，检查大量变量，有条件地拍摄快照等，此功能会非常有用。

现在，我们来为留言板应用执行此操作。如果有人请求首页，我们将请求快照，具体来说，我们希望快照能够检索 Datastore 中当前存在的问候语列表。

相应代码位于 guestbook.py 文件中。具体来说，我们希望在代码从数据存储区检索到问候语列表后，立即开始在运行时检查代码。此操作在第 72 行完成。因此，我们只需在第 74 行设置一个断点，即可知道第 72 行是否已执行。

为此，您可以点击 AppEngine 版本视图中的“调试”，也可以前往 Stackdriver → 调试。系统会显示如下所示的界面。您需要做的是选择左侧的文件 (guestbook.py)，然后点击行号，如图所示。

系统会显示一条消息（如上方的红色方框所示），表明正在等待触发快照。现在，我们只需访问以下网址即可开始使用该页面：

https://<PROJECT_ID>.appspot.com。

完成上述操作后，快照将处于有效状态，您会看到“变量”和“调用堆栈”部分填充了内容，如下所示。查看变量的显示方式，您可以展开变量来检查值。这非常有用。

例如，如果您展开问候语变量，您会看到它包含与您创建的留言簿条目数量相对应的记录。

一项非常实用的功能是随时重新拍摄快照。只需随时点击相机图标，系统就会再次等待快照命中，如下所示：

您可以按照以下方式使用“表达式”字段来跟踪特定变量。例如，我们知道自己有一个变量 greetings，并且希望在命中快照时检查其值。我们可以放入问候语变量，如下面的屏幕截图所示。当命中快照时，系统会使用所示的值填充快照。

如果您希望仅在满足特定条件时激活快照，则可以使用“条件”字段，如下所示。这里表示，只有当问候语的数量大于 1 时，才应拍摄快照。您可以根据需要尝试此功能。

注意 ：如需 Stackdriver Debugger 的完整文档，请访问以下网址：https://cloud.google.com/debugger/docs/

请务必确保您的 Web 应用性能符合您设定的要求。Stackdriver Trace 是一款关键工具，可帮助您了解应用中的延迟时间。

默认情况下，所有 App Engine 应用都会启用此功能，它会提供所有端点非常实用的性能详细信息，以及各种调用的细分数据。

在本例中，我们一直在访问首页 (“/”) 并查看 / 添加 Guestbook 条目。这足以让 Trace 告诉我们有关延迟时间的更多信息。只需前往 Stackdriver Traces 概览，即可看到如下所示的屏幕截图。请注意近期的跟踪记录及其延迟时间。

如果我们点击任何一个轨迹（即点击 URI 链接），系统会显示如下所示的详细轨迹：

请注意，它能够细分延迟时间，并显示哪些调用花费的时间最长。从上面的可视化图表中可以看出，数据存储区查询需要花费时间。或许可以考虑缓存数据来缓解这一瓶颈。同样，这一切都取决于您的应用，这对于确定调用轨迹中可能需要重构的区域非常有用。

注意 ：如需查看完整的 Stackdriver Trace 文档，请访问：https://cloud.google.com/trace/docs/

您可以随时查看应用日志，只需前往 Stackdriver Logging（如下所示）。您可以从各种 GCP 服务开始，依次选择日志类型、日志级别、日期等，使用多种过滤器。

以下屏幕截图显示了我们的 App Engine 应用和默认版本 1 的日志。

注意 ：如需查看完整的 Stackdriver Logging 文档，请访问：https://cloud.google.com/logging/docs/

最后，我们来看看一项功能，它应该会让您对它所提供的可能性感到兴奋。通常，作为开发者，我们会尽最大努力在代码中放置日志语句，部署代码，然后希望日志能告诉我们想要知道的一切。

但我们知道这还不够，只有在调试时，我们才会意识到或许应该在各处添加更多日志语句。然后，通常的工作流程是修改代码、添加额外的日志语句、重新部署并进行监控。

这当然没问题，但如果您能将这些日志语句（我们现在称之为日志点）添加到正在运行的应用中，会怎么样呢？这意味着我们无需执行停止应用、更改代码和重新部署的流程。不过，我们可以使用 logpoints 支持从应用外部管理日志点列表。

仍在 Cloud Shell 中，我们来检查一下当前配置的日志点列表（显然应该是 0）。这是通过 gcloud 命令完成的，如下所示：

gcloud debug logpoints list

您应该会看到以下控制台输出：

Debug target not specified. Using default target: default-1
Listed 0 items.

现在，我们将向正在运行的应用添加日志点。如需添加日志点，我们需要执行以下操作：

• 确定要添加日志点的源代码文件和行号。
• 确定日志消息。此日志消息可以是硬编码，也可以是表达式。

在本例中，我们将通过 logpoints create 命令在 guestbook.py 文件的第 74 行添加一个日志点，如下所示：

gcloud debug logpoints create guestbook.py:74 "Fetched greetings from Datastore. Count of greetings : {len(greetings)}"

您应该会看到以下控制台输出：

Debug target not specified. Using default target: default-1
— id: 53538243519d4-f9a0-bdbce
location: guestbook.py:74
logLevel: INFO
logMessageFormat: Fetched greetings from Datastore. Count of greetings : {len(greetings)}
condition: None
status: ACTIVE

我们提供了 filename:linenumber 和上面的日志消息。请注意，我们的日志消息还包含一个表达式，用于输出从数据存储区检索到的问候语数量。

该命令会返回一条消息，表明已添加日志点。以下是我们 Cloud Shell 的屏幕截图：

现在，如果您运行 logpoints list 命令，您将看到以下输出：

gcloud debug logpoints list

您应该会看到以下控制台输出：

Debug target not specified. Using default target: default-1
STATUS LOCATION CONDITION LOG_LEVEL LOG_MESSAGE_FORMAT ID
ACTIVE
guestbook.py:74 INFO Fetched greetings from Datastore. Count of greetings : {len(greetings)} 53538243519d4-f9a0-bdbce

若要查看其实际效果，我们可以再次访问 https://<PROJECT_ID>.appspot.com 处的首页。这会调用代码，进而调用我们的日志点。请注意，此操作默认会记录在我们的应用日志中。因此，我们只需再次访问 Stackdriver Logging，如下所示：

点击相应请求，然后就完成了！在详细信息中，您会看到我们的日志点被触发，并显示日志消息。

希望您喜欢本教程。本文仅介绍了 Stackdriver 平台提供的一些功能。还有更多精彩内容等你来探索。如需查看更多 Google Cloud Platform 教程，请访问 Romin Irani 的博客（本 Codelab 的原作者），网址为 https://rominirani.com/。

您还可以查看另一篇名为“使用 Stackdriver 的监控和日志记录功能深入了解应用的运行状况”的 Codelab。

如果您有任何反馈意见，或者想报告此 Codelab 的相关问题，请使用此页面左下角的“请发现 bug”链接。