快速入门:使用 Cloud SDK

本快速入门介绍 Stackdriver Logging 的一些功能,让您了解如何:

  • 使用 Cloud SDK 写入日志条目。
  • 使用日志查看器查看和过滤日志条目。
  • 使用 Cloud SDK 列出日志条目。
  • 使用 Logging API 列出日志条目。

准备工作

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

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

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

    转到“管理资源”页面

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

    了解如何启用结算功能

使用入门

在本快速入门中,您可以使用 Cloud Shell 环境或 Compute Engine 虚拟机实例运行 Cloud SDK 命令。

Cloud Shell

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

  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]
      

虚拟机实例

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

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

      计算准备就绪

    2. 身份和 API 访问权限窗格中,选择针对每个 API 设置访问权限。向下滚动浏览新窗格中的列表,直到找到 Stackdriver 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]
    

使用 Cloud SDK 写入日志条目

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

  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。如果您省略此字段,负载会被解析为非结构化文本。

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

在日志查看器中查看日志

日志查看器是一种工具,用于查看、过滤和下载日志条目:

  1. 转到 Google Cloud Platform Console 中的“日志查看器”页面:

    转到“日志查看器”页面

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

    日志查看器

    检查 Google Cloud Platform 导航栏并确保您的项目已被选中。如有必要,使用项目下拉列表选择您的项目。

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

    日志查看器/全局

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

  3. 要展开日志条目,请点击展开按钮 (arrow_right)。

    日志查看器

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

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

过滤日志条目

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

  1. 在日志选择器上方的过滤条件框中,输入字符串 simple。日志显示区仅会显示日志条目 A simple entry.

  2. 查看日志后,移除您添加的过滤条件字符串,然后点击日志选择器上方的刷新按钮 (refresh)。显示区中会重新出现两个日志条目。

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

  1. 要切换到高级过滤条件模式,请点击过滤条件框最右侧的展开按钮 (arrow_drop_down),然后选择转换为高级过滤条件
  2. 过滤条件框包含 resource.type="global"。在该行的下方输入:

    jsonPayload.weather:partly
    
  3. 点击提交过滤条件。结果显示单个日志条目 My second entry

    日志条目高级过滤条件

如需详细了解过滤条件,请参阅高级日志过滤条件

使用 Cloud SDK 列出日志条目

您可以从 Logging 中检索日志条目,并使用 Cloud SDK 显示它们。例如,要检索并显示资源类型为 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"
    

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

    试用此 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"
        }
      ]
    }
    

问题排查

  • 排字错误和未知字段名称导致 Cloud SDK 命令完成时显示消息参数无效。举例来说,如果在 resource.type 中您忘记了加英文句点,则会导致下列错误:

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
    
  • 当 Stackdriver Logging 未被授予所需的访问权限时,Cloud SDK 命令完成时显示消息权限遭拒。举例来说,如果 Compute Engine 虚拟机实例配置了默认的 Cloud API 设置,则 list 命令完成时将显示下列权限遭拒错误:

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

    要解决这种情况,请修改 Compute Engine 虚拟机实例权限,以向 Stackdriver Logging 授予读取权限:

    1. 转到虚拟机实例的虚拟机实例详情页面。点击停止。完成此操作可能需要一两分钟时间。
    2. 要修改配置,请点击编辑
    3. 搜索标题 Cloud API 访问权限范围,然后点击详情以显示每个 API 的设置。将来自 Stackdriver Logging API 的条目更改为全部。点击保存
    4. 要重新启动虚拟机实例,请点击启动。片刻之后,您的虚拟机就可以使用了。
  • 当 API Explorer 无法完成您的命令或需要其他授权时,它会显示一条消息或错误代码:

    • 200 响应代码和没有条目:如果显示消息 nextPageToken,则表示 API Explorer 没有时间完成搜索。将 pageToken 添加到您的请求中,将该值设置为与使用键 nextPageToken 给定的值相同,然后重试此命令。
    • 400 响应代码:过滤条件值无效。例如,如果您将 global 错拼为 gloobal,则消息为 Unsupported resource type: gloobal
    • 404 响应代码:项目 ID 无效。检查项目标识符的拼写。
    • 系统可能会要求您登录自己的 Google 帐号并允许 API Explorer 访问您的帐号。

清理

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

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

    gcloud logging logs delete my-test-log
    

    未删除的日志条目将会过期并被移除。请参阅配额政策

后续步骤

  • 请参阅日志查看器,了解日志查看器更详细的介绍。
  • 请参阅导出日志,了解如何将日志条目导出到 Cloud Storage、BigQuery 和 Cloud Pub/Sub。
  • 请参阅 Logging 代理,了解如何在 Logging 中从虚拟机实例收集日志条目。
  • 请参阅审核日志,满足审核和合规性需求。
  • 请参阅 Stackdriver Logging API,了解如何从应用读取、写入和配置日志。
此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

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