使用 Logging 查询语言构建和保存查询

本文档介绍了如何在使用 Logs Explorer 时通过在查询编辑器字段中编写查询并从预定义的过滤条件选项中进行选择来检索和分析日志。您构建的查询是使用 Logging 查询语言编写的。

您还可以在“日志浏览器”页面中保存查询，或使用 Logging API 方法 savedQueries.create 保存查询。

准备工作

Logs Viewer 角色 (roles/logging.viewer) 提供查看日志的权限。例如，获得此角色后，您可以编写和运行查询。您还可以将查询另存为私享查询，并同时运行私享查询和共享查询。不过，此角色不允许您保存或修改共享查询。如果您想保存或修改共享查询，请确保您已获得 Logging Admin 角色 (roles/logging.admin)，该角色可提供对 Cloud Logging 的完全访问权限。

执行下列其中一项操作：

  • 如需获得编写和运行查询、运行和保存私密查询以及运行共享查询所需的权限，请让您的管理员为您授予项目的 Logs Viewer (roles/logging.viewer) IAM 角色。

  • 如需获得编写和运行查询、运行和保存私密查询，以及运行、创建和管理共享查询所需的权限，请让管理员向您授予项目的 Logging Admin (roles/logging.admin) IAM 角色。

如需详细了解必要的 IAM 权限，请参阅 Google Cloud 控制台的权限。

构建查询

如需使用 Google Cloud 控制台构建查询，请执行以下操作：

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

    前往 Logs Explorer

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

  2. 选择要查看其日志的 Google Cloud 项目或其他 Google Cloud资源。

  3. 使用查询窗格构建查询。

    查询窗格提供了多种构建和运行查询表达式的方法：

    • 搜索所有日志字段中的文本。
    • 从过滤器菜单中选择选项。
    • 使用查询编辑器编写或修改查询。
    • 在 查询库中查看和运行已保存的查询、近期查询和建议的查询。

搜索日志字段中的文本

如需搜索所有日志字段中的文本并查找所有匹配的日志条目，请在查询窗格的搜索字段中输入搜索字词。

您可以搜索字词和词组，搜索字词可以包含布尔运算符和正则表达式：

  • 如需执行区分大小写的搜索，您必须使用正则表达式。

  • 如需按令牌边界执行不区分大小写的搜索，请输入不带反引号或双引号的搜索字词。

    例如，如需搜索包含字词 hello 和字词 world 的日志条目，请输入 hello world。此命令会转换为 SEARCH("hello world")，用于匹配包含令牌 hello 和 world（可按任意顺序）的日志条目。由于搜索不区分大小写，因此搜索还会匹配包含令牌 Hello 和 World 的日志条目。搜索条件与令牌 worlds 不匹配。

  • 如需按令牌边界对某个词组执行不区分大小写的搜索，请将该词组用反引号括起来。

    例如，如需搜索字词组 hello world，请输入 `hello world`。此命令会转换为 SEARCH("`hello world`")，用于匹配包含令牌 hello world 的日志条目。搜索条件与令牌 hello worlds 不匹配。

  • 如需对子字符串执行不区分大小写的搜索，请将文本用双引号括起来。例如，"hello world" 与 Hello World 和 Hello world 匹配。由于搜索不是按令牌边界执行的，因此同一查询也与 hello worlds 匹配。

如需在查询表达式中查看搜索字词，请启用显示查询。

输入搜索字词后，点击运行查询或按 Enter 键。查询结果会显示在查询结果窗格中。

布尔运算符

搜索字段条目会转换为布尔表达式，用于指定所选资源中所有日志条目的子集。 Google Cloud

搜索字段支持使用布尔运算符 AND、OR 和 NOT。在搜索表达式中使用布尔运算符时，请注意以下事项：

  • 您无法使用括号嵌套规则。搜索表达式中的所有括号都会被解析为搜索字词。
  • 布尔运算符必须采用大写形式。系统会将小写形式 and、or 和 not 解析为搜索字词，而不是运算符。

如果您未添加任何运算符，则系统会使用 AND 将所有搜索字词和短语联接起来。您可以省略搜索字词之间的 AND 运算符。

