构建日志查询

本页面介绍了如何在 Google Cloud Console 日志查看器(预览版)中构建查询以检索、优化和分析日志。

准备工作

无需工作区即可使用 Logging,除非您要向 Logging 发送来自 Amazon Web Services (AWS) 的日志。

日志查看器显示单个 Google Cloud 项目的日志。如果您使用的是工作区,则 Logging 不会合并多个受监控项目的日志。您必须选择特定项目才能查看其日志。

如果您使用工作区和 AWS,请选择 AWS 连接器项目来查看 AWS 日志。

开始使用

如需转到日志查看器(预览版),请执行以下操作:

  1. 转到 Google Cloud 导航菜单 ,然后依次选择 Logging > 日志查看器
    转到日志查看器
  2. 选择 Google Cloud 项目。
  3. 从版本选择器菜单中,将日志查看器版本从经典版切换为新的日志查看器预览版

您现在已进入日志查看器(预览版)。

构建查询

查询构建器窗格提供两种检索日志的方法:

  1. 查询构建器下拉菜单。
  2. 使用查询构建器语言的查询。
  3. 最近已保存建议的查询标签页。

query-builder-pane

以下部分介绍了如何构建和运行查询来检索日志。

查询构建器下拉菜单

通过下拉菜单,您可以向查询构建器添加查询参数。您可以使用下拉菜单选择资源、日志名称、日志严重级别和时间范围。这些选项对应于所有 Google Cloud 的运维套件日志的 LogEntry 字段。

查询构建器的下拉菜单

  • 资源:允许您指定 resource.type。您可以一次选择一项资源添加到查询构建器。条目使用逻辑运算符 AND
  • 日志名称:允许您指定 logName。您可以一次选择多个日志名称添加到查询构建器。选择多个条目时,使用逻辑运算符 OR
  • 严重级别:允许您指定 severity。您可以一次选择多个严重级别添加到查询构建器。选择多个条目时,使用逻辑运算符 OR

若要使用任意搜索参数菜单,请展开这些菜单并选择一个或多个参数,然后点击添加

构建查询之后,点击运行查询可以检索所需的日志条目。

具有时间限制的查询

您可以通过以下两种方式根据时间查询日志:

  1. 使用时间戳表达式进行查询
  2. 使用时间范围选择器进行查询

    “日志查看器”部分显示了两种按时间过滤的方法

如果您的查询带有时间戳,则时间范围选择器会处于停用状态,查询使用时间戳表达式作为其时间范围限制。如果查询不使用时间戳表达式,则会使用时间范围选择器作为其时间范围限制。

使用查询构建器语言的查询

您可以使用查询构建器语言在 Cloud Logging 查询构建器窗格、Logging API命令行界面中构建查询。

如需了解详情,请参阅查询构建器语言

以下是用于优化查询的一些建议。

优化查询

如需更高效地查找日志条目,请执行以下操作:

  • 使用编入索引的字段进行搜索。
  • 尽可能减少必须搜索的日志条目数。

使用编入索引的字段

如需利用索引,请使用等式运算符为索引字段指定确切的值。请勿使用子字符串匹配。

以下 LogEntry 字段会编入索引:

接下来的部分将介绍如何使用这些编入索引的字段来最大限度地减少要查询的日志条目数。

快速查找日志条目

通过减少日志、减少日志条目或缩小搜索时间范围,可以加快搜索速度。如果这三项都减少,效果会更好。

示例:使用正确的日志名称

指定包含您感兴趣的日志条目的日志。通过检查其中一个日志条目,确保您知道真正的日志名称。例如,日志查看器显示 Compute Engine 部分中有一个名为“activity_log”的日志。仔细检查活动日志条目后,您会发现该日志实际名为“compute.googleapis.com/activity_log”。

以下比较不正确。此比较与任何日志条目都不匹配,因为它使用的日志名称不正确:

    logName = "projects/my-project-id/logs/activity_log"   # WRONG!

以下比较正确。此比较会从活动日志中选择日志条目。您必须对日志名称进行网址编码,如下所示:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"

示例:选择正确的日志条目

