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

本文档介绍了如何在使用 Logs Explorer,方法是在查询编辑器字段中编写查询, 从过滤条件菜单中选择这些选项。通过 全部使用 日志记录查询语言

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

准备工作

  • 如需获取读取日志数据以构建查询所需的权限,请使用已保存的不公开查询 或列出并获取共享查询 请让管理员授予您 Logs Viewer (roles/logging.viewer) IAM 角色。

    此预定义角色包含 读取日志数据以构建查询、使用已保存的不公开查询、 或列出并获取共享查询。如需查看所需的确切权限,请展开所需权限部分:

    所需权限

    需要以下权限才能读取日志数据以构建查询、使用已保存的不公开查询。 或列出并获取共享查询:

    • 使用已保存的不公开查询: logging.queries.usePrivate
    • 列出并获取共享查询:
      • logging.queries.listShared
      • logging.queries.getShared
  • 要获取创建、更新和删除共享查询所需的权限, 请让管理员授予您 项目的 Logging Admin (roles/logging.admin) IAM 角色。

    此预定义角色包含创建、更新和删除共享查询所需的权限。如需查看所需的确切权限,请展开所需权限部分:

    所需权限

    如需创建、更新和删除共享查询,您需要具备以下权限:

    • logging.queries.share
    • logging.queries.updateShared
    • logging.queries.deleteShared

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

构建查询

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

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

    前往 Logs Explorer

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

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

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

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

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

跨日志字段搜索文本

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

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

您可以搜索字词和词组,搜索字词可包括 布尔值运算符正则表达式

  • 要执行区分大小写的搜索,您必须使用 正则表达式

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

    例如,要搜索包含字词 hello 和 单词 world,输入 hello world。此命令将转换为 SEARCH("hello world"),与包含令牌的日志条目匹配 helloworld,按任意顺序排列。由于搜索不区分大小写, 该搜索还与包含令牌 HelloWorld。搜索条件与令牌 worlds 不匹配。

  • 要沿着词法单元边界对词组执行不区分大小写的搜索, 用反引号将这个词组括起来。

    例如,要搜索词组“hello world”, 输入 `hello world`。 此命令将转换为 SEARCH("`hello world`")。 匹配包含令牌 hello world 的日志条目。 搜索与令牌 hello worlds 不匹配。

  • 要对子字符串执行不区分大小写的搜索,请将文本换行 双引号。例如,"hello world"Hello World 匹配,并且 Hello world。同一查询也与 hello worlds 匹配,因为 不会沿着词元边界执行搜索。

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

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

布尔运算符

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

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

  • 您不能使用括号嵌套规则。搜索内容中的任何括号 表达式解析为搜索字词。
  • 布尔运算符必须采用大写形式。小写 andor、 和 not 会解析为搜索字词,而不是运算符。

如果不包含任何运算符,所有搜索字词和词组都会由 AND。您可以省略搜索字词之间的 AND 运算符。

ANDOR 运算符为 短路运算符。 您可以在同一表达式中合并 ANDOR 规则。例如,当 两个运算符混合使用,表达式 a AND b OR c AND d 将转换为 以下 Logging 查询语言表达式:

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

NOT 运算符具有最高优先级,其次是 ORAND

NOT 运算符会对后续项执行求反运算。例如,NOT error 会返回不包含 error 的日志条目。您还可以将 NOT 运算符替换为 -(减号)运算符。例如,以下两个 都是一样的:

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

此逻辑也适用于短语,但前提是 -(减号)运算符位于 引号。例如,以下两个查询是相同的:

-"response successful"
NOT "response successful"

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

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

资源日志名称菜单中的选项来源于 Cloud Logging 存储的日志条目。

