使用 Python 脚本写入和查询日志条目

本快速入门介绍 Cloud Logging 的一些功能，并展示如何执行以下操作：

  • 使用 Python 脚本写入日志条目。
  • 使用 Python 脚本查看日志条目。
  • 使用 Python 脚本删除日志条目。
  • 将日志路由到 Cloud Storage 存储桶。

Logging 可以将日志条目路由到以下目标位置：

  • Cloud Storage 存储分区
  • BigQuery 数据集
  • Pub/Sub
  • Logging 存储桶
  • Google Cloud 项目

准备工作

您必须有启用了结算功能的 Google Cloud 项目才能完成此快速入门。如果您没有 Google Cloud 项目，或者没有为 Google Cloud 项目启用结算功能，请执行以下操作：
  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

  2. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

    转到“项目选择器”

  3. 确保您的 Google Cloud 项目已启用结算功能。

  4. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

    转到“项目选择器”

  5. 确保您的 Google Cloud 项目已启用结算功能。

本快速入门使用 Cloud Logging 和 Cloud Storage。使用这些资源可能会产生费用。完成此快速入门后，您可以通过删除创建的资源来避免继续计费。如需了解详情，请参阅本页面上的清理。

使用入门

您可以使用 Cloud Shell 环境或通用 Linux 环境来完成本快速入门。 Cloud Shell 中预安装了 Python。

Cloud Shell

  1. 打开 Cloud Shell 并验证您的 Google Cloud 项目配置：

    1. 在 Google Cloud 控制台中，点击激活 Cloud Shell：

      在 Google Cloud 控制台中，点击 Cloud Shell 图标。

      Cloud Shell 将在一个窗口中打开并显示欢迎辞：

      “欢迎使用 Cloud Shell”消息。

    2. 欢迎辞会回显已配置的 Google Cloud 项目 ID。如果这不是您要使用的 Google Cloud 项目，请在将 PROJECT_ID 替换为您的项目 ID 后运行以下命令：

       gcloud config set project PROJECT_ID

Linux

  1. 确保已安装并配置 Python。如需了解如何为 Python 开发准备机器，请参阅设置 Python 开发环境。

  2. 安装 Cloud Logging 客户端库：

    pip install --upgrade google-cloud-logging

  3. 为您的 Google Cloud 项目设置 Identity and Access Management 权限。在以下步骤中，您将为 Google Cloud 项目创建服务帐号，然后生成文件并将其下载到 Linux 工作站。

    1. 在 Google Cloud 控制台的导航面板中，选择 IAM 和管理，然后选择服务帐号：

      转到服务帐号

    2. 选择快速入门 Google Cloud 项目，然后点击创建服务帐号：

      • 输入账号名称。
      • 输入账号说明。
      • 点击创建并继续。

    3. 点击选择角色字段，然后选择 Logging Admin。

    4. 点击完成以完成服务账号的创建过程。

    5. 创建密钥文件并将其下载到您的工作站：

      • 对于您的服务帐号，请点击 更多选项，然后选择管理密钥。
      • 在密钥窗格中，点击添加密钥。
      • 点击创建新密钥。

      • 对于密钥类型，选择 JSON，然后点击创建。片刻之后，弹出式窗口会显示如下所示的消息：

        私钥已保存到您的计算机。

  4. 在 Linux 工作站上，通过将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为密钥文件的路径，向您的应用提供身份验证凭据。例如：

     export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/FILE_NAME.json"

    此环境变量仅适用于当前的 Shell 会话，因此，如果您打开新的会话，请重新设置此变量。

克隆源代码

如需为本快速入门配置 Cloud Shell，请执行以下操作：

  1. 克隆 GitHub 项目 python-logging：

      git clone https://github.com/googleapis/python-logging

    目录 samples/snippets 包含在本快速入门中使用的两个脚本：

    • snippets.py 可用于管理日志中的条目。
    • export.py 可用于管理日志导出。

  2. 切换到 snippets 目录：

      cd python-logging/samples/snippets

写入日志条目

