高级日志查询

本指南介绍了如何使用日志查看器(经典版)编写高级日志查询,这些查询即可从任意数量日志中指定一组日志条目的表达式。高级日志查询可用于日志查看器(经典版)Logging APIgcloud 命令行工具

如需详细了解基本查询选项,请转到基本日志查询

如需查看用于查找日志的推荐查询列表,请转到示例查询

简介

高级日志查询是一个布尔表达式,用于指定项目中的部分日志条目。它可用于执行以下任何操作:

  • 从特定日志或日志服务中选择日志条目。
  • 选择某一时间范围内的日志条目。
  • 选择满足元数据或用户定义字段条件的日志条目。
  • 选择所有日志条目的采样百分比。

开始使用高级日志查询

如需在日志查看器中使用高级日志查询,请执行以下操作:

  1. 转到 Cloud Console 中的 Google Cloud 运维套件 Logging > 日志(日志查看器)页面:

    转到“日志查看器”页面

  2. 在页面顶部选择一个现有 Google Cloud 项目,或者创建一个新项目。

  3. 使用下拉菜单,选择您要查看其日志的资源。

  4. 在搜索查询框中点击下拉菜单,然后选择转换为高级过滤条件

显示转换为高级过滤条件的界面。

日志查询在界面中被标记为“过滤条件”,因为借助它们可以选择一组特定的日志条目。

高级日志查询界面如下所示:

显示高级过滤条件选项的界面。

此查询界面上没有日志选择菜单,但有提交过滤条件按钮,您可以通过这些特征进行辨别。日志查看器会显示满足查询中所有指定条件的日志条目。

以下是高级日志查询的一个简单示例:

    resource.type = "gce_instance" AND
        severity >= ERROR AND
        NOT textPayload:robot
    

此查询与 Compute Engine 中严重程度值至少为 ERRORtextPayload 字段中不包含字符串 robot 的日志条目相匹配。字符串比较不区分大小写。 名称 resourceseveritytextPayload 是在 LogEntry 类型中定义的。

在输入时显示建议并突出显示:当您在日志查看器中输入高级日志查询时,系统可能会显示特定日志条目字段的建议。这些建议来自日志查看器已加载的查询语言和实际日志条目集。若要选择某个建议,请按 TAB。如果系统未显示建议,请尝试按 CTRL + SPACE。查询表达式的不同部分以不同颜色突出显示。如果您的表达式是鲜红色,则您到目前为止输入的查询可能有错误或可能不完整。

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

最佳做法:在要与字段值进行比较的字符串中添加英文引号。这样可以防止发生错误,以免比较含义改变且难以调试。如果字词以字母开头,后跟一系列字母、数字或下划线 (_) 字符,则无需使用英文引号引起来。

使用键盘:如果您使用键盘在搜索查询框中输入高级日志查询,可以按 ESC 退出修改模式,然后按 TAB 转到其他选项,例如下拉菜单提交过滤条件按钮。

高级日志查询语法

本部分介绍了如何构建高级日志查询以及如何执行匹配。

语法表示法

系统使用以下表示法描述高级日志查询语法:

  • a = e 表示 a 是表达式 e 的名称。
  • a b 表示“a 在前面,后跟 b”。
  • a | b 表示“a 或 b”。
  • ( e ) 用于分组。
  • [ e ] 表示 e 是可选项。
  • { e } 表示 e 可以重复 0 次或更多次。
  • "abc" 表示 abc 必须如显示的那样写入。

语法摘要

本部分简要介绍了高级日志查询语法。某些详细信息已予以省略,但若您需要,可以参阅以下各部分中的说明。

高级日志查询是包含表达式的字符串:

    expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
    

比较运算可以是单个值,也可以是布尔表达式:

  "The cat in the hat"
      resource.type = "gae_app"
    

第一行是比较运算为单个值的示例。这些类型的比较运算称为全局限制。系统会隐式使用包含运算符将日志条目的每个字段与该值进行比较。对于此示例,如果 LogEntry 中的任何字段或其载荷包含短语“The cat in the hat”,则比较运算成功。

