快速入门:使用 Python

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

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

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

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

准备工作

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

    转到“项目选择器”

  3. 确保您的 Cloud 项目已启用结算功能。 了解如何确认您的项目是否已启用结算功能

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

    转到“项目选择器”

  5. 确保您的 Cloud 项目已启用结算功能。 了解如何确认您的项目是否已启用结算功能

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

使用入门

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

Cloud Shell

  1. 按照下列步骤打开 Cloud Shell 并验证您的 Cloud 项目配置:

    1. 在 Cloud Console 中,点击激活 Cloud Shell

      激活 Cloud Shell

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

      欢迎使用 Cloud Shell

    2. 欢迎消息中会显示已配置的项目 ID。如果这不是您要使用的项目,请将 [PROJECT_ID] 替换为您的项目 ID 并运行以下命令:

       gcloud config set project [PROJECT_ID]
      

Linux

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

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

    1. 在 Cloud Console 中,转到 IAM 和管理 > 服务帐号

      转到“服务帐号”

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

      • 输入帐号名称。
      • 输入帐号说明。
      • 点击创建
    3. 服务帐号权限(可选)窗格中,对于角色,请从下拉列表中选择 Logging Admin。点击继续

    4. 跳过该选项以授予用户访问服务帐号的权限。

    5. 点击完成

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

      • 针对您的服务帐号,点击更多选项,然后选择管理密钥
      • 密钥窗格中,点击添加密钥
      • 对于密钥类型,选择 JSON,然后点击创建。片刻之后,弹出式窗口会显示如下所示的消息:

        私钥已保存

  3. 在 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. 在 Cloud Console 中,转到 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. 转到日志路由器页面:

      转到“日志路由器”

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

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

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

  2. 在 Cloud Console 中,点击 Storage,然后选择浏览器

    转到浏览器

  3. 如需打开详细视图,请点击存储分区的名称。

  4. 选择权限,然后点击添加

  5. 角色设置为 Storage Object Creator,并输入您的接收器的写入者身份。

如需了解详情,请参阅目标位置权限

验证接收器

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

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

    python snippets.py my-log write
    
  2. 查看您的 Cloud Storage 存储分区的内容:

    1. 在 Cloud Console 中,点击 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. 删除 Cloud 项目或删除快速入门资源。

    • 如需删除 Cloud 项目,请在 Cloud Console 的项目信息窗格中点击转到项目设置,然后点击关停

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

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

        python export.py delete mysink
        
      2. 删除 Cloud Storage 存储分区。转到 Cloud Console,然后点击存储 >浏览器。勾选您的存储分区名称旁边的复选框,然后点击删除

后续步骤