使用 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")，与包含令牌的日志条目匹配 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"

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

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

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

查询编辑器的过滤菜单

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

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

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

  2. 优化过滤器参数。

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

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

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

对于某些 Compute Engine 资源类型，例如 gce_instance 和 gce_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. 填写保存查询对话框中的字段。

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

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

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

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

后续步骤