第二行是比较运算为布尔表达式的示例,格式为 [FIELD_NAME] [OP] [VALUE]。下面介绍了比较运算的元素:

  • [FIELD_NAME]:日志条目中的一个字段。例如 resource.type

  • [OP]:比较运算符。例如 =

  • [VALUE]:数字、字符串、函数或带英文括号的表达式。 例如 "gae_app"

以下部分详细介绍了查询和匹配。

布尔运算符

布尔运算符 ANDOR短路运算符NOT 运算符具有最高优先级,OR 次之,AND 最低。例如,以下两个表达式是等效的:

a OR NOT b AND NOT c OR d
    (a OR (NOT b)) AND ((NOT c) OR d)
    

您可以省略比较运算之间的 AND 运算符。您还可以将 NOT 运算符替换为 -(减号)运算符。例如,以下两个高级日志查询是相同的:

a=b AND c=d AND NOT e=F
    a=b c=d -e=f
    

本文档均使用 ANDNOT

比较运算

比较运算具有以下形式:

[FIELD_NAME] [OP] [VALUE]
    

下面介绍了比较运算的元素:

  • [FIELD_NAME]:日志条目中字段的路径名。字段名称的示例如下所示:

    resource.type
        resource.labels.zone
        resource.labels.project_id
        insertId
        jsonPayload.httpRequest.protocol
        labels."compute.googleapis.com/resource_id"
        

    如需了解详情,请查看本页上的字段路径标识符

  • [OP]:比较运算符,包含以下几种:

    =           # equal
        !=          # not equal
        > < >= <=   # numeric ordering
        :           # "has" matches any substring in the log entry field
        
  • [VALUE]:数字、字符串、函数或带英文括号的表达式。 字符串用于表示任意文本,以及布尔值、枚举值和字节字符串值。 在比较之前,[VALUE] 会转换为字段的类型。

如果 [VALUE] 是带英文括号的布尔型比较运算组合,则字段名称和比较运算符将应用于每个元素。例如:

    jsonPayload.cat = ("siamese" OR "shorthair")
        jsonPayload.animal : ("nice" AND "pet")
    

第一个比较运算检查字段 cat 是否包含值“siamese”或“shorthair”。第二个比较运算检查字段 animal 的值是否同时包含字词“nice”和“pet”(字词不限顺序)。

字段路径标识符

所有日志条目都是类型为 LogEntry 的实例。位于比较运算左侧的标识符必须是在 LogEntry 类型中定义的字段。如需详细了解可能的标识符及其值,请查看 LogEntry 类型

下面是当前的日志条目字段列表。每个字段后跟该字段的下一级别的名称(如果适用):

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status, userAgent }
  • insertId
  • jsonPayload { 变量 }
  • labels { 变量 }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, 变量 }
  • receiveTimestamp
  • resource { type, labels }
  • severity
  • sourceLocation: { file, line, function }
  • spanId
  • textPayload
  • timestamp
  • trace

下面是您可以在比较运算中使用的字段路径标识符的示例:

  • resource.type:如果您的第一个路径标识符是 resource,则下一个标识符必须是 MonitoredResource 类型中的字段。

  • httpRequest.latency:如果您的第一个路径标识符是 httpRequest,则下一个标识符必须是 HttpRequest 类型中的字段。

  • labels.[KEY] 如果您的第一个路径标识符是 labels,则下一个标识符 [KEY] 必须是 labels 字段中出现的键值对中的一个键。

  • logName:由于 logName 字段是一个字符串,因此该字段后面不能跟有任何子字段名称。

如需详细了解如何使用引用对象或数组的字段路径标识符,请转到本页上的对象和数组类型

受监控的资源类型

为加快搜索速度,请指定受监控的资源类型。如需查看资源类型列表,请转到受监控的资源类型

例如,Compute Engine 虚拟机使用资源类型 gce_instance,而 Amazon EC2 实例使用 aws_ec2_instance。以下示例展示了如何将搜索限制为这两种虚拟机类型:

    resource.type = ("gce_instance" OR "aws_ec2_instance")
    