AND 和 OR 运算符是短路运算符。您可以在同一表达式中组合使用 AND 和 OR 规则。例如，当混合使用这两个运算符时，表达式 a AND b OR c AND d 会转换为以下 Logging 查询语言表达式：

"a"
"b" OR "c"
"d"

NOT 运算符具有最高优先级，OR 次之，AND 最低。

NOT 运算符会对后续项执行求反运算。例如，NOT error 会返回不包含 error 的日志条目。您还可以将 NOT 运算符替换为 -（减号）运算符。例如，以下两个查询是相同的：

"response" AND "successful" AND NOT "error"

"response successful" -"error"

如果 -（减号）运算符位于引号之外，此逻辑也适用于字词组。例如，以下两个查询是相同的：

-"response successful"

NOT "response successful"

使用过滤条件菜单构建查询

您可以使用查询窗格中的过滤条件菜单将资源、日志名称、日志严重性和相关性参数添加到查询编辑器字段。这些选项对应于 Logging 中所有日志的 LogEntry 字段。

资源和日志名称菜单中的选项派生自 Cloud Logging 存储的日志条目。

  • 资源：可让您指定 resource.type 和关联的 resource.labels。您可以使用此过滤条件菜单选择单个资源类型，并选择要应用于查询的零个或零个以上的资源标签。资源参数由逻辑运算符 AND 联接。
  • 日志名称：允许您指定 logName。您可以选择多个日志名称来应用于查询。选择多个日志名称时，使用逻辑运算符 OR。
  • 严重程度：可让您指定严重程度。您可以同时选择多个严重程度级别添加到查询中。选择多个严重程度级别时，使用逻辑运算符 OR。
  • 按：让您能以“父-子”格式对日志条目进行分组和查看。如需了解详情，请参阅关联日志条目。

如需使用任何过滤条件菜单，请执行以下操作：

  1. 展开查询窗格中任何过滤条件菜单上的 Menu。

  2. 优化过滤条件参数。

  3. 点击应用。您会在查询编辑器字段中看到这些参数。

    如需在查询表达式中查看搜索字词，请启用显示查询。

  4. 查看查询后，点击运行查询。查询结果会显示在查询结果窗格中。

对于某些 Compute Engine 资源类型（例如 gce_instance 和 gce_network），您会看到资源名称，其中资源 ID 作为副文显示。例如，对于 gce_instance 资源类型，您会看到虚拟机名称和虚拟机 ID。资源名称可帮助您确定正确的资源 ID，以便您据此构建查询。

按时间范围查看日志

您可以通过以下两种方式显示在特定时间范围内写入的日志：

  1. 使用时间范围选择器。
  2. 在查询编辑器字段中添加时间戳表达式。

使用时间范围选择器

默认时间范围为 1 小时，但您可以从预设时间选项中进行选择、指定自定义开始时间和结束时间，也可以使用时间范围选择器将时间范围以特定时间戳为中心。例如，如果您想查看过去一周的数据，请从时间范围选择器中选择过去 1 周。

您还可以使用时间范围选择器设置时区偏好设置。

在查询编辑器字段中添加时间戳表达式

如需直接向查询编辑器字段添加时间戳表达式，请使用 Logging 查询语言。

如果查询编辑器字段包含包含时间戳的表达式，则时间范围选择器会处于停用状态，查询会使用时间戳表达式作为其时间范围限制。如果查询不使用时间戳表达式，则会使用时间范围选择器作为其时间范围限制。

使用 Logging 查询语言编写高级查询

您可以使用 Logging 查询语言在 Logs Explorer 查询编辑器字段中构建更高级的查询：

  1. 如果您在查询窗格中没有看到查询编辑器字段，请启用显示查询。

  2. 直接在查询编辑器字段中输入查询表达式。

    如果您在搜索字段中添加了任何搜索字词，或在过滤条件菜单中选择了任何参数，这些内容也会显示在查询编辑器字段中，并作为查询表达式的一部分进行评估。

  3. 查看查询后，点击运行查询。

    与您的查询匹配的日志会列在查询结果窗格下。直方图和日志字段窗格也会根据查询表达式进行调整。