snippets.py 脚本使用 Python 客户端库将日志条目写入 Logging。如果命令行中指定了 write 选项，脚本将写入以下日志条目：

  • 包含非结构化数据且未指定严重级别的条目。
  • 包含非结构化数据且严重级别为 ERROR 的条目。
  • 包含 JSON 结构化数据且未指定严重级别的条目。

要将新日志条目写入日志 my-log，请运行带 write 选项的 snippets.py 脚本：

python snippets.py my-log write

查看日志条目

要在 Cloud Shell 中查看日志条目，请运行带 list 选项的 snippets.py 脚本：

python snippets.py my-log list

该命令完成时会返回以下结果：

    Listing entries for logger my-log:
    * 2018-11-15T16:05:35.548471+00:00: Hello, world!
    * 2018-11-15T16:05:35.647190+00:00: Goodbye, world!
    * 2018-11-15T16:05:35.726315+00:00: {u'favorite_color': u'Blue', u'quest': u'Find the Holy Grail', u'name': u'King Arthur'}

如果结果未显示任何条目，请重试该命令。Logging 接收和处理日志条目需要一些时间。

您还可以使用日志浏览器查看日志条目。如需了解详情，请参阅使用日志浏览器查看日志。

删除日志条目

要删除日志 my-log 中的所有日志条目，请运行带 delete 选项的 snippets.py 脚本：

python snippets.py my-log delete

该命令完成时会返回以下结果：

Deleted all logging entries for my-log.

路由日志

在本部分中，您将执行以下操作：

  • 创建一个 Cloud Storage 存储桶作为数据的目标位置。
  • 创建一个将新日志条目复制到目标位置的接收器。
  • 更新 Cloud Storage 存储桶的权限。
  • 将日志条目写入 Logging。
  • （可选）验证 Cloud Storage 存储桶的内容。

创建目标位置

本快速入门的导出目标位置是一个 Cloud Storage 存储桶。如需创建 Cloud Storage 存储桶，请执行以下操作：

  1. 在 Google Cloud 控制台的导航面板中，选择 Cloud Storage，然后点击存储分区：

    前往存储分区

  2. 点击创建存储桶。
  3. 为存储桶输入名称。
  4. 对于位置类型，选择区域，这将选择延迟时间最短的存储桶位置。
  5. 对于默认存储类别，选择标准。
  6. 对于访问权限控制，选择精细控制。
  7. 对于保护工具，选择无，然后点击创建。

此快速入门使用名为 myloggingproject-1 的 Cloud Storage 存储桶。

创建接收器

接收器是一种规则，用于确定 Logging 是否将新到达的日志条目路由到目标位置。接收器具有三个属性：

  • 名称
  • 目标位置
  • 过滤条件

如需详细了解接收器，请参阅接收器。

如果新到达的日志条目满足查询条件，则该日志条目将被路由到目标位置。

export.py 脚本使用 Python 客户端库创建、列出、修改和删除接收器。如需创建用于将严重性级别至少为 INFO 的所有日志条目导出到 Cloud Storage 存储桶 myloggingproject-1 的接收器 mysink，请运行以下命令：

python export.py create mysink myloggingproject-1 "severity>=INFO"

要查看您的接收器，请运行带 list 选项的 export.py 脚本：

python export.py list

该脚本会返回以下内容：

    mysink: severity>=INFO -> storage.googleapis.com/myloggingproject-1

更新目标位置权限

如果您使用 export.py 脚本创建接收器，目标位置（本例中为您的 Cloud Storage 存储桶）的权限不会被修改。您必须更改 Cloud Storage 存储桶的权限设置，以便向接收器授予写入权限。 如需了解服务账号、访问权限范围和 Identity and Access Management 角色，请参阅服务账号。

如需更新 Cloud Storage 存储桶的权限，请执行以下操作：

  1. 确认接收器的写入者身份：

    1. 在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择日志路由器：

      前往日志路由器

      您将看到接收器的摘要表。

    2. 在表中找到您的接收器，选择 菜单，然后选择查看接收器详情。

    3. 将写入者身份复制到剪贴板。

  2. 在 Google Cloud 控制台的导航面板中，选择 Cloud Storage，然后点击存储分区：

    前往存储分区

  3. 如需打开详细视图，请点击存储桶的名称。

  4. 选择权限，然后点击授予访问权限。

  5. 将写入者身份粘贴到新的主帐号框中。从写入者身份地址中移除 serviceAccount: 前缀。

  6. 将角色设置为 Storage Object Creator，然后点击保存。