日志中受监控的资源类型值已编入索引,对这些值使用子字符串匹配会导致查询速度变慢。

缺失字段

如果您在查询中使用了字段名称,且该字段没有出现在日志条目中,则该字段为缺失未定义默认字段:

  • 如果该字段属于日志条目的载荷(jsonPayloadprotoPayload),或者它位于日志条目的 labels 部分内的标签中,则该字段为缺失字段。使用缺失字段不会显示错误,但使用缺失字段的所有比较运算都会失败,且不发出任何提示。

    示例:jsonPayload.nearest_storeprotoPayload.name.nickname

  • 如果该字段是在 LogEntry 类型中定义的,则该字段为默认字段。比较运算会按照该字段存在并且具有默认值的情况执行。

    示例:httpRequest.remoteIptraceoperation.producer

  • 否则,该字段为未定义字段,在使用查询之前会检测到此错误。

    示例:thudoperation.thudtextPayload.thud

如需测试是否存在缺失字段或默认字段,而不测试字段中是否有特定值,请使用 :* 比较运算。例如,如果日志条目中明确存在字段 operation.id,则以下比较运算会成功:

operation.id:*
    

对象和数组类型

每个日志条目字段都可以包含标量、对象或数组

  • 标量字段存储单个值,如 174.4-1string 也被视为标量。可与字符串相互转换的字段(如 DurationTimestamp)也是标量类型。

  • 对象类型存储一组指定值,如以下 JSON 值:

    {"age": 24, "height": 67}
        

    您可以引用对象内的值。例如,如果 jsonPayload.x 包含了前面的值,则 jsonPayload.x.age 将包含值 24

  • 数组字段存储值列表(所有值的类型相同)。例如,包含测量结果的字段可能具有数字数组:

    {8.5, 9, 6}
        

    在执行比较运算且 [FIELD_NAME] 为数组字段时,每个数组成员都会与 [VALUE] 比较,并且结果会通过 OR 运算符组合在一起。例如,如果 jsonPayload.shoeSize 是存储 {8.5, 9, 6} 的数组字段,则比较运算:

    jsonPayload.shoeSize < 7
        

    等效于:

    8.5 < 7 OR 9 < 7 OR 6 < 7
        

    在此示例中,整体比较计算结果成功。

值和转换

评估比较运算的第一步是将右侧值转换为日志条目字段的类型。比较运算中允许使用标量字段类型,以及另外两种其值表示为字符串的类型:DurationTimestamp。如需查看标量类型列表,请转到标量协议缓冲类型列表。下表说明了可以将哪些值转换为日志字段类型:

字段类型 允许的查询值
bool “True”或“false”,字母不区分大小写。示例:“True”、“true”。
bytes 字符串,包含任意字节序列。示例:“\377\377”。
Duration 字符串,包含带符号小数,后跟“ns”、“us”、“ms”、“s”、“m”或“h”单位之一。持续时间精确到纳秒。示例:“3.2s”。
enum 枚举类型字面量的名称,不区分大小写。示例:“WARNING”,它是类型为 LogSeverity 的值。
double 任何数字(带符号或无符号和指数部分),或特殊值字符串“NaN”、“-Infinity”和“Infinity”(无论大小写)。示例:“-3.2e-8”、“nan”。
intNN 任何带符号整数,不超过带符号整数类型的大小。示例:“-3”。
string 任何包含 UTF-8 编码或 7 位 ASCII 文本的字符串。嵌入式英文引号必须使用反斜杠进行转义。
Timestamp 采用 RFC 3339ISO 8601 格式的字符串。例如:“2014-10-02T15:01:23.045Z”(RFC 3339)、“2014-10-02”(ISO 8601)。在查询表达式中,采用 RFC 3339 格式的时间戳可以使用“Z”或 ±hh:mm 指定时区。时间戳可以精确到纳秒。
uintNN 任何无符号整数,不超过无符号整数类型的大小。示例:“1234”。

如果尝试转换失败,则比较失败。

当转换需要字符串时,如果它们不包含空格和运算符等特殊字符,您也可以使用数字或不带英文引号的文本。同样,如果转换需要数字,您可以使用其内容为数字的字符串。

