CloudWatch Logs Insights 查询语法 - Amazon CloudWatch Logs
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

如果我们为英文版本指南提供翻译,那么如果存在任何冲突,将以英文版本指南为准。在提供翻译时使用机器翻译。

CloudWatch Logs Insights 查询语法

CloudWatch Logs Insights 支持您用来对日志组执行查询的查询语言。每个查询可以包含一个或多个由 Unix 式竖线字符 (|) 分隔的查询命令。

支持六个查询命令以及许多支持函数和操作,包括正则表达式、算术运算、比较操作、数字函数、日期时间函数、字符串函数和通用函数。

此外还支持注释。将忽略查询中以 # 字符开头的行。

@ 符号由 CloudWatch Logs 见解。有关以下字段的更多信息 CloudWatch Logs 自动发现并生成,请参阅 支持的日志和发现的字段.

CloudWatch Logs Insights 查询命令

下表列出了六个支持的查询命令以及基本示例。有关更强大的示例查询,请参阅 查询示例

Command Description 示例:

display

指定要在查询结果中显示的字段。如果您在查询中多次指定此命令,则仅使用您在最后一次的命令中指定的字段。

以下示例使用字段 @message 并创建临时字段 loggingTypeloggingMessage 用于查询。它仅将事件过滤给那些 ERROR 作为 loggingType,但是仅显示 loggingMessage 结果中的字段。

fields @message | parse @message "[*] *" as loggingType, loggingMessage | filter loggingType = "ERROR" | display loggingMessage

fields

从日志事件中检索指定字段以显示。

您可以使用字段命令中的函数和操作来修改要显示的字段值,并创建新字段以用于查询的其余部分。

以下示例显示了 foo-bar, action,且两者之差的绝对值 f3f4 日志组中的所有日志事件。

fields `foo-bar`, action, abs(f3-f4)

以下示例创建并显示临时字段 opStatus。价值观 opStatus 每个日志条目是 OperationStatusCode 字段,两个值之间带有连字符。

fields concat(Operation, '-', StatusCode) as opStatus

filter

根据一个或多个条件筛选查询的结果。您可以在 filter 命令。有关更多信息,请参阅 过滤器命令中的匹配和常规表达。)

以下示例检索字段 f1, f2、和 f3 所有对数事件(数值超过2000) duration 字段。

fields f1, f2, f3 | filter (duration>2000)

以下示例也是一个有效的查询,但结果不显示单独的字段。相反,结果会显示 @timestamp 和所有日志数据 @message 用于持续时间超过2000的所有日志事件的字段。

filter (duration>2000)

以下示例检索字段 f1f2 所有日志事件,其中 f1 是10或 f3 超过25。

fields f1, f2 | filter (f1=10 or f3>25)

下一个示例返回字段所在的日志事件 statusCode 有一个介于200和299之间的值。

fields f1 | filter statusCode like /2\d\d/

下一个示例返回日志事件,其中包括 statusCode 300、400或500。

fields @timestamp, @message | filter statusCode in [300,400,500]

此最后一个示例返回没有 Type 字段的值是“Fo”、“bar”或“1”。

fields @timestamp, @message | filter Type not in ["foo","bar",1]

stats

根据日志字段的值计算聚合统计数据。当您使用 stats 时,也可以使用 by 指定一个或多个条件,以便在计算统计数据时用于对数据进行分组。

支持若干统计运算符,包括 sum()avg()count()min()max()

以下示例计算 f1 每个唯一值 f2.

stats avg (f1) by f2

sort

对检索的日志事件排序。同时支持升序 (asc) 和降序 (desc)。

以下示例根据 f1,并显示字段 f1, f2、和 f3.

fields f1, f2, f3 | sort f1 desc

limit

指定查询返回的日志事件数。

您可以使用此选项将结果限制为较少的数量,以查看一小部分相关结果。您还可以使用值为介于 1000 到 10000 之间数字的 limit,将控制台中显示的查询结果行数增加到超过默认值 1000 行的数量。

