CloudWatch Logs Insights 查询语法
CloudWatch Logs Insights 支持您用来对日志组执行查询的查询语言。查询语法支持不同的函数和运算,包括但不限于常规函数、算术和比较运算以及正则表达式。您可以创建包含多个查询命令的查询。使用 Unix 风格的管道字符 (|) 将查询中的查询命令分开。有关查询语法的更多信息,请参阅支持的运算和函数。
CloudWatch Logs Insights 支持在查询中使用备注。CloudWatch Logs Insights 会忽略以哈希符号 (#) 开头的行。CloudWatch Logs Insights 会自动发现多种日志类型的字段,并生成以 @ 符号开头的字段。有关 CloudWatch Logs 自动生成的字段的更多信息,请参阅 Amazon CloudWatch 用户指南中的支持的日志和搜索到的字段。
CloudWatch Logs Insights 查询命令
下表列出了 CloudWatch Logs Insights 支持的查询命令,并包含基本示例。有关常规查询和其他日志类型的查询示例,请参阅 Amazon CloudWatch Logs 用户指南中的 示例查询。
命令 | 说明 | 示例 |
---|---|---|
|
指定要在查询结果中显示的字段。如果您在查询中多次指定此命令,则仅使用您在最后一次的命令中指定的字段。 |
以下示例查询包含字段
|
|
从日志事件检索指定的字段,以供显示。 您可以使用字段命令中的函数和运算来修改要显示的字段值,并创建新字段以供在查询的其余部分中使用。 |
以下示例对于日志组中的所有日志事件显示字段
以下示例创建并显示一个临时字段
|
|
根据一个或多个条件筛选查询的结果。 |
以下示例对
以下示例展示了类似查询,但查询结果不会显示单独的字段。反而,查询结果会针对持续时间超过 2000 的所有录入事件,显示
以下示例针对
以下示例返回字段
下一个示例返回字段
以下示例返回
最后一个示例返回
|
|
使用日志字段值计算聚合统计数据。您可以将
|
以下示例对
以下示例计算每小时的异常数量。
在示例中, |
|
对检索的日志事件排序。同时支持升序 ( |
以下示例根据
|
|
指定查询返回的日志事件数。 您可以使用此选项将结果限制为较少的数量,以查看一小部分相关结果。您还可以使用值为介于 1000 到 10000 之间数字的 如果未指定限制,则查询默认为最多显示 1000 行。 |
以下示例根据
|
|
从日志字段提取数据,并创建一个或多个您可以在查询中进一步处理的临时字段。
对于 glob 表达式,请将常量字符串(用单引号或双引号括起来的字符)与 在正则表达式两旁加上正斜杠 (/)。在该表达式中,要提取的匹配字符串的每段均包含在一个命名的捕获组中。 |
使用此单个日志行作为示例:
以下两个
使用此单个日志行作为示例:
以下示例使用正则表达式从日志字段
|
使用查询命令的指南
您必须将查询中命名的日志字段(包括除 @
符号、句点 (.
) 和非字母数字字符以外的字符)括在反引号键 (`
) 中。例如,必须将日志字段 foo-bar
括在反引号键 (`foo-bar`
) 中,因为它包含连字符 (-
),它是非字母数字字符。
可以使用 display
命令显示要在查询结果中看到的一个或多个字段。display
命令仅会显示您指定的文件。如果您的查询包含多个 display
命令,则查询结果仅会显示您在最终 display
命令中指定的一个或多个字段。
您可以将 fields
命令与关键字 as 配合使用,以创建使用您的录入事件中的字段和函数的临时字段。例如,fields ispresent as isRes
将创建一个名为 isRes
的临时字段,并且该临时字段可在查询的其余部分中使用。
isRes
的值等于 0 或 1,具体取决于 resolverArn
是否是发现的字段。如果您的查询包含多个 fields
命令,且不包括 display
命令,则会显示在 fields
命令中指定的所有字段。
筛选命令中的匹配项和正则表达式
筛选条件支持使用正则表达式。您可以使用以下比较运算符(=
、!=
、<
、<=
、>
、>=
)和布尔运算符(and
、or
和 not
)。
我们假定您熟悉正则表达式。CloudWatch Logs Insights 支持 Hyperscan,这是一个多正则表达式匹配库。有关 Hyperscan 的更多信息,请参阅 Hyperscan 网站
您可以使用关键字 in
来测试集合成员资格并检查数组中的元素。要检查数组中的元素,请将该数组放在 in
之后。您可以将布尔运算符 not
与 in
配合使用。您可以创建查询,它们使用 in
返回字段是字符串匹配项的录入事件。这些字段必须是完整字符串。例如,下面的代码片段显示了一个查询,它使用 in
返回字段 logGroup
是完整字符串 example_group
的录入事件。
fields @timestamp, @message | filter logGroup in ["example_group"]
您可以使用关键字短语 like
和 not like
以匹配子字符串。您可以使用正则表达式运算符 =~
以匹配子字符串。要使用 like
和 not like
匹配子字符串,请将您要匹配的子字符串括在单引号或双引号中。您可以将正则表达式模式与 like
和 not like
配合使用。要使用正则表达式运算符匹配子字符串,请将您要匹配的子字符串括在正斜杠中。下面的示例包含多个代码片段,它们展示您如何能够使用 filter
命令匹配子字符串。
示例:匹配子字符串
以下示例将返回 f1
包含单词 Exception 的录入事件。所有三个示例都区分大小写。
第一个示例使用 like
匹配子字符串。
fields f1, f2, f3 | filter f1 like "Exception"
第二个示例使用 like
和正则表达式模式匹配子字符串。
fields f1, f2, f3 | filter f1 like /Exception/
最后一个示例使用正则表达式匹配子字符串。
fields f1, f2, f3 | filter f1 =~ /Exception/
示例:使用通配符匹配子字符串
您可以使用星号 (*
) 作为正则表达式中的通配符来匹配子字符串。下面的示例将返回 f1
包含以字母 E 开头的单词的多个录入事件。此示例区分大小写。
fields f1, f2, f3 | filter f3 like /E*/
您可以在星号之前放置一个句点 (.*),以创建一个返回尽可能多的匹配项的贪婪量词。
示例:从匹配项中排除子字符串
下面的示例将显示一个查询,它将返回 f1
不包含单词 Exception 的多个录入事件。此示例区分大小写。
fields f1, f2, f3 | filter f1 not like "Exception"
示例:使用不区分大小写的模式匹配子字符串
您可以使用 like
和正则表达式匹配不区分大小写的子字符串。在您要匹配的子字符串前放置以下参数 (?i)。下面的示例将显示一个查询,它将返回 f1
包含单词 Exception 或 exception 的多个录入事件。
fields f1, f2, f3 | filter f1 like /(?i)Exception/
在查询中使用别名
您可以使用 as
在查询中创建一个或多个别名。fields
、stats
和 sort
命令中支持别名。
您可以为日志字段以及运算和函数的结果创建别名。
示例
以下示例说明在查询命令中使用别名。
fields abs(myField) as AbsoluteValuemyField, myField2
将 myField
的绝对值返回为 AbsoluteValuemyField
,还返回字段 myField2
。
stats avg(f1) as myAvgF1 | sort myAvgF1 desc
将 f1
值的平均值计算为 myAvgF1
并按该值的降序将它们返回。
在查询中使用注释
您可以在查询中使用 #
字符注释掉行。将忽略以 #
字符开头的行。这可用于记录您的查询或暂时对某个调用忽略复杂查询的一部分,而不删除该行。
在以下示例中,将忽略查询的第二行。
fields @timestamp, @message # | filter @message like /delay/ | limit 20
支持的运算和函数
此查询语言支持多种类型的运算和函数,如下面的表中所示。
比较运算
您可以在 filter
命令中使用比较运算并将其用作其他函数的参数。比较运算接受所有数据类型作为参数,并返回布尔值结果。
= != < <= > >=
布尔运算符
您可以使用布尔运算符 and
、or
和 not
。您只能在返回布尔值的函数中使用这些布尔运算符。
算术运算
您可以在 filter
和 fields
命令中使用算术运算并将其用作其他函数的参数。算术运算接受数值数据类型作为参数并返回数值结果。
运算 | 说明 |
---|---|
|
加 |
|
减 |
|
乘 |
|
除 |
|
幂。 |
|
余额或模数。 |
数值运算
您可以在 filter
和 fields
命令中使用数值运算并将其用作其他函数的参数。数值运算接受数值数据类型作为参数并返回数值结果。
运算 | 结果类型 | 说明 |
---|---|---|
|
number |
绝对值。 |
|
number |
舍入到上限(大于 |
|
number |
舍入到下限(小于 |
|
number |
返回最大值。 |
|
number |
返回最小值。 |
|
number |
自然对数。 |
|
number |
平方根。 |
常规函数
您可以在 filter
和 fields
命令中使用常规函数并将其用作其他函数的参数。
函数 | 结果类型 | 说明 |
---|---|---|
|
布尔值 |
如果字段存在,则返回 |
|
LogField |
返回列表中的第一个非 null 值。 |
字符串函数
您可以在 filter
和 fields
命令中使用字符串函数并将其用作其他函数的参数。
函数 | 结果类型 | 说明 |
---|---|---|
|
数字 |
如果字段缺失或为空字符串,则返回 |
|
数字 |
如果字段缺失或为空字符串,或只包含空格,则返回 |
|
字符串 |
连结字符串。 |
|
字符串 |
如果函数没有第二个参数,它将删除字符串左侧的空格。如果函数有第二个字符串参数,它将不会删除空格。相反,它会从 |
|
字符串 |
如果函数没有第二个参数,它将删除字符串右侧的空格。如果函数有第二个字符串参数,它将不会删除空格。相反,它会从 |
|
字符串 |
如果函数没有第二个参数,它将删除字符串两端的空格。如果函数有第二个字符串参数,它将不会删除空格。相反,它会从 |
|
number |
返回 Unicode 代码点中字符串的长度。 |
|
字符串 |
将字符串转换为大写。 |
|
字符串 |
将字符串转换为小写。 |
|
字符串 |
返回从由数值参数指定的索引到字符串末尾的子字符串。如果该函数具有二个参数,它包含要检索的子字符串的长度。例如, |
|
字符串 |
将 例如,函数 |
|
number |
如果 |
日期时间函数
您可以在 filter
和 fields
命令中使用日期时间函数并将其用作其他函数的参数。您可以使用这些函数为使用聚合函数的查询创建时间存储桶。您也可以使用包括一个数字的时间段,m
表示分钟,h
表示小时。例如,10m
为 10 分钟,1h
为 1 小时。下表包含可在查询命令中使用的不同日期时间函数的列表。该表列出了每个函数的结果类型,并包含对每个函数的描述。
在创建查询命令时,您可以使用时间间隔选择器选择要查询的时间段。例如,您可以设置 5 到 30 分钟的时间间隔;1、3 和 12 小时间隔;或者自定义时间范围。您还可以设置特定日期之间的时间段。有关如何运行查询命令的信息,请参阅《Amazon CloudWatch Logs 用户指南》中的教程:运行和修改示例查询。
函数 | 结果类型 | 说明 |
---|---|---|
|
时间戳 |
将 |
|
时间戳 |
将时间戳截断到指定的时间段。例如, |
|
时间戳 |
将时间戳向上舍入到指定的时间段,然后截断。例如, |
|
时间戳 |
将输入字段解释为自 Unix 纪元以来的毫秒数并将其转换为时间戳。 |
|
number |
将在命名字段中找到的时间戳转换为表示自 Unix 纪元以来毫秒数的数字。例如, |
目前,CloudWatch Logs Insights 不支持使用人类可读的时间戳筛选日志。
IP 地址函数
您可以在 filter
和 fields
命令中使用 IP 地址字符串函数并将其用作其他函数的参数。
函数 | 结果类型 | 说明 |
---|---|---|
|
布尔值 |
如果字段是有效的 IPv4 或 IPv6 地址,则返回 |
|
布尔值 |
如果字段是有效的 IPv4 地址,则返回 |
|
布尔值 |
如果字段是有效的 IPv6 地址,则返回 |
|
布尔值 |
如果字段是指定的 v4 或 v6 子网中有效的 IPv4 或 IPv6 地址,则返回 |
|
布尔值 |
如果字段是指定的 v4 子网中有效的 IPv4 地址,则返回 |
|
布尔值 |
如果字段是指定的 v6 子网中有效的 IPv6 地址,则返回 |
统计聚合函数
您可以在 stats
命令中使用聚合函数并将其用作其他函数的参数。
函数 | 结果类型 | 说明 |
---|---|---|
|
number |
指定的字段中值的平均值。 |
|
number |
计算日志事件的数量。 |
|
number |
返回字段的唯一值的数量。如果字段具有非常高的基数(包含许多唯一值),则 |
|
LogFieldValue |
所查询的日志中此日志字段的值的最大值。 |
|
LogFieldValue |
所查询的日志中此日志字段的值的最小值。 |
|
LogFieldValue |
百分位数指示某个值在数据集中的相对位置。例如, |
|
number |
指定的字段中值的标准偏差。 |
|
number |
指定的字段中值的总和。 |
统计非聚合函数
您可以在 stats
命令中使用非聚合函数并将其用作其他函数的参数。
函数 | 结果类型 | 说明 |
---|---|---|
|
LogField |
从查询的日志中具有最早时间戳的日志事件返回 |
|
LogField |
从查询的日志中具有最晚时间戳的日志事件返回 |
|
LogField |
返回在查询的日志中排在第一位的 |
|
LogField |
返回在查询的日志中排在最后一位的 |