类型 intNNuintNN 表示各种大小的整数类型,例如 int32uint64。在写入要转换为 64 位整数类型的值时,您应以字符串形式写入该值,例如“9223372036854775807”。

日志字段的类型

下面介绍了如何确定日志条目字段的类型:

  • 类型 LogEntry 及组件类型中定义的日志字段为协议缓冲区字段。协议缓冲区字段具有显式类型。

  • 属于 protoPayload 对象的日志字段也是协议缓冲区字段,具有显式类型。协议缓冲区类型的名称存储在 protoPayload"@type" 字段中。如需了解详情,请查看 JSON 映射

  • jsonPayload 内的日志字段的类型是收到日志条目时根据字段的值推断出的类型:

    • 如果字段的值为不带英文引号的数字,则该字段的类型为 double
    • 如果字段的值为 truefalse,则该字段的类型为 bool
    • 如果字段的值为字符串,则该字段的类型为 string

    长(64 位)整数存储在字符串字段中,因为它们不能精确表示为 double 值。

  • DurationTimestamp 类型只能在协议缓冲区字段 {:class="external"} 中识别。在其他位置,这些值存储在字符串字段中。

比较运算符

等式(=!=)和不等式(<<=>>=)运算符的含义取决于左侧字段名称的基础类型。

  • 所有数字类型:等式和不等式具有其常规数字含义。
  • bool:等式表示布尔值相同。不等式通过 true > false 来定义。
  • enum:等式表示枚举值相同。不等式使用枚举字面量的基础数值。
  • Duration:等式表示持续时间的长度相同。不等式基于持续时间的长度。例如:持续时间 "1s" > "999ms"
  • Timestamp:等式表示同一时刻。如果 abTimestamp 值,则 a < b 表示在时间上 a 早于 b
  • bytes:操作数按字节从左到右逐一比较。
  • string:比较运算会忽略字母大小写。具体来说,两个操作数必须先使用 NFKC_CF Unicode 归一化进行归一化,然后按字典顺序比较。

子字符串运算符 (:) 适用于 stringbytes,除了右侧操作数只需等于左侧字段的某个部分之外,其处理方式与等式相同。编入索引的字段的子字符串匹配未充分利用日志索引。

全局限制

如果比较运算包含单个值,则称为全局限制。Logging 使用包含运算符 (:) 确定日志条目的任何字段或条目的载荷是否包含全局限制。如果包含,则比较会成功。

根据全局限制编写的最简单的高级日志查询为单个值:

"The Cat in The Hat"
    

您可以使用 ANDOR 运算符组合全局限制以获得更符合需要的查询。例如,如果要显示一个字段包含 cat,一个字段包含 hatbat 的所有日志条目,请按以下所示编写查询:

(cat AND (hat OR bat))
    

在本例中,有三个全局限制:cathatbat。这些全局限制会单独应用,而结果会进行组合,就像未使用英文括号编写表达式一样。

全局限制是一种在日志中搜索特定值的简便方式。 例如,如果您在活动日志中查找提及到 GCE_OPERATION_DONE 的条目,则可以使用以下查询:

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

虽然全局限制使用简单,但速度可能较慢;如需了解详情,请查看本页中的快速查找日志条目

函数

您可以在高级查询中使用内置函数作为全局限制:

function = identifier ( [ argument { , argument } ] )
    

其中,argument 为值、字段名称或带英文括号的表达式。 以下各部分介绍了这些函数。

示例

sample 函数选择日志条目总数的一部分:

sample([FIELD], [FRACTION])
    

[FIELD] 是日志条目中字段的名称,如 logNamejsonPayload.a_field。该字段的值确定日志条目是否在样本中。字段类型必须为字符串或数值。 建议将 [FIELD] 设置为 insertId,因为对于该字段,每一个日志条目都具有不同的值。

[FRACTION] 是具有 [FIELD] 包含的值的日志条目所占的比例。它是一个大于 0.0 且小于等于 1.0 的数字。 例如,如果您指定 0.01,则样本所包含的日志条目大约占具有 [FIELD] 值的所有日志条目的 1%。如果 [FRACTION] 为 1,则选择具有 [FIELD] 值的所有日志条目。

