使用 gcloud CLI 写入和查询日志条目

使用 gcloud CLI 写入和查询日志条目

本文档介绍了 Cloud Logging 的一些功能，并展示了如何执行以下操作：

• 使用 Google Cloud CLI 写入日志条目。
• 使用 gcloud CLI 列出日志条目。
• 使用 Logging API 列出日志条目。
• 使用日志浏览器查看和查询日志条目。

准备工作

您必须有启用了结算功能的 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.

使用入门

gcloud CLI 有一组命令， gcloud logging，它们为 Cloud Logging API 提供命令行界面。

您可以使用 Cloud Shell 环境或 Compute Engine 虚拟机 gcloud CLI 命令的 快速入门。gcloud CLI 已预安装在 Cloud Shell 环境中。

Cloud Shell

验证 gcloud CLI 是否已配置为使用正确的 Google Cloud 项目：

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

   Cloud Shell 将在一个窗口中打开并显示欢迎消息。欢迎辞中会回显已配置的项目 ID。

2. 如果要使用不同于欢迎消息中列出的 Google Cloud 项目，请在将 PROJECT_ID 替换为项目 ID 后运行以下命令：

      gcloud config set project PROJECT_ID
      

   如需获取项目 ID，请参阅识别项目。

虚拟机实例

如需在 Google Cloud 控制台中创建 Compute Engine 虚拟机实例，请执行以下操作： 请按以下步骤操作：

1. 在 Google Cloud 控制台中，选择 Compute Engine，然后选择 VM 实例。

2. 选择创建实例。

3. 在访问权限范围下的身份和 API 访问权限中，选择 为每个 API 设置访问权限。

4. 滚动查看 API，直至找到 Stackdriver Logging API。将访问权限切换为完整。

5. 将所有其他设置保留为默认值并点击创建。虚拟机实例可以使用了。

6. 点击 SSH 以连接到虚拟机实例 shell。片刻之后，窗口中就会打开 Debian GNU/Linux shell 并显示欢迎消息。

7. 运行以下命令以验证 gcloud CLI 是否 为您的 Compute Engine 项目配置的

     gcloud config list
     

8. 如果您想使用其他 Google Cloud 项目，请运行 （将 PROJECT_ID 替换为您的 项目 ID：

     gcloud config set project PROJECT_ID
     

   如需获取项目 ID，请参阅识别项目。

使用 gcloud CLI 写入日志条目

Logging 支持包含结构化和非结构化数据的日志条目。结构化数据由 JSON 数据结构组成；例如 {"weather": "partly cloudy"}。非结构化数据是一串字符；例如 "A simple entry"。在接下来的步骤中，您将使用 gcloud CLI 写入含非结构化数据的日志条目和含结构化数据的日志条目：

1. 将含非结构化数据的日志条目写入日志 my-test-log：

   gcloud logging write my-test-log "A simple entry."
   

   命令完成后，您会看到消息：Created log entry。

2. 将含结构化数据的日志条目写入日志 my-test-log：

   gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
   

   当您写入含结构化数据的日志条目时，必须包括 --payload-type=json。如果您省略此字段，Logging 会将负载解释为非结构化数据。

如果日志 my-test-log 不存在，则 Logging 会在收到日志条目时创建该日志。

使用 gcloud CLI 列出日志条目

您可以使用 gcloud CLI 从 Logging 中检索日志条目并显示这些条目。例如，如需检索并显示资源类型为 global 的日志条目，请运行以下命令：

gcloud logging read "resource.type=global"

该命令会返回类似于如下所示的结果：

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

使用 API Explorer 列出日志条目

若要在不编写任何代码的情况下运行 Logging API 方法，请参阅 使用 APIs Explorer。如需从 Logging 中读取日志条目列表，请执行以下操作：

1. 转到 entries.list API 方法的“API 参考文档”页面：

   转到 entries.list API 页面

2. 配置并运行 API 命令：

   1. 替换以下文本中的 PROJECT_ID：

      "resourceNames": [
      "projects/PROJECT_ID"
      ],
      "filter": "resource.type=global",
      "orderBy": "timestamp desc"
      

   2. 复制上一步中更新后的文本，将其粘贴到 API Explorer 的请求正文字段中。

   3. 点击执行。

   该方法会返回类似于如下所示的响应：

   {
     "entries": [
       {
         "textPayload": "A simple entry",
         "insertId": "vd4m1if7h7u1a",
         "resource": {
           "type": "global",
           "labels": {
             "project_id": "myloggingproject"
           }
         },
         "timestamp": "2018-11-01T18:39:19.718100792Z",
         "logName": "projects/myloggingproject/logs/my-test-log",
         "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
       },
       {
         "insertId": "jpj9zjf73t1mn",
         "jsonPayload": {
           "message": "My second entry",
           "weather": "partly cloudy"
         },
         "resource": {
           "type": "global",
           "labels": {
             "project_id": "myloggingproject"
           }
         },
         "timestamp": "2018-11-01T18:39:31.114507977Z",
         "logName": "projects/myloggingproject/logs/my-test-log",
         "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
       }
     ]
   }
   

