此页面由 Cloud Translation API 翻译。

使用 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 控制台构建查询，请执行以下操作：

在 Google Cloud 控制台中，转到 Logs Explorer 页面。
前往 Logs Explorer

如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。
选择 Google Cloud 项目或其他 Google Cloud 您要查看其日志的资源。
使用查询窗格构建查询。

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 为。

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

在任意设备上展开菜单 Query 窗格中过滤条件菜单的位置。
优化过滤器参数。
点击应用。您会在查询编辑器字段中看到参数。

若要查看查询表达式中的搜索字词，请启用显示查询。
查看查询后，点击运行查询。使用 查询结果窗格中会显示查询内容。

对于某些 Compute Engine 资源类型，例如 gce_instance 和 gce_network 时，您会看到资源名称以辅助文本形式显示资源 ID。对于例如，对于 gce_instance 资源类型，您会看到虚拟机名称以及虚拟机 ID资源名称可帮助您识别可用于构建查询的资源 ID。

按时间范围查看日志

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

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

使用时间范围选择器

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

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

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

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

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

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

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

如果在 Query 窗格中没有看到查询编辑器字段，请启用 显示查询。
直接在查询编辑器字段中输入查询表达式。

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

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

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

使用近期查询

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

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

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

如需保存查询，请执行以下操作：
1. 点击另存为。保存查询对话框随即会打开。
2. 填写以下字段：
  - 名称（必需）：提供查询的名称。名称限制为 64 个字符。
  - 说明（可选）：提供说明以帮助标识查询的用途。
  - 包含摘要字段（可选）：启用包含摘要字段 然后输入您要显示的摘要字段。
  - 截断摘要字段（可选）：启用 截断摘要字段，然后选择截断至，以及是否截断字段。
3. 点击保存查询。您现在可以在“已保存的查询”列表中找到该查询。

您还可以对近期查询进行排序和过滤；过滤条件与文本匹配。

保存和共享查询

通过已保存的查询，您可以存储查询表达式，以便更深入地探索日志。日志浏览器的查询窗格 已保存标签页，方便您访问已保存的查询。您还可以使用 Logging API 方法保存查询 savedQueries.create。

您可以保存查询，使其不对外公开，并且只有您自己可以查看可与 Google Cloud 项目的其他成员共享。分享查询，则您以及项目中的所有成员都不再拥有该查询即可访问该查询

控制台

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

点击 Query 窗格中的 Save。保存查询对话框随即会打开，在查询编辑器字段中使用查询表达式。
填写以下字段：
- 名称（必需）：提供查询的名称。名称限制为 64 个字符。
- 说明（可选）：提供说明以帮助标识查询的用途。
- 添加自定义摘要字段（可选）：启用包含摘要字段中，然后输入所需的摘要字段。要显示的内容。
- 截断摘要字段（可选）：启用 截断摘要字段，然后选择截断至，以及是否截断字段。
- 与项目共享：（可选）启用与项目共享以执行以下操作：与 Google Cloud 项目的其他成员共享您的查询。
点击保存查询。您保存的查询会显示在列表。

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

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

如需删除已保存的查询，请选择 更多选项。然后选择删除。

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

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 项目的已保存标签页中：

控制台

在 Google Cloud 控制台中，转到 Logs Explorer 页面。
前往 Logs Explorer

如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。
选择 Google Cloud 项目或其他 Google Cloud 您要查看其日志的资源。
点击已保存。

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

共享：与 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 数据。

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

在 Query 窗格中选择 Library 标签页。
在所有查询列中，您会看到各种可用的基于 Google Cloud 产品构建的查询和查询子集。要缩小显示的查询范围，请点击产品。

您还可以使用搜索字段按类别、说明或查询表达式的内容。
如需查看查询表达式，请执行以下任一操作：

a. 点击查询所在的行。

b. 点击更多，然后选择查看。
在查询详细信息对话框中，您会看到该查询以及用于运行、流式传输或另存为：
- 如需保存查询，请执行以下操作：
  1. 点击另存为。
  2. 填写保存查询对话框中的字段。
  修改后的查询会显示在已保存列表中，您可以在其中选择稍后运行查询。
- 如需立即运行查询，请点击运行。查询会运行，并显示于查询编辑器字段。
- 如需立即运行查询并流式传输结果，请点击流式传输。
- 要关闭对话框并返回到建议的查询列表，请点击关闭。

后续步骤

示例查询