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

本文档介绍如何通过以下方式检索和分析日志:使用 Logs Explorer 时在查询编辑器字段中编写查询,以及使用日志条目中包含的选项从过滤条件菜单中进行选择。您构建的查询使用 Logging 查询语言编写。

您还可以在 Logs Explorer 页面中保存查询,或者使用 Logging API 方法 savedQueries.create 来保存。

准备工作

  • 如需构建查询,您必须拥有读取日志数据的权限。Logging Viewer (roles/logging.viewer) 角色拥有这些权限。如需详细了解必要的 IAM 权限,请参阅 Google Cloud 控制台的权限

  • 如需保存查询,您的 Identity and Access Management 角色必须包含 logging.queries.{list, create, get, update, delete} 权限。

  • 如需共享查询,您的 Identity and Access Management 角色必须包含 logging.queries.share 权限。Owner (roles/owner) 和 Logging Admin (roles/logging.admin) 角色拥有此权限。

    如需查看与每个 Logging 角色关联的权限列表,请参阅 Logging 角色

构建查询

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

  1. 在 Google Cloud 控制台的导航面板中,选择 Logging,然后选择 Logs Explorer

    前往 Logs Explorer

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

    如需查看从 Amazon Web Services (AWS) 帐号发送到 Logging 的日志,请在 Google Cloud 控制台资源选择器中选择 AWS 连接器项目,然后使用 Logs Explorer。AWS 连接器项目会存储您的 AWS 账号的 Amazon 资源名称 (ARN),并将您的 AWS 账号关联到 Google Cloud 服务。如需了解详情,请参阅从 AWS 帐号收集指标
  3. 使用查询窗格构建查询。

    日志浏览器查询窗格。

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

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

搜索日志字段中的文本

如需搜索所有日志字段中的文本并查找所有匹配的日志条目,请在搜索字段中输入搜索字词:

查询窗格中的日志浏览器搜索字段。

您可以搜索字词和短语,并且您的搜索字词可以包含布尔值运算符正则表达式

  • 如需沿词元边界执行不区分大小写的搜索,请输入搜索字词,不要反引号或双引号。

    例如,如需搜索包含 helloworld 一词的日志条目,请输入 hello world。此命令会转换为 SEARCH("hello world"),它会匹配包含令牌 helloworld 的日志条目(按任意顺序)。由于搜索不区分大小写,因此搜索还会匹配包含令牌 HelloWorld 的日志条目。此搜索条件与令牌 worlds 不匹配。

  • 如需沿词元边界对短语执行不区分大小写的搜索,请使用反引号将短语括起来。

    例如,如需搜索短语 hello world,请输入 `hello world`。 此命令会转换为 SEARCH("`hello world`"),它会匹配包含令牌 hello world 的日志条目。此搜索条件与令牌 hello worlds 不匹配。

  • 如需对子字符串执行不区分大小写的搜索,请用英文双引号将文本引起来。例如,"hello world"Hello WorldHello world 匹配。同一查询也匹配 hello worlds,因为搜索不是沿词元边界执行的。

要查看查询表达式中的搜索字词,请启用显示查询

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

布尔运算符

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

搜索字段支持使用布尔运算符 ANDORNOT。在搜索表达式中使用布尔值运算符时,请注意以下事项:

  • 不能使用括号来嵌套规则。搜索表达式中的任何圆括号都会被解析为搜索字词。
  • 布尔值运算符必须大写。系统会将小写的 andornot 解析为搜索字词,而不是运算符。

如果您未包含任何运算符,则所有搜索字词和短语都会由 AND 连接。您可以省略搜索字词之间的 AND 运算符。

ANDOR 运算符是短路运算符。您可以在同一表达式中组合使用 ANDOR 规则。例如,当混合使用两个运算符时,表达式 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. Query 窗格中展开任意过滤条件菜单上的 Menu

  2. 优化过滤条件参数。

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

    要查看查询表达式中的搜索字词,请启用显示查询

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

对于某些 Compute Engine 资源类型(例如 gce_instancegce_network),您将看到带有资源 ID 的资源名称作为辅助文本。例如,对于 gce_instance 资源类型,您会看到虚拟机名称以及虚拟机 ID。资源名称可帮助您识别正确的资源 ID,然后据此构建查询。

按时间范围查看日志

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

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

使用时间范围选择器

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

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

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

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

如果查询编辑器字段包含带有时间戳的表达式,则时间范围选择器会停用,并且查询会使用时间戳表达式作为其时间范围限制。如果查询未使用时间戳表达式,则查询会使用时间范围选择器作为其时间范围限制。

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

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

  1. 如果您在 Query 窗格中没有看到查询编辑器字段,请启用 Show query

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

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

  3. 查看查询后,点击运行查询

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

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

使用近期查询

当您运行任何查询时,该查询就会被添加到您的最近查询列表中,该列表包含 30 天内的最后 10,000 个唯一查询。

如需查看最近的查询,请选择查询窗格中的最近标签页。在最近标签页中,您可以查看以下选项:

  • 流式传输:如需运行查询并流式传输结果,请选择此选项。
  • 运行:如需运行查询,请选择此选项。
  • 更多选项:可让您查看查询表达式,并提供运行查询的选项,或将查询保存到已保存查询列表。您也可以直接选择查询来获取这些选项。

    如需保存查询,请执行以下操作:

    1. 点击另存为。系统随即会打开保存查询对话框。
    2. 填写以下字段:

      • 名称(必填):为查询提供名称。名称不得超过 64 个字符。
      • 说明(可选):提供说明以帮助标识查询的用途。
      • 包含摘要字段(可选):启用包含摘要字段并输入您要显示的摘要字段
      • 截断摘要字段(可选):启用截断摘要字段,并选择要截断的字符数,以及截断是在字段的开头还是结尾。
    3. 点击保存查询。您现在可以在“已保存的查询”列表中找到该查询。

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