在日志浏览器中查看日志条目

如需在 Google Cloud 控制台中查看日志条目，您可以使用 Logs Explorer。大多数 Google Cloud 项目都会存储大量日志；您可以通过编写查询来选择特定的日志条目。

如需查看您使用日志浏览器写入的日志条目，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 Logs Explorer 页面。

   前往 Logs Explorer

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

   确保在 Google Cloud 中选择您的 Google Cloud 项目 导航栏。如有必要，请使用 Google Cloud 项目下拉列表选择您的 Google Cloud 项目。

2. 在资源菜单中，选择全局。

   如果您没有看到全局菜单选项或者没有看到日志条目，请等待几分钟，然后刷新该页面。Logging 可能需要几分钟才能收到日志条目。

3. 如需查看日志条目的详细信息，请点击其 菜单。

   第一个日志条目的数据存储在 textPayload 中。第二个日志 条目包含存储在 jsonPayload 中的结构化数据。结构化载荷包含键 message 和 weather。

   注意：如果 message 是用于结构化日志条目的键，则 Logging 会在日志条目未展开时将该键用作日志条目的摘要。

如需了解日志条目的数据格式，请参阅 LogEntry 类型。

在日志浏览器中查询日志条目

您可以使用查询编辑器查询日志条目；对于结构化日志，也可以使用键和值过滤日志条目。例如，要显示包含 文本 simple，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 Logs Explorer 页面。

   前往 Logs Explorer

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

2. 在资源菜单中，选择全局。

3. 在查询编辑器中，用英文引号括住输入字符串 simple。 日志显示区仅会显示日志条目 A simple entry.

4. 查看日志后，移除您添加的查询字符串，然后点击运行查询。显示区中会重新出现两个日志条目。

显示包含结构化数据且键为 weather 的所有日志条目 其中 value 字段包含 partly，请执行以下操作：

1. 查询编辑器中有一行为 resource.type="global"。 输入以下命令：

   jsonPayload.weather:partly
   

2. 点击运行查询。结果为一条日志条目 My second entry。

日志浏览器还提供保存的查询、建议的查询和最新查询。如需详细了解查询，请参阅在日志浏览器中构建查询。

如需查看示例查询，请参阅使用日志浏览器的查询示例。

问题排查

• 排字错误和未知字段名称导致 gcloud CLI 命令完成时显示消息参数无效。例如，如果您忘记输入 resource.type 中的英文句点，则会导致以下错误：

   ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
  

• 当 Cloud Logging 未被授予必要的访问权限时， gcloud CLI 命令 权限遭拒消息。 例如，如果 Compute Engine 虚拟机实例配置了默认的 API 设置，则 list 命令完成时显示“权限遭拒”错误：

   ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
  

  如需解决此问题，请通过执行以下操作修改您的 Compute Engine 虚拟机实例权限以授予 Cloud Logging 读取权限：

  1. 转到虚拟机实例的虚拟机实例详情页面。点击停止。完成此操作可能需要一两分钟时间。
  2. 若要修改配置，请点击编辑。
  3. 搜索标题 Cloud API 访问权限范围，然后点击详情以显示每个 API 的设置。将来自 Cloud Logging API 的条目更改为全部。点击保存。
  4. 如需重新启动虚拟机实例，请点击启动。片刻之后，您的虚拟机就可以使用了。

• 当 API Explorer 无法完成您的命令或需要其他授权时，它会显示一条消息或错误代码：

  • 200 响应代码和没有条目：如果显示消息 nextPageToken，则表示 API Explorer 没有时间完成搜索。在请求中添加 pageToken，将值设置为键 nextPageToken 所对应的值，然后重试命令。
  • 400 响应代码：查询值无效。例如，如果您将 global 错拼为 gloobal，则消息为 Unsupported resource type: gloobal。
  • 404 响应代码：项目 ID 无效。检查项目标识符的拼写。
  • 系统可能会要求您登录自己的 Google Cloud 项目，并允许 APIs Explorer 访问您的账号。

清理

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

1. （可选）若要删除您创建的日志条目，请运行以下 gcloud 命令：

   gcloud logging logs delete my-test-log
   

   如果您不删除日志条目，它们会过期，然后被移除。如需了解保留信息，请参阅配额和限制。

后续步骤

• 如需详细了解 Logging 命令行界面，请参阅 gcloud logging 命令组的参考页面。
• 如需获取 Logging API 的相关文档，请参阅 Cloud Logging API。
• 如需详细了解日志浏览器，请参阅使用日志浏览器。

• 如需了解如何在 Google Cloud 控制台中从虚拟机实例收集日志条目， Logging，请参阅 Google Cloud Observability 代理。