查询编辑器的过滤菜单

  • 资源:可让您指定 resource.type 和 关联的resource.labels。您可以使用 此过滤条件菜单,以及零个或多个要应用于 查询。资源参数由逻辑运算符 AND 连接。
  • 日志名称:允许您指定 logName。您可以选择 要应用于查询的多个日志名称选择多个日志时 则使用逻辑运算符 OR
  • 严重程度:可让您指定严重程度。您可以选择 多个严重级别,以应用于您的查询。 选择多个严重级别时,逻辑运算符 OR 为 。

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

  1. 在任意设备上展开 菜单 Query 窗格中过滤条件菜单的位置。

  2. 优化过滤器参数。

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

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

  4. 查看查询后,点击运行查询。使用 查询结果窗格中会显示查询内容。

对于某些 Compute Engine 资源类型,例如 gce_instancegce_network 时,您会看到资源名称以辅助文本形式显示资源 ID。对于 例如,对于 gce_instance 资源类型,您会看到虚拟机名称 以及虚拟机 ID资源名称可帮助您确定正确的资源 ID,以便您据此构建查询。

按时间范围查看日志

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

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

使用时间范围选择器

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

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

在查询编辑器字段中包含时间戳表达式

如需直接将时间戳表达式添加到查询编辑器字段,请执行以下操作: 使用 日志记录查询语言

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

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

您可以使用 要构建的日志记录查询语言 日志浏览器查询编辑器字段中的更多高级查询:

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

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

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

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

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

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

使用近期查询

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

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

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

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

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

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

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

保存和共享查询

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

您可以将查询保存为不公开状态,仅供您自己查看,也可以与 Google Cloud 项目的其他成员共享。分享 查询,则您以及项目中的所有成员都不再拥有该查询 即可访问该查询

控制台

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

  1. 点击 Query 窗格中的 Save保存查询对话框随即会打开, 在查询编辑器字段中使用查询表达式。

  2. 填写以下字段:

    • 名称(必需):为查询提供名称。名称限制为 64 个字符。
    • 说明(可选):提供说明以帮助标识查询的用途。
    • 添加自定义摘要字段(可选):启用添加摘要字段,然后输入要显示的摘要字段
    • 截断摘要字段(可选):启用 截断摘要字段,然后选择 截断至,以及是否截断 字段。
    • 与项目共享:(可选)启用与项目共享以执行以下操作: 与 Google Cloud 项目的其他成员共享您的查询。
  3. 点击保存查询。您保存的查询会显示在 已保存标签页下的列表。

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

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

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

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

API

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

您可以使用savedQueries.create 方法参考页面上的 APIs 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 项目的其他成员共享查询,请在 visibility 字段中指定值 SHARED

查看已保存的查询

您可以查看不公开查询以及与其他成员共享的查询 在 Google Cloud 项目的已保存标签页中:

控制台

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

    前往 Logs Explorer

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

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

  3. 点击已保存

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

  • 共享:与 Google Cloud 项目。
  • 不公开:您保存的查询,仅对您本人可见。

API

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

例如,以下请求正文列出了所有共享日志浏览器 带有通配符位置 ID 的查询:

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

使用建议的查询

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

要查看和运行建议的查询,请选择建议的标签页 Query 窗格。建议标签会显示一系列查询,每个查询都包含 和以下选项:

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

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

    • 选择相应查询的行。

    • 点击 更多 然后选择查看。此时将打开 Query details 对话框。

    Query details 对话框中,您会看到该查询以及用于运行 在线播放另存为

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

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

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

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

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

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

请注意以下预期行为:

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

从库中选择查询

Logging 基于常见用途提供了一个查询库 支持请求和 Google Cloud 产品。这些查询可以帮助您 在时间关键的问题排查会话期间查找日志并浏览日志 以更好地了解可用的 Logging 数据。

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

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

  2. 所有查询列中,您会看到各种可用的 基于 Google Cloud 产品构建的查询和查询子集。 要缩小显示的查询范围,请点击 产品。

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

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

    a. 点击查询所在的行。

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

  4. 查询详细信息对话框中,您会看到该查询以及用于 运行流式传输另存为

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

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

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

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

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

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

后续步骤