如需了解您想要使用的常见查询示例，请参阅使用日志浏览器的查询示例。

使用近期查询

运行任何查询时，该查询都会添加到 查询库中，其中包含近 30 天的最后 10,000 个非重复查询。

如需查看最近的查询，请选择主工具栏中的 Query Library（查询库）按钮。对于近期查询，您有以下选项：

  • 流式传输：如需运行查询并流式传输结果，请选择此选项。
  • Run：如需运行查询，请选择此选项。

  • 更多选项：允许您使用选项来查看查询表达式以便运行查询或将查询保存到已保存查询列表。您也可以直接选择查询来获取这些选项。

    如需保存查询，请执行以下操作：

    1. 点击保存。系统随即会打开保存查询对话框。

    2. 填写以下字段：

      • 名称（必填）：为查询提供名称。名称的长度不得超过 64 个字符。
      • 说明（可选）：提供说明以帮助标识查询的用途。
      • 添加摘要字段（可选）：启用添加摘要字段，然后输入要显示的摘要字段。
      • 截断摘要字段（可选）：启用截断摘要字段，然后选择要截断的字符数，并选择是在字段开头还是结尾处进行截断。

    3. 点击保存查询。您现在可以在“已保存的查询”列表中找到该查询。

您还可以对最近查询进行排序和过滤；过滤条件与查询表达式中的文本匹配。

保存和共享查询

通过已保存的查询，您可以存储查询表达式，这有助于您以更一致、更高效的方式探索日志。日志浏览器提供了一个查询库，您可以在该库中访问已保存的查询。您还可以使用 Logging API 方法 savedQueries.create 保存查询。

您可以保存查询，使其设为不公开且仅对您可见，也可以与 Google Cloud 项目的其他成员共享。分享查询后，该查询将不再归您所有，并且项目中拥有必要权限的任何成员都可以访问该查询。

控制台

如需保存已在查询编辑器字段中构建的查询表达式，请执行以下操作：

  1. 在查询窗格中点击保存。此时系统会打开保存查询对话框，并在查询编辑器字段中填充您的查询表达式。

  2. 填写以下字段：

    • 名称（必填）：为查询提供名称。名称的长度不得超过 64 个字符。
    • 说明（可选）：提供说明以帮助标识查询的用途。
    • 添加自定义摘要字段（可选）：启用添加摘要字段，然后输入要显示的摘要字段。
    • 截断摘要字段（可选）：启用截断摘要字段，然后选择要截断的字符数，并选择是在字段开头还是结尾处进行截断。
    • 与项目共享：您可以选择启用与项目共享，以便与 Google Cloud 项目的其他成员共享查询。

  3. 点击保存查询。已保存的查询会显示在已保存标签页下的列表中。

如需运行已保存的查询，请点击运行。如需运行查询并流式传输结果，请点击流式传输。

如需修改已保存的查询，请依次选择 更多选项 和 修改。您也可以选择相应查询，进行修改，然后保存修改后的查询。

如需删除已保存的查询，请依次选择 更多选项和 删除。

您还可以对已保存的查询进行排序和过滤；过滤条件与查询表达式中的文本匹配。

API

如需使用 Logging API 保存查询，请使用 savedQueries.create 方法。如需详细了解此方法、其参数和响应数据，请参阅 savedQueries.create 的参考页面。

您可以使用方法参考页面上的 API Explorer 微件来执行 savedQueries.create 方法。对于日志浏览器查询，您必须指定 loggingQuery 字段。以下示例展示了一个包含 SavedQuery 实例的示例请求正文：

{
  "parent": "projects/my-project/locations/global"
  "savedQueryId": "compute-query"
  {
    "displayName": "compute-admin-activity-query",
    "description": "Queries for Compute Engine Admin Activity logs.",

    "loggingQuery":
      {
        "filter": resource.type="gce_instance" AND log_id("cloudaudit.googleapis.com/activity"),
      },
    "visibility": "PRIVATE"
  }
}