保存查询

通过已保存的查询,您可以存储查询表达式,以便更加一致、高效地探索日志。Logs Explorer 的查询窗格中有一个已保存标签页,您可以通过该标签页访问已保存的查询。您还可以使用 Logging API 方法 savedQueries.create 保存查询。

控制台

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

  1. 点击 Query 窗格中的 Save。此时会打开保存查询对话框,其中的查询表达式显示在查询编辑器字段中。

  2. 填写以下字段:

    • 名称(必填):为查询提供名称。名称不得超过 64 个字符。
    • 说明(可选):提供说明以帮助标识查询的用途。
    • 添加自定义摘要字段(可选):启用包含摘要字段并输入您要显示的摘要字段
    • 截断摘要字段(可选):启用截断摘要字段,并选择要截断的字符数,以及截断是在字段的开头还是结尾。
  3. 点击保存查询。已保存的查询会显示在已保存标签页下的列表中。

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

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

API

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

您可以使用 savedQueries.create 方法的参考页面上的 API Explorer widget 执行该方法。对于 Logs Explorer 查询,您必须指定 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 项目的用户互相共享已保存的查询。您可以在已保存标签页中查看共享查询。

如需了解查看和修改共享查询所需的角色和权限,请参阅 Google Cloud 控制台权限。请注意,拥有 IAM 角色 roles/logging.adminroles/editor 的用户可以修改其他用户的共享查询。

创建共享查询

控制台

您可以共享已保存的查询,也可以共享新查询。

如需创建和共享查询,请执行以下操作:

  1. 在查询编辑器字段中输入查询。

  2. 点击保存

  3. 填写保存查询对话框中的字段。

  4. 启用与项目共享

  5. 点击保存查询

您的查询现已与 Google Cloud 项目的其他用户共享。

如需共享已保存的查询,请执行以下操作:

  1. 选择已保存标签页。

  2. 选择 更多选项,然后选择 修改,或者直接选择相应查询。

  3. 修改查询对话框中,启用与项目共享,然后点击更新查询

您的查询现已与 Google Cloud 项目的其他用户共享。

API

您可以使用 Logging API 来创建共享查询,只需使用 savedQueries.Create 方法并在 visibility 字段中指定 SHARED 值即可。

查看共享查询

控制台

如需快速查看所有共享查询,请对公开范围列进行排序以首先显示共享查询:

  1. 选择已保存标签页。

  2. 点击全部

  3. 公开范围列进行排序。

公开范围列会指明是否共享查询以及如何共享:

  • 由我共享:您保存并与 Google Cloud 项目的其他用户共享的查询。
  • 共享:Google Cloud 项目的其他用户已共享的查询。
  • 不公开:已保存且未与 Google Cloud 项目的其他用户共享的查询。

仅查看您的查询

要查看您创建或共享的已保存查询,请点击我的查询。现在,您会看到自己创建并保存的查询的列表。在公开范围列中,您可以看到未共享的不公开查询。您共享的查询通过由我共享表示。

使用建议的查询

Logging 会根据 Google Cloud 项目(例如您使用的 Google Cloud 产品)的上下文生成建议的查询。建议的查询可帮助您发现问题,并为您提供有关系统整体运行状况的数据洞见。例如,如果检测到您在使用 Google Kubernetes Engine,Logging 可能会建议一个查找容器的所有错误日志的查询。

如需查看和运行建议的查询,请选择 Query 窗格中的 Suggested 标签页。建议标签页显示了一个查询列表,每个查询都附有说明和以下选项:

  • 流式传输:如需运行查询并流式传输结果,请选择此选项。
  • 运行:如需运行查询,请选择此选项。
  • 更多选项:可让您查看查询表达式的详细信息,以及用于运行查询或保存查询的选项。您也可以直接选择查询来获取这些选项。

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

    • 选择查询所在的行。

    • 点击 更多,然后选择查看。此时会打开查询详情对话框。

    查询详情对话框中,您会看到该查询以及运行流式传输另存为选项:

    • 如需保存查询,请执行以下操作:

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

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

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

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

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

请注意以下预期行为:

  • 在后续网页加载时,系统可能不会以相同顺序显示相同的查询。
  • 您可能看不到任何建议的查询。
  • 有时,运行建议的查询不会返回任何日志。

从库中选择查询

Logging 基于常见使用场景和 Google Cloud 产品提供了一个查询库。这些查询可以帮助您在时间紧迫的问题排查会话期间高效地查找日志,并浏览日志以更好地了解可用的日志记录数据。

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

  1. Query 窗格中选择 Library 标签页。

  2. 所有查询列中,您会看到各类可用查询以及基于 Google Cloud 产品的查询子集。如需缩小所显示的查询范围,请点击任一产品。

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

  3. 如需查看查询表达式,请执行以下任一操作:

    a. 点击查询所在的行。

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

  4. 查询详情对话框中,您会看到查询以及运行流式传输另存为选项:

    • 如需保存查询,请执行以下操作:

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

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

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

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

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

后续步骤