CloudWatch Logs Insights 查询语法
借助 CloudWatch Logs Insights,您可使用查询语言对日志组执行查询。查询语法支持不同的函数和运算,包括但不限于常规函数、算术和比较运算以及正则表达式。创建包含多个查询命令的查询。用管道字符 (|) 分离命令。创建包含备注的查询。用哈希字符 (#) 分隔注释。
注意
CloudWatch Logs Insights 会自动发现多种不同日志类型的字段,并生成以 @ 字符开头的字段。有关这些字段的更多信息,请参阅 Amazon CloudWatch 用户指南中的支持的日志和搜索到的字段。
CloudWatch Logs Insights 查询命令
本部分包含支持的 CloudWatch Logs Insights 查询命令列表。
注意
并非本部分中的所有示例查询都适用于您的日志事件。本部分中的示例查询旨在展示如何使用支持的 CloudWatch Logs Insights 查询命令来格式化查询。您可能需要格式化查询,使其与日志事件的格式匹配。有关更多示例查询,请参阅 示例查询。
-
display
使用
display
在查询结果中显示一个或多个特定字段。示例:显示一个字段
该代码片段显示了一个查询示例,其使用解析命令从
@message
提取数据以创建临时字段loggingType
和loggingMessage
。该查询将返回loggingType
的值为 ERROR(错误)的所有日志事件。display
在查询结果中仅显示loggingMessage
的值。fields @message | parse @message "[*] *" as loggingType, loggingMessage | filter loggingType = "ERROR" | display loggingMessage
提示
在查询中只使用
display
一次。如果您在查询中多次使用display
,则查询结果会显示在最后使用的display
命令中指定的字段。 -
fields
使用
fields
在查询结果中显示特定字段。示例:显示特定字段
该代码片段显示了一个查询示例,其将返回 20 个日志事件并按降序显示它们。查询结果将显示
@timestamp
和@message
的值。fields @timestamp, @message | sort @timestamp desc | limit 20
提示
当您不想使用
display
时,请使用此命令。fields
支持用于修改字段值和创建可在查询中使用的新字段的不同函数和操作。 -
filter
使用
filter
获取与一个或多个条件匹配的日志事件。示例:使用一个条件筛选日志事件
该代码片段显示了一个查询示例,其将返回
range
的值大于 3000 的所有日志事件。该查询将结果限制为 20 个日志事件,并按@timestamp
和降序对日志事件进行排序。fields @timestamp, @message | filter (range>3000) | sort @timestamp desc | limit 20
示例:使用多个条件筛选日志事件
您可以使用关键字
and
和or
组合多个条件。该代码片段显示了一个查询示例,其将返回
range
的值大于 3000 以及accountId
的值等于 798312420998 的日志事件。该查询将结果限制为 20 个日志事件,并按@timestamp
和降序对日志事件进行排序。fields @timestamp, @message | filter (range>3000 and accountId=9876543210) | sort @timestamp desc | limit 20
-
stats
使用
stats
计算带有日志字段值的聚合统计数据。 -
sort
使用
sort
按升序 (asc
) 或降序 (desc
) 顺序显示日志事件。 -
limit
使用
limit
指定您希望查询返回的日志事件数。 -
parse
使用
parse
从日志字段中提取数据,并创建可以在查询中处理的临时字段。您可以使用正则表达式解析嵌套的 JSON 字段。
示例:解析嵌套的 JSON 字段
该代码片段显示了如何解析在摄取过程中展平的 JSON 日志事件。
{'fieldsA': 'logs', 'fieldsB': [{'fA': 'a1'}, {'fA': 'a2'}]}
该代码片段显示了一个带有正则表达式的查询,其将提取
fieldsA
和fieldsB
的值以创建临时字段fld
和array
。parse @message "'fieldsA': '*', 'fieldsB': ['*']" as fld, array
-
unmask
使用
unmask
显示由于数据保护策略而屏蔽部分内容的日志事件的所有内容。要使用此命令,必须具备logs:Unmask
权限。有关日志组中数据保护的更多信息,请参阅 通过屏蔽帮助保护敏感的日志数据。
注意
JSON 日志事件在摄取过程中会被展平。目前,不支持使用 glob 表达式来解析嵌套的 JSON 字段。您只能解析所含日志事件字段数不超过 200 的 JSON 日志事件。解析嵌套的 JSON 字段时,必须格式化查询中的正则表达式,使其与 JSON 日志事件的格式匹配。
使用查询命令的指南
您必须将查询中命名的日志字段(包括除 @
符号、句点 (.
) 和非字母数字字符以外的字符)括在反引号键 (`
) 中。例如,日志字段 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
的值以字符串 ServiceLog
开头的匹配项。
fields f1, f2, f3 | filter f1 like /ServiceLog./
您可以在句点符号 (.*
) 之后放置星号,以创建一个返回尽可能多的匹配项的贪婪量词。例如,以下查询将返回 f1
的值不仅以字符串 ServiceLog
开头并且还包括字符串 ServiceLog
的匹配项。
fields f1, f2, f3 | filter f1 like /ServiceLog.*/
可能的匹配项可以采用以下格式:
-
ServiceLogSampleApiLogGroup
-
SampleApiLogGroupServiceLog
示例:从匹配项中排除子字符串
下面的示例将显示一个查询,它将返回 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
-
parse
-
sort
-
stats
以下示例演示了如何创建包含别名的查询。
示例
查询中在 fields
命令中包含别名。
fields @timestamp, @message, accountId as ID | sort @timestamp desc | limit 20
查询将返回字段 @timestamp
、@message
和 accountId
的值。结果按降序排序且限制在 20 个。accountId
的值在别名 ID
下列出。
示例
查询在 sort
和 stats
命令中包含别名。
stats count(*) by duration as time | sort time desc
查询计算字段 duration
出现在日志组中的次数,然后按降序对结果进行排序。duration
的值在别名 time
下列出。
在查询中使用注释
CloudWatch Logs Insights 支持查询中的备注。使用哈希字符 (#) 分隔备注。您可以使用备注忽略查询或文档查询中的行。
示例:查询
运行以下查询时,将忽略第二行。
fields @timestamp, @message, accountId # | filter accountId not like "7983124201998" | sort @timestamp desc | limit 20
支持的运算和函数
CloudWatch Logs Insights 支持以下操作和函数。
算术运算符
算术运算接受数值数据类型作为参数并返回数值结果。在 filter
和 fields
命令中使用算术运算并将其用作其他函数的参数。
运算 | 描述 |
---|---|
|
加 |
|
减 |
|
乘 |
|
除 |
|
幂( |
|
余额或模数( |
布尔运算符
使用布尔运算符 and
、or
和 not
。
注意
仅在返回 TRUE 或 FALSE 值的函数中使用布尔运算符。
比较运算符
比较运算接受所有数据类型作为参数,并返回布尔值结果。在 filter
命令中使用比较运算并将其用作其他函数的参数。
操作符 | 描述 |
---|---|
|
等于 |
|
不等于 |
|
小于 |
|
大于 |
|
小于或等于 |
|
大于或等于 |
数值运算
数值运算接受数值数据类型作为参数并返回数值结果。在 filter
和 fields
命令中使用数值运算并将其用作其他函数的参数。
运算 | 结果类型 | 描述 |
---|---|---|
|
number |
绝对值 |
|
number |
舍入到上限(大于 |
|
number |
舍入到下限(小于 |
|
number |
返回最大值 |
|
number |
返回最小值 |
|
number |
自然对数 |
|
number |
平方根 |
日期时间函数
在 fields
和 filter
命令中使用日期时间函数并将其用作其他函数的参数。使用这些函数为使用聚合函数的查询创建时间存储桶。使用包括一个数字的时间段,m
表示分钟,h
表示小时。例如,10m
为 10 分钟,1h
为 1 小时。下表包含可在查询命令中使用的不同日期时间函数列表。该表列出了每个函数的结果类型,并包含对每个函数的描述。
提示
在创建查询命令时,您可以使用时间间隔选择器选择要查询的时间段。例如,您可以设置 5 到 30 分钟的时间间隔;1、3 和 12 小时间隔;或者自定义时间范围。您还可以设置特定日期之间的时间段。
函数 | 结果类型 | 描述 |
---|---|---|
|
时间戳 |
将 |
|
时间戳 |
将时间戳截断到指定的时间段。例如, |
|
时间戳 |
将时间戳向上舍入到指定的时间段,然后截断。例如, |
|
时间戳 |
将输入字段解释为自 Unix 纪元以来的毫秒数并将其转换为时间戳。 |
|
number |
将在命名字段中找到的时间戳转换为表示自 Unix 纪元以来毫秒数的数字。例如, |
注意
目前,CloudWatch Logs Insights 不支持使用人类可读的时间戳筛选日志。
常见函数
在 fields
和 filter
命令中使用常规函数并将其用作其他函数的参数。
函数 | 结果类型 | 描述 |
---|---|---|
|
布尔值 |
如果字段存在,则返回 |
|
LogField |
返回列表中的第一个非 null 值 |
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 |
返回在查询的日志中排在最后一位的 |
字符串函数
在 fields
和 filter
命令中使用字符串函数并将其用作其他函数的参数。
函数 | 结果类型 | 描述 |
---|---|---|
|
数字 |
如果字段缺失或为空字符串,则返回 |
|
数字 |
如果字段缺失或为空字符串,或只包含空格,则返回 |
|
字符串 |
连结字符串。 |
|
字符串 |
如果函数没有第二个参数,它将删除字符串左侧的空格。如果函数有第二个字符串参数,它将不会删除空格。相反,它会从 |
|
字符串 |
如果函数没有第二个参数,它将删除字符串右侧的空格。如果函数有第二个字符串参数,它将不会删除空格。相反,它会从 |
|
字符串 |
如果函数没有第二个参数,它将删除字符串两端的空格。如果函数有第二个字符串参数,它将不会删除空格。相反,它会从 |
|
number |
返回 Unicode 代码点中字符串的长度。 |
|
字符串 |
将字符串转换为大写。 |
|
字符串 |
将字符串转换为小写。 |
|
字符串 |
返回从由数值参数指定的索引到字符串末尾的子字符串。如果该函数具有二个参数,它包含要检索的子字符串的长度。例如, |
|
字符串 |
将 例如,函数 |
|
number |
如果 |