Python 使用快速入门

在本快速入门中,您将执行 Python 程序以写入、读取、删除和导出日志条目。

准备工作

您必须拥有已启用结算功能的 Google Cloud Platform 项目才能完成此快速入门。如果您没有 GCP 项目,或者没有为项目启用结算功能,请执行以下操作:
  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册新帐号

  2. 选择或创建 Google Cloud Platform 项目。

    转到“管理资源”页面

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

    了解如何启用结算功能

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

使用入门

您可以使用 Cloud Shell 环境或通用 Linux 环境来完成本快速入门。

Cloud Shell

  1. Cloud Shell 中预装了 Python 2.7 版和 3.5 版。您无需安装或配置任何其他软件。

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

    1. 在 GCP Console 中,点击右上角的激活 Cloud Shell 按钮。

      激活 Cloud Shell

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

      欢迎使用 Cloud Shell

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

       gcloud config set project [PROJECT_ID]
      

Linux

  1. 安装并配置 Python。在本快速入门中,您可以使用 Python 版本 2 或 3。如需了解详情,请参阅设置 Python 开发环境

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

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

      转到服务帐号

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

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

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

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

      • 创建密钥(可选)窗格中,点击创建密钥
      • 对于密钥类型,选择 JSON,然后点击创建。片刻之后,弹出式窗口会显示如下所示的消息:

        私钥已保存

    6. 要完成服务帐号的创建过程,请点击完成

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

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

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

克隆源代码

克隆 GitHub 项目 python-docs-samples

git clone https://github.com/GoogleCloudPlatform/python-docs-samples

目录 python-docs-samples/logging/cloud-client 包含本快速入门中使用的两个程序:

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

要切换至程序目录,请运行以下命令:

cd python-docs-samples/logging/cloud-client

写入日志条目

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-list 中的所有日志条目,请运行带有 delete 选项的 snippets.py 程序:

python snippets.py my-log delete

片刻之后,该命令就会完成,并显示以下结果:

Deleted all logging entries for my-log

导出日志

Logging 可以将日志条目导出到 Cloud Storage 存储分区、BigQuery 数据集和 Cloud Pub/Sub。如需详细了解如何导出,请参阅日志导出概览

在本部分中,您要执行以下操作:

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

创建目标位置

本快速入门的导出目标位置是一个 Cloud Storage 存储分区。要创建 Cloud Storage 存储分区,请执行以下操作:

  1. 在 GCP Console 中,转到存储 > 浏览器

    转到浏览器

  2. 点击创建存储分区

  3. 为存储分区选择名称。

  4. 选择区域,然后为位置选择最近的地理选项。

  5. 对于访问权限控制模型,请选择设置对象层级和存储分区层级权限 (Set object-level and bucket-level permissions)。

  6. 所有其他设置都保留默认值。点击创建

本快速入门使用 myloggingproject-1 作为 Cloud Storage 存储分区名称。

创建接收器

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

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

如果新到达的日志条目满足过滤条件,则该日志条目将被导出到目标位置。

export.py 程序使用 Python 客户端库来创建、列出、修改和删除接收器。要创建名为 mysink 的接收器以将严重级别不低于 INFO 的所有日志条目导出到 Cloud Storage 存储分区 myloggingproject-1,请运行以下命令:

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 存储分区的权限设置,以便向接收器授予写入权限。

要更新 Cloud Storage 存储分区的权限,请执行以下操作:

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

    1. 转到日志查看器页面:

      转到“日志查看器”页面

    2. 选择导出以查看接收器的摘要,包括接收器的写入者身份

  2. 在 GCP Console 中,点击存储 > 浏览器

    转到浏览器

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

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

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

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

验证接收器

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

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

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

    1. 在 GCP Console 中,点击存储 > 浏览器

      转到浏览器

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

      There are no live objects in this bucket.

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

    3. 存储分区收到数据后,详情视图会显示如下所示的结果:

      存储分区内容

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

      存储分区内容

    5. 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] Stackdriver Logging export config error in myloggingproject.

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

     bucket_permission_denied

    要纠正此特定情况,请参阅更新权限

  • 创建接收器后您没有写入日志条目。接收器只会影响新到达的日志条目。要纠正此情况,请写入新的日志条目:

     python snippets.py my-log write
    

清理

为避免系统因本快速入门中使用的资源向您的 GCP 帐号收取费用,请执行以下操作:

  1. (可选)删除您创建的日志条目。未删除的日志条目将会过期并被移除。请参阅配额政策。要删除日志 my-log 中的所有日志条目,请运行以下命令:

     python snippets.py my-log delete
    
  2. 删除项目或删除快速入门资源。

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

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

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

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

后续步骤

  • 请参阅服务帐号,详细了解服务帐号、访问权限范围和 Cloud Identity and Access Management 角色。
  • 请参阅日志查看器,详细了解日志查看器。
  • 请参阅导出日志,了解如何将日志条目导出到 Cloud Storage、BigQuery 和 Cloud Pub/Sub。
  • 请参阅 Logging 代理,了解如何在 Stackdriver Logging 中从虚拟机实例收集日志条目。
  • 请参阅审核日志,了解审核和合规性需求。
  • 请参阅 Stackdriver Logging API,了解如何从应用读取、写入和配置日志。
此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Stackdriver Logging
需要帮助?请访问我们的支持页面