如果未指定限制,则查询默认为最多显示 1000 行。

以下示例根据 @timestamp,并显示字段 f1f2 按排序顺序排序的前25个事件。在这种情况下,排序顺序是按最近的时间戳,因此会返回最新的 25 个事件。

sort @timestamp desc | limit 25 | display f1, f2

parse

从日志字段提取数据并创建一个或多个临时字段,您可以在查询中进一步处理这些字段。parse 接受球形表达和规则表达。

对于 glob 表达式,为 parse 命令提供一个常量字符串(用单引号或双引号括起来的字符),其中每个可变文本段都用星号 (*) 替换。它们被提取到临时字段中,并按照位置顺序在 as 关键字之后给定别名。

在正则表达式两旁加上正斜杠 (/)。在表达式中,要提取的匹配字符串的每个部分均包含在一个命名的捕获组中。(?<name>.*) 是一个命名的捕获组示例,其中 name 为名称,.* 为模式。

使用此单个日志行作为示例:

25 May 2019 10:24:39,474 [ERROR] {foo=2, bar=data} The error was: DataIntegrityException

以下两个 parse 表达分别进行以下操作:临时字段 level, config、和 exception 创建。level 价值为 ERROR, config 价值为 {foo=2, bar=data}、和 exception 价值为 DataIntegrityException。第一个示例使用球形表达,第二个示例使用规则表达。

parse @message "[*] * The error was: *" as level, config, exception
parse @message /\[(?<level>\S+)\]\s+(?<config>\{.*\})\s+The error was: (?<exception>\S+)/

以下示例使用正则表达式从日志字段 @message 提取临时字段 @user2@method2@latency2,并针对 @method2@user2 的每个唯一组合返回平均延迟。

parse @message /user=(?<user2>.*?), method:(?<method2>.*?), latency := (?<latency2>.*?)/ | stats avg(@latency2) by @method2, @user2

关于上一表中查询命令的注释

