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

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

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

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

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

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

准备工作

您必须有启用了结算功能的 Google Cloud 项目才能完成此快速入门。如果您没有 Google Cloud 项目，或者没有结算账号 ，请执行以下操作：

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

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

使用入门

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

Cloud Shell

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

   1. 在 Google Cloud 控制台中，点击 激活 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. 在表中找到接收器，选择 Menu（菜单），然后选择 View sink details（查看接收器详情）。

   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.

      如 延迟的日志条目， 第一批条目可能要 2 到 3 个小时才会显示在 或收到配置错误通知。

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

      

   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 控制台，然后点击存储 >存储分区。勾选您的存储分区名称旁边的复选框，然后点击删除。

后续步骤

• 如需了解如何从应用读取、写入和配置日志，请参阅 Cloud Logging API。
• 如需了解日志浏览器，请参阅 使用日志浏览器查看日志。
• 如需了解如何将日志数据路由到支持的目标位置，请参阅路由和存储概览。
• 如需了解如何从虚拟机实例收集日志条目，请参阅 Ops Agent 概览。
• 如需了解审核和合规性，请参阅 Cloud Audit Logs 概览。