AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

CloudWatch Logs Insights 查询语法

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

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

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

CloudWatch Logs Insights 查询命令

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

命令	说明	示例
`fields`	从日志事件检索指定的字段。您可以在 fields 命令中使用函数和操作。	fields `foo-bar`, action, abs(f3-f4) 对于日志组中的所有日志事件检索字段 `foo-bar`、`action` 以及 `f3` 与 `f4` 之间的差值绝对值。 `foo-bar` 周围的反勾号符号 ` 是必需的，因为字段名称包含非字母数字字符。在查询中命名的具有除 @ 符号、句点 (.) 和字母数字字符之外字符的任何日志字段都必须用反引号字符括起来。
`filter`	根据一个或多个条件筛选查询的结果。您可以使用比较运算符（=、!=、<、<=、>、>=）、布尔值运算符（`and`、`or` 和 `not`）和正则表达式。	`fields f1, f2, f3 \| filter (duration>2000)` 对于 `duration` 字段中的值超过 2000 的所有日志事件，检索字段 `f1`、`f2` 和 `f3`。 `filter (duration>2000)` 也是有效查询，则结果不会显示单独的字段。相反，对于持续时间超过 2000 的所有日志事件，结果显示 @timestamp 并在 @message 中显示所有日志数据。 `fields f1, f2 \| filter (f1=10 or f3>25)` 对于 `f1` 为 10 或 `f3` 大于 25 的所有日志事件检索字段 `f1` 和 `f2`。 `fields f1 \| filter statusCode like /2\d\d/` 返回字段 `statusCode` 的值介于 200 与 299 之间的日志事件。
`stats`	根据日志字段的值计算聚合统计数据。支持若干统计运算符，包括 `sum()`、`avg()`、`count()`、`,min()` 和 `max()`。当您使用 `stats` 时，您也可以使用 `by` 指定一个或多个条件，以便在计算统计数据时用于对数据进行分组。	`stats avg (f1) by f2` 为 `f2` 的每个唯一值计算 `f1` 的平均值。
`sort`	对检索的日志事件排序。同时支持升序 (`asc`) 和降序 (`desc`)。	`fields f1, f2, f3 \| sort f1 desc` 检索字段 `f1`、`f2` 和 `f3`，并根据 `f1` 的值按降序对返回的事件排序。
`limit`	限制查询返回的日志事件数。	`fields f1, f2 \| sort @timestamp desc \| limit 25` 检索字段 `f1` 和 `f2`，根据 `@timestamp` 的值以降序对事件进行排序，并按排序顺序返回前 25 个事件。在这种情况下，排序顺序是按最近的时间戳，因此会返回最新 25 个事件。随 CloudWatch Logs Insights 提供的一些示例查询使用 `head` 或 `tail` 命令，而非 `limit`。这些命令现正被弃用并已替换为 `limit`。在写入的所有查询中使用 `limit` 而非 `head` 或 `tail`。
`parse`	从日志字段提取数据，同时创建一个或多个您可以在查询中进一步处理的临时字段。`parse` 既接受 glob 表达式又接受正则表达式。对于 glob 表达式，为解析命令提供一个常量字符串（用单引号或双引号括起来的字符），其中每个可变文本段都用星号 () 替换。它们被提取到临时字段中，并按照位置顺序在 `as` 关键字之后给定别名。在正则表达式两旁加上正斜杠 (/)。在表达式中，要提取的匹配字符串的每个部分均包含在一个命名的捕获组中。`(?<name>.)` 是一个命名的捕获组示例，其中 `name` 为名称，`.*` 为模式。	使用此单个日志行作为示例： `25 May 2019 10:24:39,474 [ERROR] {foo=2, bar=data} The error was: DataIntegrityException` 以下两个解析表达式均提供临时字段 `level`、`config` 和 `exception`，以及值 `ERROR`、`{foo=2, bar=data}` 和 `DataIntegrityException`。第一个表达式使用 glob 表达式，第二个表达式使用正则表达式。 `parse @message "[] The error was: " as level, config, exception` `parse @message /\[(?<level>\S+)\]\s+(?<config>\{.\})\s+The error was: (?<exception>\S+)/`

筛选命令中的正则表达式

您可以在 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"

以下示例使用正则表达式并返回 f1 中包含单词 Exception 的所有事件。查询不区分大小写。


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

以下示例使用正则表达式并返回 f1 中确切包含单词 Exception 的所有事件。查询不区分大小写。


fields f1, f2, f3 | filter f1 =~ /^(?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 命令中使用比较运算并将其用作其他函数的参数。比较运算接受所有数据类型作为参数，并返回布尔值结果。


= != < <= > >=

算术运算

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

操作	说明
`a + b`	加
`a - b`	减
`a * b`	乘
`a / b`	除
`a ^ b`	幂。`2 ^ 3` 返回 `8`
`a % b`	余额或模数。`10 % 3` 返回 `1`

数值运算

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

操作	说明
`abs(a)`	绝对值
`ceil(a)`	舍入到上限（大于 `a` 的值的最小整数）。
`floor(a)`	舍入到下限（小于 `a` 的值的最大整数）。
`greatest(a,b,... z)`	返回最大值。
`least(a, b, ... z)`	返回最小值。
`log(a)`	自然对数
`sqrt(a)`	平方根

常规函数

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

函数	参数	结果类型	描述
`ispresent(fieldname)`	日志字段	Boolean	如果字段存在，则返回 `true`。
`coalesce(fieldname1, fieldname2, ... fieldnamex)`	日志字段	日志字段	返回列表中的第一个非 null 值。

字符串函数

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

函数	参数	结果类型	描述
`isempty(fieldname)`	字符串	Boolean	如果字段缺失或为空字符串，则返回 `true`。
`isblank(fieldname)`	字符串	Boolean	如果字段缺失或为空字符串，或只包含空格，则返回 `true`。
`concat(string1, string2, ... stringz)`	字符串	字符串	连结字符串。
`ltrim(string) or ltrim(string1, string2)`	字符串	字符串	删除字符串左侧的空格。如果函数具有第二个字符串参数，它将从 `string1` 左侧删除 `string2` 的字符。例如，`ltrim("xyZfooxyZ","xyZ")` 将返回 `"fooxyZ"`。
`rtrim(string) or rtrim(string1, string2)`	字符串	字符串	删除字符串右侧的空格。如果函数具有第二个字符串参数，它将从 `string1` 右侧删除 `string2` 的字符。例如，`rtrim("xyZfooxyZ","xyZ")` 将返回 `"xyZfoo"`。
`trim(string) or trim(string1, string2)`	字符串	字符串	删除字符串两端的空格。如果函数具有第二个字符串参数，它将从 `string1` 的两端删除 `string2` 的字符。例如，`trim("xyZfooxyZ","xyZ")` 将返回 `"foo"`。
`strlen(string)`	字符串	数字	返回 Unicode 代码点中字符串的长度。
`toupper(string)`	字符串	字符串	将字符串转换为大写。
`tolower(string)`	字符串	字符串	将字符串转换为小写。
`substr(string1, x), or substr(string1, x, y)`	字符串、数字或字符串、数字、编号	字符串	返回从由数值参数指定的索引到字符串末尾的子字符串。如果该函数具有二个参数，它包含要检索的子字符串的长度。例如，`substr("xyZfooxyZ",3, 3)` 将返回 `"foo"`。
`replace(string1, string2, string3)`	字符串、字符串、字符串	字符串	将 `string1` 中出现的所有 `string2` 替换为 `string3`。例如：`replace("foo","o","0")` 将返回 `"f00"`。
`strcontains(string1, string2)`	字符串	数字	如果 `string1` 包含 `string2`，则返回 1，否则返回 0。

日期时间函数

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

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

函数	参数	结果类型	描述
`datefloor(a, period)`	时间戳，时间段	时间戳	将时间戳截断到指定的时间段。例如，`datefloor(@timestamp, 1h)` 将 `@timestamp` 的所有值截断至小时底部。
`dateceil(a, period)`	时间戳，时间段	时间戳	将时间戳向上舍入到指定的时间段，然后截断。例如，`dateceil(@timestamp, 1h)` 将 `@timestamp` 的所有值截断至小时顶部。
`bin(period)`	Period	时间戳	将 `@timestamp` 的值舍入到指定的时间段，然后截断。

IP 地址函数

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

函数	参数	结果类型	描述
`isValidIp(fieldname)`	字符串	Boolean	如果字段是有效的 v4 或 v6 IP 地址，则返回 `true`。
`isValidIpV4(fieldname)`	字符串	Boolean	如果字段是有效的 v4 IP 地址，则返回 `true`。
`isValidIpV6(fieldname)`	字符串	Boolean	如果字段是有效的 v4 或 v6 IP 地址，则返回 `true`。
`isValidIp(fieldname)`	字符串	Boolean	如果字段是有效的 v6 IP 地址，则返回 `true`。
`isIpInSubnet(fieldname, string)`	字符串、字符串	Boolean	如果字段是指定的 v4 或 v6 子网中有效的 v4 或 v6 IP 地址，则返回 `true`。
`isIpv4InSubnet(fieldname, string)`	字符串、字符串	Boolean	如果字段是指定的 v4 子网中有效的 v4 IP 地址，则返回 `true`。
`isIpv6InSubnet(fieldname, string)`	字符串、字符串	Boolean	如果字段是指定的 v6 子网中有效的 v6 IP 地址，则返回 `true`。

Stats 命令中的聚合函数

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

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

Stats 命令中的非聚合函数

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

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

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

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