如果您知道需要的日志条目来自特定虚拟机实例,则指定该实例。通过检查您想要搜索的其中一个日志条目来检查正确的标签名称。在以下示例中,instance_id 是编入索引的标签之一:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"
    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"

您必须为资源类型指定值。否则,instance_id 的比较不会使用索引。

示例:选择正确的时间段

您应指定要搜索的时间段。快速确定 RFC 3339 格式的有效时间戳的一种方法是使用 Gnu/Linux date 命令:

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

在以下查询中使用这些时间戳的值。如需创建 Logging 接受的时间戳,请将日期和时间之间的空格替换为字母 T

例如,要在最近三个小时内搜索,请输入:

    timestamp >= "2016-06-27T14:40:00-04:00"

再举一例,若要在前五个小时到前三个小时之间搜索,请输入:

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

如需查看使用时间戳的其他示例,请转到本页中的临时字段索引

尽可能减少全局搜索和子字符串搜索

输入日志记录查询时,请避免尝试走捷径。

示例:不要在编入索引的字段中使用子字符串

您要在 Apache2 网络服务器中搜索日志条目。您知道 Apache 日志名为 apache-accessapache-error。您要怎么做?

  • 不要使用子字符串匹配来减少一些输入:

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • 搜索编入索引的字段时,务必使用完全匹配:

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

在您执行子字符串搜索时,编入索引的字段速度优势荡然无存。

示例:不要使用全局搜索

您要在负载中搜索包含“Hello, Kitty”的日志条目:

  • 不要使用全局搜索。一个原因是全局搜索都是子字符串搜索:

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • 务必将搜索限制为单个字段,即使您必须保留子字符串搜索也是如此:

        textPayload:"Hello, Kitty"
    
  • 如果可以,请务必使用等式测试:

        textPayload = "Hello, Kitty"
    
  • 如果日志条目包含结构化负载,请务必引用负载中的各个字段。

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • 务必使用编入索引的字段来限制搜索:

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

搜索示例

显示的日志条目是与搜索查询框中的查询匹配的日志条目。如果跳转到日期菜单包含值,则显示内容会滚动到相应时间点。下面是一些查询示例:

resource.type=gae_app

如果您从资源日志菜单中选择了 GAE 应用(所有模块 ID),并从日志名称菜单中选择了所有日志,则查找的日志条目与基本查询界面会显示的日志条目相同。如需查看资源类型列表,请转到受监控的资源列表

在输入时,日志查看器会针对 resource.type 等字段提供补全建议。

resource.type=gae_app AND logName:request_log

从包含 request_log 的日志名称中查找 App Engine 应用的日志条目。请注意以下几点:

  • = 运算符表示完全相等。资源类型必须正好是 "gae_app",字母不区分大小写。
  • : 运算符表示“包含”。logName 字段必须包含 request_log,字母不区分大小写。实际的日志名称要长得多。使用 : 可能会导致搜索速度变慢。
  • 这两项比较由 AND 连接。您也可以使用 OR,但如果您省略此运算符,则假定为 AND
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

查找具有以下两种资源类型之一的日志条目:Compute Engine 虚拟机实例或 AWS EC2 虚拟机实例。日志条目的 severity 必须至少为 ERROR,这相当于在基本查询界面的严重级别菜单中选择错误。您无法在基本查询界面中查看来自多种资源类型的日志。

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

查找项目 [PROJECT_ID] 中的所有管理员活动审核日志条目。审核日志在项目中都使用相同的日志名称,但具有不同的资源类型。日志 ID cloudaudit.googleapis.com/activity 必须在日志名称中进行网址编码。在比较中使用等式可加快搜索速度。如需了解详情,请参阅了解审核日志

unicorn

在任何字段中查找包含 unicorn(字母不区分大小写)的日志条目。不属于字段比较的搜索字词是一个“所有字段”查询。

unicorn phoenix

在某些字段中查找包含 unicorn 的日志条目,而在某些字段中查找包含 phoenix 的日志条目。

textPayload:(unicorn phoenix)

查找 textPayload 字段同时包含 unicornphoenix(字词不限顺序)的日志条目 - 这两个字词之间隐含 AND

textPayload:"unicorn phoenix"