如需了解详情，请参阅设置目标位置权限。

验证接收器

如需验证您的接收器和目标位置是否已正确配置，请执行以下操作：

  1. 将新的日志条目写入日志 my-log：

    python snippets.py my-log write

  2. 查看您的 Cloud Storage 存储桶的内容：

    1. 在 Google Cloud 控制台的导航面板中，选择 Cloud Storage，然后点击存储分区：

      前往存储分区

    2. 如需打开详细视图，请点击存储桶的名称。详情视图列出了包含数据的文件夹。如果存储桶中没有数据，则会显示以下消息：

      There are no live objects in this bucket.

      如延迟的日志条目中所述，您可能需要等待两三个小时才能看到第一批条目显示在目标位置或收到配置错误通知。

      在存储桶收到数据后，详细视图会显示如下所示的结果：

      存储分区内容详细视图。

    3. 每个文件夹中的数据都会整理到一系列文件夹中，其中顶级文件夹名称是日志名称，然后依次是年、月、日。要查看接收器导出的数据，请点击文件夹名称 my-log，然后继续点击年、月、日子文件夹，直到找到以 json 结尾的文件：

      存储分区内容子文件夹视图。

    4. JSON 文件包含已导出到 Cloud Storage 存储桶的日志条目。点击 JSON 文件的名称以查看其内容。内容类似于如下所示：

       {"insertId":"yf1cshfoivz48",
 "logName":"projects/loggingproject-222616/logs/my-log",
 "receiveTimestamp":"2018-11-15T23:06:14.738729911Z",
 "resource":{"labels":{"project_id":"loggingproject-222616"},"type":"global"},
 "severity":"ERROR",
 "textPayload":"Goodbye, world!",
 "timestamp":"2018-11-15T23:06:14.738729911Z"}

      由于 ERROR 严重级别高于 INFO 严重级别，因此包含字符串“Goodbye, world!”的日志条目会被导出到接收器目标位置。其他写入的日志条目不会被导出到目标位置，因为它们的严重级别已设置为默认值，而默认严重级别低于 INFO。

问题排查

Cloud Storage 存储桶可能为空的原因有如下几种：

  • 存储桶尚未收到数据。您可能需要等待两三个小时才能看到第一批条目显示在目标位置或收到配置错误通知。如需了解详情，请参阅延迟的日志条目。

  • 存在配置错误。在这种情况下，您将收到主题如下所示的电子邮件：

     [ACTION REQUIRED] Logging export config error in myloggingproject.

    电子邮件的正文会对配置问题进行说明。 例如，如果您未更新目标位置权限，则电子邮件会列出以下错误代码：

     bucket_permission_denied

    如需更正此特定情况，请参阅本页面中的更新目标位置权限。

  • 创建接收器后未写入任何日志条目。接收器只会影响新到达的日志条目。要纠正此情况，请写入新的日志条目：

     python snippets.py my-log write

清理

为避免因本页中使用的资源导致您的 Google Cloud 账号产生费用，请按照以下步骤操作。

  1. （可选）删除您创建的日志条目。未删除的日志条目将会过期并被移除。请参阅配额和限制。

    如需删除日志 my-log 中的所有日志条目，请运行以下命令：

     python snippets.py my-log delete

  2. 删除您的 Google Cloud 项目或删除快速入门资源。

    • 如需删除您的 Google Cloud 项目，请在 Google Cloud 控制台的项目信息窗格中点击前往项目设置，然后点击关停。

    • 要删除快速入门资源，请执行以下操作：

      1. 通过运行以下命令删除接收器：

        python export.py delete mysink

      2. 删除 Cloud Storage 存储桶。转到 Google Cloud 控制台，依次点击存储 > 存储分区。勾选您的存储桶名称旁边的复选框，然后点击删除。

后续步骤