支持的查询命令筛选命令中的匹配项和正则表达式在查询中使用别名在查询中使用注释支持的运算和函数

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 命令中使用算术运算并将其用作其他函数的参数。

运算	描述
`a + b`	加
`a - b`	减
`a * b`	乘
`a / b`	除
`a ^ b`	幂（`2 ^ 3` 返回 `8`）
`a % b`	余额或模数（`10 % 3` 返回 `1`）

布尔运算符

使用布尔运算符 and、or 和 not。

注意

仅在返回 TRUE 或 FALSE 值的函数中使用布尔运算符。

比较运算符

比较运算接受所有数据类型作为参数，并返回布尔值结果。在 filter 命令中使用比较运算并将其用作其他函数的参数。

操作符	描述
`=`	等于
`!=`	不等于
`<`	小于
`>`	大于
`<=`	小于或等于
`>=`	大于或等于

数值运算

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

运算	结果类型	描述
`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	平方根

日期时间函数

在 fields 和 filter 命令中使用日期时间函数并将其用作其他函数的参数。使用这些函数为使用聚合函数的查询创建时间存储桶。使用包括一个数字的时间段，m 表示分钟，h 表示小时。例如，10m 为 10 分钟，1h 为 1 小时。下表包含可在查询命令中使用的不同日期时间函数列表。该表列出了每个函数的结果类型，并包含对每个函数的描述。

提示

在创建查询命令时，您可以使用时间间隔选择器选择要查询的时间段。例如，您可以设置 5 到 30 分钟的时间间隔；1、3 和 12 小时间隔；或者自定义时间范围。您还可以设置特定日期之间的时间段。

函数	结果类型	描述
`bin(period: Period)`	时间戳	将 `@timestamp` 的值四舍五入到指定的时间段，然后截断。例如，`bin(5m)` 将 `@timestamp` 的值舍入为 5 分钟，然后截断。
`datefloor(timestamp: Timestamp, period: Period)`	时间戳	将时间戳截断到指定的时间段。例如，`datefloor(@timestamp, 1h)` 将 `@timestamp` 的所有值截断至小时底部。
`dateceil(timestamp: Timestamp, period: Period)`	时间戳	将时间戳向上舍入到指定的时间段，然后截断。例如，`dateceil(@timestamp, 1h)` 将 `@timestamp` 的所有值截断至小时顶部。
`fromMillis(fieldName: number)`	时间戳	将输入字段解释为自 Unix 纪元以来的毫秒数并将其转换为时间戳。
`toMillis(fieldName: Timestamp)`	number	将在命名字段中找到的时间戳转换为表示自 Unix 纪元以来毫秒数的数字。例如，`toMillis(@timestamp)` 将时间戳 `2022-01-14T13:18:031.000-08:00` 转换为 `1642195111000`。

注意

目前，CloudWatch Logs Insights 不支持使用人类可读的时间戳筛选日志。

常见函数

在 fields 和 filter 命令中使用常规函数并将其用作其他函数的参数。

函数	结果类型	描述
`ispresent(fieldName: LogField)`	布尔值	如果字段存在，则返回 `true`
`coalesce(fieldName: LogField, ...fieldNames: LogField[])`	LogField	返回列表中的第一个非 null 值

IP 地址字符串函数

在 filter 和 fields 命令中使用 IP 地址字符串函数并将其用作其他函数的参数。

函数	结果类型	描述
`isValidIp(fieldName: string)`	布尔值	如果字段是有效的 IPv4 或 IPv6 地址，则返回 `true`。
`isValidIpV4(fieldName: string)`	布尔值	如果字段是有效的 IPv4 地址，则返回 `true`。
`isValidIpV6(fieldName: string)`	布尔值	如果字段是有效的 IPv6 地址，则返回 `true`。
`isIpInSubnet(fieldName: string, subnet: string)`	布尔值	如果字段是指定的 v4 或 v6 子网中有效的 IPv4 或 IPv6 地址，则返回 `true`。指定子网时，请使用 CIDR 表示法（例如 `192.0.2.0/24` 或 `2001:db8::/32`），其中 `192.0.2.0` 或 `2001:db8::` 是 CIDR 块的起点。
`isIpv4InSubnet(fieldName: string, subnet: string)`	布尔值	如果字段是指定的 v4 子网中有效的 IPv4 地址，则返回 `true`。指定子网时，请使用 CIDR 表示法（例如 `192.0.2.0/24`），其中 `192.0.2.0` 是 CIDR 块的起点。
`isIpv6InSubnet(fieldName: string, subnet: string)`	布尔值	如果字段是指定的 v6 子网中有效的 IPv6 地址，则返回 `true`。指定子网时，请使用 CIDR 表示法（例如 `2001:db8::/32`），其中 `2001:db8::` 是 CIDR 块的起点。

统计聚合函数

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

函数	结果类型	描述
`avg(fieldName: NumericLogField)`	number	指定的字段中值的平均值。
`count()` `count(fieldName: LogField)`	number	计算日志事件的数量。`count()`（或 `count(*)`）对查询返回的所有事件进行计数，而 `count(fieldName)` 对包含所指定字段名称的所有记录进行计数。
`count_distinct(fieldName: LogField)`	number	返回字段的唯一值的数量。如果字段具有非常高的基数（包含许多唯一值），则 `count_distinct` 返回的值只是一个近似值。
`max(fieldName: LogField)`	LogFieldValue	所查询的日志中此日志字段的值的最大值。
`min(fieldName: LogField)`	LogFieldValue	所查询的日志中此日志字段的值的最小值。
`pct(fieldName: LogFieldValue, percent: number)`	LogFieldValue	百分位数指示某个值在数据集中的相对位置。例如，`pct(@duration, 95)` 返回 `@duration` 值，95% 的 `@duration` 值低于此值，5% 的值高于此值。
`stddev(fieldName: NumericLogField)`	number	指定的字段中值的标准偏差。
`sum(fieldName: NumericLogField)`	number	指定的字段中值的总和。

统计非聚合函数

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

函数	结果类型	描述
`earliest(fieldName: LogField)`	LogField	从查询的日志中具有最早时间戳的日志事件返回 `fieldName` 的值。
`latest(fieldName: LogField)`	LogField	从查询的日志中具有最晚时间戳的日志事件返回 `fieldName` 的值。
`sortsFirst(fieldName: LogField)`	LogField	返回在查询的日志中排在第一位的 `fieldName` 的值。
`sortsLast(fieldName: LogField)`	LogField	返回在查询的日志中排在最后一位的 `fieldName` 的值。

字符串函数

在 fields 和 filter 命令中使用字符串函数并将其用作其他函数的参数。

函数	结果类型	描述
`isempty(fieldName: string)`	数字	如果字段缺失或为空字符串，则返回 `1`。
`isblank(fieldName: string)`	数字	如果字段缺失或为空字符串，或只包含空格，则返回 `1`。
`concat(str: string, ...strings: string[])`	字符串	连结字符串。
`ltrim(str: string)` `ltrim(str: string, trimChars: string)`	字符串	如果函数没有第二个参数，它将删除字符串左侧的空格。如果函数有第二个字符串参数，它将不会删除空格。相反，它会从 `str` 左侧删除 `trimChars` 中的字符。例如，`ltrim("xyZxyfooxyZ","xyZ")` 将返回 `"fooxyZ"`。
`rtrim(str: string)` `rtrim(str: string, trimChars: string)`	字符串	如果函数没有第二个参数，它将删除字符串右侧的空格。如果函数有第二个字符串参数，它将不会删除空格。相反，它会从 `str` 右侧删除 `trimChars` 字符。例如，`rtrim("xyZfooxyxyZ","xyZ")` 将返回 `"xyZfoo"`。
`trim(str: string)` `trim(str: string, trimChars: string)`	字符串	如果函数没有第二个参数，它将删除字符串两端的空格。如果函数有第二个字符串参数，它将不会删除空格。相反，它会从 `str` 两端删除 `trimChars` 字符。例如，`trim("xyZxyfooxyxyZ","xyZ")` 将返回 `"foo"`。
`strlen(str: string)`	number	返回 Unicode 代码点中字符串的长度。
`toupper(str: string)`	字符串	将字符串转换为大写。
`tolower(str: string)`	字符串	将字符串转换为小写。
`substr(str: string, startIndex: number)` `substr(str: string, startIndex: number, length: number)`	字符串	返回从由数值参数指定的索引到字符串末尾的子字符串。如果该函数具有二个参数，它包含要检索的子字符串的长度。例如，`substr("xyZfooxyZ",3, 3)` 将返回 `"foo"`。
`replace(fieldName: string, searchValue: string, replaceValue: string)`	字符串	将 `fieldName: string` 中出现的所有 `searchValue` 替换为 `replaceValue`。例如，函数 `replace(logGroup,"smoke_test","Smoke")` 搜索录入事件，其中字段 `logGroup` 包含字符串值 `smoke_test`，并使用字符串 `Smoke` 替换该值。
`strcontains(str: string, searchValue: string)`	number	如果 `str` 包含 `searchValue`，则返回 1，否则返回 0。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

教程：运行生成时间序列可视化的查询

在图形中可视化日志数据