快速入门:使用 Logging 工具

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

  • 使用 gcloud 命令行工具写入日志条目。
  • 使用 gcloud 命令行工具列出日志条目。
  • 使用 Logging API 列出日志条目。
  • 使用日志浏览器查看和查询日志条目。

准备工作

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

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

  2. 在 Cloud Console 的项目选择器页面上,选择或创建 Cloud 项目。

    转到项目选择器页面

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

开始使用

Cloud SDK 有一组 gcloud logging 命令,为 Cloud Logging API 提供命令行界面。

您可以使用 Cloud Shell 环境或 Compute Engine 虚拟机 (VM) 实例来执行此快速入门中的 gcloud 命令行工具命令。

Cloud Shell

  1. Cloud SDK 已预安装在 Cloud Shell 环境中。您无需安装或配置任何其他软件。

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

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

      激活 Cloud Shell

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

      欢迎使用 Cloud Shell

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

       gcloud config set project [PROJECT_ID]
      

虚拟机实例

  1. 创建 Compute Engine 虚拟机实例:

    1. 在 Cloud Console 中,选择 Compute Engine > 虚拟机实例。选择创建。如果您看到以下消息,请等待 Compute Engine 准备就绪后再继续:

      计算准备就绪

    2. 身份和 API 访问权限中,选择针对每个 API 设置访问权限。滚动查看列表,直至找到 Cloud Logging API。将访问权限从只写切换为全部

      计算准备就绪

    3. 将所有其他设置保留为默认值并点击创建。片刻之后,虚拟机实例就可供使用了。

  2. 如需连接到虚拟机实例 shell,请转到 SSH > 在浏览器窗口中打开。片刻之后,窗口中就会打开 Debian GNU/Linux shell 并显示欢迎辞。

  3. Cloud SDK 已预安装在 GCM 虚拟机实例中。如需验证 Compute Engine 项目是否已配置 Cloud SDK,请运行以下命令:

     gcloud config list
    
  4. 如果列出的项目不是您要使用的项目,请在将 [PROJECT_ID] 替换为项目 ID 后运行以下命令:

     gcloud config set project [PROJECT_ID]
    

使用 gcloud 工具写入日志条目

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

  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 工具列出日志条目

您可以从 Logging 中检索日志条目,并使用 gcloud 工具显示这些条目。例如,如需检索并显示资源类型为 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 列出日志条目

您可以使用 API Explorer 运行 Logging API 方法,无需编写任何代码。如需从 Logging 中读取日志条目列表,请执行以下操作:

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

    转到 entries.list API 页面

  2. 您将会看到 API Explorer 微件。其标题为试用此 API。请复制以下文本并将其粘贴到请求正文中。先替换 [PROJECT_ID],然后点击执行

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

    下面的示例显示采用这些设置的已完成请求正文

    试用此 API

  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"
        }
      ]
    }
    

在日志浏览器中查看日志

日志浏览器是一种工具,用于查看、查询和下载日志条目:如需在日志浏览器中查看日志,请执行以下操作:

  1. 转到 Google Cloud Console 中的“日志浏览器”。

    转到日志浏览器

    您会看到“日志浏览器”页面:

    旧版日志查看器

    查看 Google Cloud 导航栏,确保您的项目处于选中状态。如有必要,使用项目下拉列表选中您的项目。

  2. 在资源类型下拉列表中,选择全局以查看您写入的日志条目:

    旧版日志查看器/全局

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

  3. 若要展开日志条目,请点击其菜单

    旧版日志查看器

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

如需详细了解日志条目数据格式,请参阅 LogEntry 类型

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

您可以使用文本字段查询日志条目;对于结构化日志,也可以使用键和值过滤日志条目。例如,若要显示包含文本 simple 的所有日志条目,请执行以下操作:

  1. 在搜索查询框中,输入字符串 simple。日志显示区仅会显示日志条目 A simple entry.

  2. 当您查看完日志后,移除您添加的查询字符串,然后点击刷新 ()。显示区将重新显示这两个日志条目。

如需显示包含结构化数据、键为 weather 并且 value 字段包含 partly 的所有日志条目,请执行以下操作:

  1. 您可以点击查询框中的下拉菜单 ,然后选择转换为高级过滤条件,已切换到高级查询模式。
  2. 查询框中有一行为 resource.type="global"。在该行下方,输入以下命令行:

    jsonPayload.weather:partly
    
  3. 点击提交过滤条件。结果为一条日志条目 My second entry

    日志条目的高级查询

如需详细了解查询,请参阅高级日志查询

问题排查

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

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
    
  • 当 Cloud Logging 未被授予所需的访问权限时,gcloud 工具命令完成时会显示消息权限遭拒。例如,如果 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 帐号并允许 API Explorer 访问您的帐号。

清理

为避免系统因本快速入门中使用的资源向您的 Google Cloud 帐号收取费用,请按照以下步骤操作。

  1. (可选)若要删除您创建的日志条目,请运行以下 gcloud 命令:

    gcloud logging logs delete my-test-log
    

    如果您不删除日志条目,它们会过期,然后被移除。如需了解有关保留的信息,请转到配额和限制

后续步骤

  • 如需详细了解 Logging 命令行界面,请参阅 gcloud logging 命令组的参考页面。
  • 如需获取 Logging API 的相关文档,请阅读 Cloud Logging API
  • 如需详细了解日志浏览器,请转到日志浏览器
  • 如需了解如何在 Logging 中收集来自您的虚拟机实例的日志条目,请转到关于 Logging 代理
  • 阅读我们关于 DevOps 的资源,并了解我们的研究项目