示例:以下查询返回日志 syslog 中 25% 的日志条目:

    logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)
    

详细信息:基于哈希技术的确定性算法用于确定日志条目包含在样本中还是从样本中排除。所生成的样本的准确率取决于哈希值的分布。如果哈希值分布不均匀,则生成的样本可能会出现偏差。在最坏的情况下,如果 [FIELD] 始终包含相同的值,则生成的样本将包含所有日志条目的 [FRACTION] 或不包含任何日志条目。

如果 [FIELD] 出现在日志条目中,则:

  • 计算哈希值。
  • 该哈希值(数字)除以最大可能的哈希值。
  • 如果得出的比例小于或等于 [FRACTION],则日志条目包含在样本中;否则日志条目从样本中排除。

如果 [FIELD] 未出现在日志条目中,则:

  • 如果 [FIELD] 属于日志条目的载荷部分或 labels 部分,即使 [FRACTION] 为 1,系统也不会为该样本选择日志条目。
  • 否则,日志条目会按照 [FIELD] 在日志条目中且 [FIELD] 的值为默认值进行处理。默认值由 LogEntry 类型确定。如需详细了解缺失字段和默认字段,请查看本页中的缺失字段

如需从样本中排除包含默认字段的日志条目,请使用判断字段是否存在的运算符 :*。以下查询生成 1% 的日志条目样本,这些日志条目已明确提供 field 的值:

field:* AND sample(field, 0.01)
    

ip_in_net

ip_in_net 函数确定日志条目中的 IP 地址是否包含在子网中。您可以使用此函数来判断请求是来自内部还是外部来源。例如:

ip_in_net([FIELD], [SUBNET])
    

[FIELD] 是日志条目中包含 IP 地址或 IP 地址范围的字符串值字段。该字段可以重复,在这种情况下,只有一个重复字段必须包括子网中包含的地址或地址范围。

[SUBNET] 是 IP 地址或 IP 地址范围的字符串常量。如果 [SUBNET] 不是合法的 IP 地址或 IP 地址范围,则会出错,如本部分稍后所述。

示例:以下查询测试来自日志 my_log 的日志条目载荷中的 IP 地址:

    logName = "projects/my_project/logs/my_log" AND
        ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")
    

详细信息:如果在日志条目中,[FIELD] 为缺失字段或默认字段,或者不包含合法 IP 地址或 IP 地址范围,则该函数会返回 false。如需详细了解缺失字段和默认字段,请查看本页中的缺失字段

以下是受支持的 IP 地址和范围的示例:

  • IPv4:10.1.2.3
  • IPv4 子网:10.1.2.0/24
  • CIDR IPv6:1234:5678:90ab:cdef:1234:5678:90ab:cdef
  • CIDR IPv6 子网:1:2::/48

按时间搜索

在高级日志查询界面中,您可以对要显示的日志条目的日期和时间设置特定限制。例如,如果您向查询添加以下条件,日志查看器会精确显示在指定的 30 分钟时间段内的日志条目,并且您无法滚动查看该日期范围外的日志条目:

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

在编写带有时间戳的查询时,您使用的日期和时间格式必须如上所示。您还必须从搜索查询框下方的时间范围选择器中选择无限制

快速查找日志条目

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

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

使用编入索引的字段

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

以下 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" 的日志条目。这与在基本查询界面中相同。

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

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

问题排查

键盘导航

如果您使用键盘在搜索查询框中输入高级查询,并且需要转到该页面上的其他菜单,请按ESC 退出修改模式,然后按 TAB 转到其他选项。

语法问题

如果高级查询的表达式出现问题,请检查以下各项:

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

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

  • 布尔运算采用大写字母(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."'
        
  • 日志查看器的基本查询中的搜索表达式与高级日志查询中的搜索表达式不同。如需了解详情,请转到基本查询和高级查询的差异

  • 如果您要编写包含时间戳的查询,则必须从搜索查询框下方的时间范围选择器中选择无限制