如需与 Google Cloud 项目的其他成员共享查询，请在 visibility 字段中指定值 SHARED。

查看已保存的查询

您可以点击 Query library（查询库）按钮，查看私有查询以及与 Google Cloud 项目中的其他成员共享的查询：

控制台

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

    前往 Logs Explorer

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

  2. 选择要查看其日志的 Google Cloud 项目或其他 Google Cloud资源。

  3. 点击 Query library（查询库）按钮，然后点击 Saved（已保存）。

您可以按任意标题对表格进行排序。公开范围列会指明查询是共享还是不公开：

  • 已共享：与 Google Cloud 项目的其他成员共享的查询。
  • 不公开：您已保存的查询，仅对您本人可见。

API

您可以使用 Logging API 通过 savedQueries.list 方法查看私享查询和共享查询。

例如，以下请求正文列出了包含通配符位置 ID 的所有共享 Logs Explorer 查询：

{
  "parent": "name": projects/PROJECT_ID/locations/-
  "visibility": "SHARED"
  "filter": "explorer"
}

使用建议的查询

Logging 会根据 Google Cloud 项目的上下文（例如您使用的 Google Cloud 产品）生成建议的查询。建议的查询可帮助您找出问题，并让您深入了解系统的整体运行状况。例如，如果检测到您正在使用 Google Kubernetes Engine，Logging 可能会建议一个查询，该查询可以找到容器的所有错误日志。

如需查看和运行建议的查询，请点击 查询库按钮，然后点击建议。在推荐标签页中，您可以选择以下选项：

  • 流式传输：如需运行查询并流式传输结果，请选择此选项。
  • Run：如需运行查询，请选择此选项。

  • 更多选项：允许您查看查询表达式的详细信息，并提供用于运行或保存查询的选项。您也可以直接选择查询来获取这些选项。

    如需查看建议的查询的详细信息，请执行以下任一操作：

    • 选择相应查询的行。

    • 点击 更多，然后选择查看。系统随即会打开查询详情对话框。

    在查询详情对话框中，您会看到该查询以及用于运行、流式传输或另存为的选项：

    • 如需保存查询，请执行以下操作：

      1. 点击保存查询。
      2. 填写保存查询对话框中的字段。

      修改后的查询会显示在已保存列表中，您可以选择稍后运行该查询。

    • 如需立即运行查询，请点击运行。查询会运行并显示在查询编辑器字段中。

    • 如需立即运行查询并流式传输结果，请点击流式传输。

    • 如需关闭该对话框并返回到建议的查询列表，请点击关闭。

请注意以下预期行为：

  • 而连续的页面加载可能不会按同一顺序显示相同的查询。
  • 您可能会看到零个建议的查询。
  • 有时，运行建议的查询会返回零个日志。

从库中选择查询

Logging 提供了一个基于常见用例和 Google Cloud 产品的查询库。这些查询可帮助您在紧急的问题排查会话期间高效地查找日志，并探索日志以更好地了解可用的 Logging 数据。

如需查看和运行库的查询，请执行以下操作：

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

    前往 Logs Explorer

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

  2. 选择要查看其日志的 Google Cloud 项目或其他 Google Cloud资源。

  3. 点击 Query library 按钮。您会看到可用查询的类别以及基于 Google Cloud产品的查询子集。如需缩小所显示查询的范围，请点击任一商品。

    您还可以使用搜索字段按类别、说明或查询表达式的内容搜索可用查询。

  4. 如需查看查询表达式，请执行以下任一操作：

    a. 点击相应查询的行。

    b. 点击 更多，然后选择查看。

  5. 在查询详情对话框中，您会看到该查询以及用于运行、流式传输或另存为的选项：

    • 如需保存查询，请执行以下操作：

      1. 点击保存查询。
      2. 填写保存查询对话框中的字段。

      修改后的查询会显示在已保存列表中，您可以选择稍后运行该查询。

    • 如需立即运行查询，请点击运行。查询会运行并显示在查询编辑器字段中。

    • 如需立即运行查询并流式传输结果，请点击流式传输。

    • 如需关闭该对话框并返回建议的查询列表，请点击关闭。

后续步骤