以下规则、指南和提示适用于上表中的查询命令。

  • 在查询中命名的具有除 @ 符号、句点 (.) 和字母数字字符之外字符的任何日志字段都必须用反引号 (`) 字符括起来。例如,foo-bar 字段名称必须用反引号字符括起来,因为它包含非字母数字字符。

  • 两者 fieldsdisplay 用于指定要在查询结果中显示的字段。两者之间的差异如下:

    • 您使用 display 命令仅指定要在结果中显示的字段。您可以使用 fields 命令 作为 关键字,使用函数和日志事件中的字段创建新的临时字段。例如, fields ispresent(resolverArn) as isRes 创建一个名为 isRes 可在查询的剩余部分使用。价值观 isRes 为0或1,具体取决于 resolverArn 是日志事件中已发现的字段。

    • 如果您有多个 fields 命令,但不包括 display 命令,所有 fields commands are displayed.

    • 如果您有多个 display 命令中,只有最终 display command are displayed.

过滤器命令中的匹配和常规表达

您可以使用比较运算(=、!=、<、<=、>、>=)、布尔运算(and, or、和 not)和常规表达 filter 命令。

您可以使用 in 测试集合成员资格。放置一个包含要检查的元素的阵列,之后立即检查 in。您可以使用 notin。使用进行串匹配 in 必须是与匹配的完整串。

要按子串进行筛选,您可以使用 like=~ (等号后接波浪号) filter 命令。使用 like=~,将子串与双引号或单引号进行匹配。要执行规则表达匹配,请封装要与正斜线匹配的表达。查询将仅返回与您设置的条件匹配的日志事件。

示例:

以下三个示例返回所有事件, f1 包含单词 Exception。前两个示例使用常规表达。第三个示例使用子字符串匹配。所有三个示例都区分大小写。

fields f1, f2, f3 | filter f1 like /Exception/
fields f1, f2, f3 | filter f1 =~ /Exception/
fields f1, f2, f3 | filter f1 like "Exception"

以下示例将搜索“异常”更改为不区分大小写。

fields f1, f2, f3 | filter f1 like /(?i)Exception/

以下示例使用正则表达式。它返回所有事件, f1 就是 Exception。质疑不区分大小写。

fields f1, f2, f3 | filter f1 =~ /^(?i)Exception$/

在查询中使用别名

您可以使用 as 在查询中创建一个或多个别名。fieldsstatssort 命令中支持别名。

您可以为日志字段以及操作和函数的结果创建别名。

示例:

以下示例说明在查询命令中使用别名。

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。您只能在返回布尔值的函数中使用这些布尔运算。

算术运算

您可以在 filterfields 命令中使用算术运算并将其用作其他函数的参数。算术运算接受数值数据类型作为参数并返回数值结果。

运算 Description

a + b

a - b

减 ()

a * b

乘 ()

a / b

a ^ b

指数化。2 ^ 3 退货 8

a % b

剩余或模量。10 % 3 退货 1

数值运算

您可以在 filterfields 命令中使用数值运算并将其用作其他函数的参数。数值运算接受数值数据类型作为参数并返回数值结果。

运算 结果类型 Description

abs(a: number)

number

绝对值。

ceil(a: number)

number

舍入到上限(大于 a 的值的最小整数)。

floor(a: number)

number

舍入到下限(小于 a 的值的最大整数)。

greatest(a: number, ...numbers: number[])

number

返回最大值。

least(a: number, ...numbers: number[])

number

返回最小值。

log(a: number)

number

自然对数。

sqrt(a: number)

number

平方根。

常规函数

您可以在 filterfields 命令中使用常规函数并将其用作其他函数的参数。

Function 结果类型 Description

ispresent(fieldName: LogField)

boolean

如果字段存在,则返回 true

coalesce(fieldName: LogField, ...fieldNames: LogField[])

Log字段

返回列表中的第一个非 null 值。

字符串函数

您可以在 filterfields 命令中使用字符串函数并将其用作其他函数的参数。

Function 结果类型 Description

isempty(fieldName: string)

boolean

如果字段缺失或为空字符串,则返回 true

isblank(fieldName: string)

boolean

如果字段缺失或为空字符串,或只包含空格,则返回 true

concat(str: string, ...strings: string[])

string

连结字符串。

ltrim(str: string)

ltrim(str: string, subStr: string)

string

删除字符串左侧的空格。如果函数具有第二个串参数,它将删除 subStrstr。例如, ltrim("xyZfooxyZ","xyZ") 退货 "fooxyZ".

rtrim(str: string)

rtrim(str: string, subStr: string)

string

删除字符串右侧的空格。如果函数具有第二个串参数,它将删除 subStrstr。例如, rtrim("xyZfooxyZ","xyZ") 退货 "xyZfoo".

trim(str: string)

trim(str: string, subStr: string)

string

删除字符串两端的空格。如果函数具有第二个串参数,它将删除 subStrstr。例如, trim("xyZfooxyZ","xyZ") 退货 "foo".

strlen(str: string)

number

返回 Unicode 代码点中字符串的长度。

toupper(str: string)

string

将字符串转换为大写。

tolower(str: string)

string

将字符串转换为小写。

substr(str: string, startIndex: number)

substr(str: string, startIndex: number, length: number)

string

返回从由数值参数指定的索引到字符串末尾的子字符串。如果该函数具有二个参数,它包含要检索的子字符串的长度。例如,substr("xyZfooxyZ",3, 3) 将返回 "foo"

replace(str: string, searchValue: string, replaceValue: string)

string

替换所有实例 searchValuestrreplaceValue。例如, replace("foo","o","0") 退货 "f00".

strcontains(str: string, searchValue: string)

number

如果 str 包含 searchValue,则返回 1,否则返回 0。

日期时间函数

您可以在 filterfields 命令中使用日期时间函数并将其用作其他函数的参数。您可以使用这些函数为使用聚合函数的查询创建时间存储桶。

作为日期时间函数的一部分,您可以使用包括一个数字的时间段,m 表示分钟,h 表示小时。例如,10m 为 10 分钟,1h 为 1 小时。

Function 结果类型 Description

bin(period: Period)

Timestamp()

@timestamp 的值舍入到指定的时间段,然后截断。

datefloor(timestamp: Timestamp, period: Period)

Timestamp()

将时间戳截断到指定的时间段。例如,datefloor(@timestamp, 1h)@timestamp 的所有值截断至小时底部。

dateceil(timestamp: Timestamp, period: Period)

Timestamp()

将时间戳向上舍入到指定的时间段,然后截断。例如,dateceil(@timestamp, 1h)@timestamp 的所有值截断至小时顶部。

fromMillis(fieldName: number)

Timestamp()

将输入字段解释为自 Unix 纪元以来的毫秒数并将其转换为时间戳。

toMillis(fieldName: Timestamp)

number

将在命名字段中找到的时间戳转换为表示自 Unix 纪元以来毫秒数的数字。

IP 地址函数

您可以在 filterfields 命令中使用 IP 地址字符串函数并将其用作其他函数的参数。

Function 结果类型 Description

isValidIp(fieldName: string)

boolean

如果字段是有效的 IPv4 或 IPv6 地址,则返回 true

isValidIpV4(fieldName: string)

boolean

如果字段是有效的 IPv4 地址,则返回 true

isValidIpV6(fieldName: string)

boolean

如果字段是有效的 IPv6 地址,则返回 true

isIpInSubnet(fieldName: string, subnet: string)

boolean

如果字段是指定的 v4 或 v6 子网中有效的 IPv4 或 IPv6 地址,则返回 true。指定子网时,请使用 CIDR 表示法,例如 192.0.2.0/242001:db8::/32

isIpv4InSubnet(fieldName: string, subnet: string)

boolean

如果字段是指定的 v4 子网中有效的 IPv4 地址,则返回 true。指定子网时,请使用 CIDR 表示法,例如 192.0.2.0/24

isIpv6InSubnet(fieldName: string, subnet: string)

boolean

如果字段是指定的 v6 子网中有效的 IPv6 地址,则返回 true。指定子网时,请使用 CIDR 表示法,例如 2001:db8::/32

统计聚合函数

您可以在 stats 命令中使用聚合函数并将其用作其他函数的参数。

Function 结果类型 Description

avg(fieldName: NumericLogField)

number

指定的字段中值的平均值。

count()

count(fieldName: LogField)

number

计数日志事件。count() (或 count(*))计算查询返回的所有事件,而 count(fieldName) 计算包含指定字段名称的所有记录。

count_distinct(fieldName: LogField)

number

返回字段的唯一值的数量。如果字段具有非常高的基数(包含许多唯一值),则 count_distinct 返回的值只是一个近似值。

max(fieldName: LogField)

Log字段值

所查询的日志中此日志字段的值的最大值。

min(fieldName: LogField)

Log字段值

所查询的日志中此日志字段的值的最小值。

pct(fieldName: LogFieldValue, percent: number)

Log字段值

百分位数指示某个值在数据集中的相对位置。例如,pct(@duration, 95) 返回 @duration 值,95% 的 @duration 值低于此值,5% 的值高于此值。

stddev(fieldName: NumericLogField)

number

指定的字段中值的标准偏差。

sum(fieldName: NumericLogField)

number

指定的字段中值的总和。

统计非聚合函数

您可以在 stats 命令中使用非聚合函数并将其用作其他函数的参数。

Function 结果类型 Description

earliest(fieldName: LogField)

Log字段

从查询的日志中具有最早时间戳的日志事件返回 fieldName 的值。

latest(fieldName: LogField)

Log字段

从查询的日志中具有最晚时间戳的日志事件返回 fieldName 的值。

sortsFirst(fieldName: LogField)

Log字段

返回在查询的日志中排在第一位的 fieldName 的值。

sortsLast(fieldName: LogField)

Log字段

返回在查询的日志中排在最后一位的 fieldName 的值。