查找 textPayload 字段包含字符串 "unicorn phoenix" 的日志条目。这与在基本查询界面中相同。

NOT textPayload: "unicorn phoenix"

查找 textPayload 字段不包含字符串 "unicorn phoenix" 的日志条目。这种类型的查询可以减少不必要的日志条目。

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

查找 30 分钟时间段内的日志条目。

已保存的查询

查询构建器窗格中有一个已保存标签页,您可以在该标签页中访问已保存的查询。

已保存查询的列表

通过已保存的查询,您可以存储查询表达式,这有助于您以更一致、更高效的方式探索日志。

如需保存已在查询构建器窗格中构建的查询,请执行以下操作:

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

  2. 为查询添加名称

    名称的长度不得超过 64 个字符。

  3. 可选:如需向查询添加摘要字段,请打开包含摘要字段 (Include summary fields)。

  4. 可选:为查询添加说明

    说明的长度不得超过 1000 个字符。请勿包含任何敏感信息。

  5. 点击对话框中的保存查询

此时您的已保存的查询会出现在查询构建器窗格中已保存标签页下的列表里。

如需运行已保存的查询,请点击运行查询

最近查询

查询构建器窗格包含一个最近标签页。运行查询时,该查询会添加到最近查询列表中,其中包含近 30 天的最后 10000 个非重复查询。

“最近”标签页显示最近查询。

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

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

    要运行查询,请选择运行

    要保存查询,请选择另存为,然后填写以下字段:

    • 名称(必填):提供名称。
    • 说明(可选):提供说明以帮助标识查询的用途。
    • 添加摘要字段(可选):启用添加摘要字段,然后输入要显示的字段。
    • 截断摘要字段(可选):启用截断摘要字段,然后选择要截断的字符数,并选择是在字段开头还是结尾处进行截断。

    选择保存查询。该查询现已在已保存的查询列表中提供。

请注意,您还可以过滤最近查询;过滤条件与查询表达式中的文本匹配。

建议的查询

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

如需在查询构建器窗格中查看和运行“建议的查询”,请执行以下操作:

  1. 点击建议标签页。

    显示一组查询的“建议的查询”标签页

  2. 查看“建议的查询”的说明。

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

    a.点击相应的行。

    b. 点击更多 并选择查看

  4. 在查询构建器窗格中,您会看到该查询以及用于运行查询或保存查询的选项。

    a.要保存查询,请点击保存。此时,该查询会显示在已保存列表中,其中,您可以选择以后再运行该查询。

    b. 如需运行查询,请点击运行。 该查询会显示在查询构建器窗格中的查询预览下。

  5. 查看查询后,点击运行查询。建议的查询的结果会显示在查询结果下。

建议的查询是根据 Google Cloud 项目上下文动态创建的。而连续的页面加载可能不会按同一顺序显示相同的查询。这是正常情况。

问题排查

不带英文引号的文本

如果文本字符串不包含空格或某些特殊字符,则无需使用英文引号引起来。这称为不带英文引号的文本,例如前述示例中的字词 ERROR字符串 "v1.compute.instances.insert" 加了英文引号,因为它包含英文句点。如果您想在字符串内包含英文引号,请在英文引号前面加上反斜杠。

语法问题

如果使用查询构建器语言时遇到问题,请检查以下各项:

  • 您的查询应遵循语法规则,并使用匹配的括号和引号。您的查询不能包含评论。

  • 您的日志条目字段名称应正确拼写。

  • 布尔运算采用大写字母(ANDORNOT)。

  • 为明确起见,作为全局限制的布尔表达式或作为比较运算右侧的布尔表达式应加英文括号。例如,以下两个查询看起来相同,但实际并不相同:

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • 不带英文引号的文本不得包含任何特殊字符。如果不确定,请添加英文双引号。例如,由于嵌入了子字符串运算符 (:),下面的第一个比较运算不符合规则。比较运算必须用英文引号括起来:

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • gcloud 日志记录要求查询采用英文双引号。如需使用英文双引号通过 gcloud logging 命令进行转义特殊字符写入,请改用英文单引号将整个查询引起来:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
    
  • 如果您要编写包含时间戳的查询,则必须从搜索查询框下方的时间范围选择器中选择无限制