指标筛选条件、订阅筛选条件、筛选日志事件和 Live Tail 的筛选条件模式语法 - Amazon CloudWatch 日志
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

指标筛选条件、订阅筛选条件、筛选日志事件和 Live Tail 的筛选条件模式语法

注意

有关如何使用 Amazon CloudWatch Logs Insights 查询语言查询日志组的信息,请参阅 CloudWatch 日志见解查询语法

借助 CloudWatch Logs,您可以使用指标筛选条件将日志数据转换为可操作的指标,使用订阅筛选条件将日志事件路由到其他 Amazon 服务,使用筛选日志事件来搜索日志事件,以及使用 Live Tail 实时交互式查看提取的日志。

筛选条件模式构成了指标筛选条件、订阅筛选条件、筛选日志事件和 Live Tail 用来匹配日志事件中的字词的语法。字词可以是单词、准确的短语或数字值。正则表达式(regex)可用于创建独立的筛选条件模式,也可以与 JSON 和以空格分隔的筛选条件模式合并。

使用要匹配的字词创建筛选条件模式。筛选条件模式仅返回包含您定义的字词的录入事件。您可以在 CloudWatch 控制台中测试筛选条件模式。

支持的正则表达式(regex)语法

使用正则表达式搜索和筛选日志数据时,必须用 % 将表达式括起来。

使用正则表达式的筛选条件模式只能包括以下内容:

  • 字母数字字符 – 字母数字字符是字母(从 A 到 Z 或 a 到 z)或数字(从 0 到 9)字符。

  • 支持的符号字符 – 这些符号包括:“_”、“#”、“=”、“@”、“/”、“;”、“,”和“-”。例如,%something!% 会被拒绝,因为不支持“!”。

  • 支持的运算符 – 这些运算符包括:“^”、“$”、“?”、“[”、“]”、“{”、“}”、“|”、“\”、“*”、“+”和“.”。

不支持 () 运算符。不能使用括号来定义子模式。

不支持多字节字符。

注意

配额

在创建指标筛选条件或订阅筛选条件时,每个日志组最多有 5 个包含正则表达式的筛选条件模式。

为指标筛选条件和订阅筛选条件创建带分隔符的筛选条件模式或 JSON 筛选条件模式,或者筛选日志事件或 Live Tail 时,每个筛选条件模式的正则表达式限制为 2 个。

支持的运算符的使用

  • ^:将匹配项锚定到字符串的开头。例如,%^[hc]at% 匹配“hat”和“cat”,但仅在字符串的开头。

  • $:将匹配项锚定到字符串的结尾。例如,%[hc]at$% 匹配“hat”和“cat”,但仅在字符串的结尾。

  • ?:匹配前面字词的零个或多个实例。例如,%colou?r% 可以同时匹配“color”和“colour”。

  • []:定义字符类。匹配方括号内包含的字符列表或字符范围。例如,%[abc]% 匹配“a”、“b”或“c”;%[a-z]% 匹配从“a”到“z”的任何小写字母;%[abcx-z]% 匹配 “a”、“b”、“c”、“x”、“y”或“z”。

  • {m, n}:与前面的字词匹配至少 m 次且不超过 n 次。例如,%a{3,5}% 仅匹配“aaa”、“aaaa”和“aaaaa”。

    注意

    如果您选择不定义最小值或最大值,则可以省略 mn

  • |:布尔值“Or”,与竖线两侧的字词相匹配。例如,%gra|ey% 可以匹配“gray”或“grey”。

    注意

    字词是单个字符或重复字符类,其使用以下运算符之一:?*+{n,m}

  • \:转义字符,允许您使用运算符的字面含义而不是其特殊含义。例如,%\[.\]% 匹配任何由“[”和“]”括起来的单个字符,因为方括号已转义,例如“[a]”、“[b]”、“[7]”、“[@]”、“[]]”和“[ ]”。

    注意

    %10\.10\.0\.1% 是创建正则表达式来匹配 IP 地址 10.10.0.1 的正确方法。

  • *:匹配前面字词的零个或多个实例。例如, %ab*c% 可以匹配“ac”、“abc”和“abbbc”;%ab[0-9]*% 可以匹配“ab”、“ab0”和“ab129”。

  • +:匹配前面字词的一个或多个实例。例如,%ab+c% 可以匹配“abc”、“abbc”和“abbbc”,但不匹配“ac”。

  • .:匹配任意单个字符。例如,%.at% 匹配以“at”结尾的任意三个字符串,包括“hat”、“cat”、“bat”、“4at”、“#at”和“ at”(以空格开头)。

    注意

    在创建正则表达式以匹配 IP 地址时,转义 . 运算符很重要。例如,%10.10.0.1% 可能匹配“10010,051”,这可能不是表达式的实际预期用途。

  • \d\D:匹配数字/非数字字符。例如,%\d% 等同于 %[0-9]%%\D% 等同于 %[^0-9]%

    注意

    大写运算符表示其小写对应运算符的逆运算符。

  • \s\S:匹配空格字符/非空格字符。

    注意

    大写运算符表示其小写对应运算符的逆运算符。空格字符包括制表符 (\t)、空格 ( ) 和换行符 (\n)。

  • \w\W:匹配字母数字字符/非字母数字字符。例如,%\w% 等同于 %[a-zA-Z_0-9]%%\W% 等同于 %[^a-zA-Z_0-9]%

    注意

    大写运算符表示其小写对应运算符的逆运算符。

  • \xhh:匹配两位十六进制字符的 ASCII 映射。\x 是转义序列,表示以下字符代表 ASCII 的十六进制值。hh 指定指向 ASCII 表中字符的两个十六进制数字(0-9 和 A-F)。

    注意

    您可以使用 \xhh 匹配筛选条件模式不支持的符号字符。例如,%\x3A% 匹配 :%\x28% 匹配 (

使用筛选条件模式将字词与正则表达式(regex)进行匹配

您可以使用 % 括起来的正则表达式模式(正则表达式模式前后有百分号)来匹配日志事件中的字词。下面的代码段显示了筛选条件模式的示例,该模式返回包含 AUTHORIZED 关键字的所有日志事件。

有关支持的正则表达式的列表,请参阅支持的正则表达式

%AUTHORIZED%

此筛选条件模式返回日志事件消息,例如以下内容:

  • [ERROR 401] UNAUTHORIZED REQUEST

  • [SUCCESS 200] AUTHORIZED REQUEST

使用筛选条件模式匹配非结构化日志事件中的字词

以下示例包含代码段,这些代码段显示了如何使用筛选条件模式匹配非结构化日志事件中的字词。

注意

筛选条件模式区分大小写。将包含非字母数字字符的精确短语和字词用双引号括起来 ("")。

Example: Match a single term

下面的代码段显示了单个字词筛选条件模式的示例,该模式返回其中的消息包含字词 ERROR 的所有录入事件。

ERROR

此筛选条件模式匹配日志事件消息,例如以下内容:

  • [ERROR 400] BAD REQUEST

  • [ERROR 401] UNAUTHORIZED REQUEST

  • [ERROR 419] MISSING ARGUMENTS

  • [ERROR 420] INVALID ARGUMENTS

Example: Match multiple terms

下面的代码段显示了多个字词筛选条件模式的示例,该模式返回其中的消息包含字词 ERRORARGUMENTS 的所有录入事件。

ERROR ARGUMENTS

筛选条件返回录入事件消息,例如以下内容:

  • [ERROR 419] MISSING ARGUMENTS

  • [ERROR 420] INVALID ARGUMENTS

筛选条件模式不会返回以下日志事件消息,因为它们不包含筛选条件模式中指定的两个字词。

  • [ERROR 400] BAD REQUEST

  • [ERROR 401] UNAUTHORIZED REQUEST

Example: Match optional terms

您可以使用模式匹配来创建返回包含可选字词的日志事件的筛选条件模式。在您想匹配的字词前放置问号 ("?")。下面的代码片段将显示筛选条件模式的一个示例,它将返回消息中包含单词 ERRORARGUMENTS 的所有日志事件。

?ERROR ?ARGUMENTS

此筛选条件模式匹配日志事件消息,例如以下内容:

  • [ERROR 400] BAD REQUEST

  • [ERROR 401] UNAUTHORIZED REQUEST

  • [ERROR 419] MISSING ARGUMENTS

  • [ERROR 420] INVALID ARGUMENTS

注意

不能将问号(“?”)与其他筛选条件模式组合,例如包含和排除术语。如果将“?”与其他筛选条件模式组合,问号(“?”)将被忽略。

例如,以下筛选条件模式匹配所有包含词语 REQUEST 的事件,但带有问号(“?”)的筛选条件将被忽略且无效。

?ERROR ?ARGUMENTS REQUEST

日志事件匹配项

  • [INFO] REQUEST FAILED

  • [WARN] UNAUTHORIZED REQUEST

  • [ERROR] 400 BAD REQUEST

Example: Match exact phrases

下面的代码段显示了筛选条件模式的示例,该模式返回其中的消息包含精确短语 INTERNAL SERVER ERROR 的录入事件。

"INTERNAL SERVER ERROR"

此筛选条件模式返回以下日志事件消息:

  • [ERROR 500] INTERNAL SERVER ERROR

Example: Include and exclude terms

您可以创建筛选条件模式,该模式返回录入事件,其中的消息包含一些字词并排除其他字词。在您想排除的字词前放置减号 ("-")。下面的代码段显示了筛选条件模式的示例,该模式返回其中的消息包含字词 ERROR 并排除字词 ARGUMENTS 的录入事件。

ERROR -ARGUMENTS

此筛选条件模式返回日志事件消息,例如以下内容:

  • [ERROR 400] BAD REQUEST

  • [ERROR 401] UNAUTHORIZED REQUEST

此筛选条件模式不会返回以下日志事件消息,因为它们包含单词 ARGUMENTS

  • [ERROR 419] MISSING ARGUMENTS

  • [ERROR 420] INVALID ARGUMENTS

Example: Match everything

您可以用双引号匹配录入事件中的所有内容。下面的代码段显示了筛选条件模式的示例,该模式返回所有录入事件。

" "

使用筛选条件模式匹配 JSON 日志事件中的字词

下面介绍了如何编写与包含字符串和数值的 JSON 字词匹配的筛选条件模式的语法。

Writing filter patterns that match strings

您可以创建筛选条件模式以匹配 JSON 日志事件中的字符串。以下代码段显示了基于字符串的筛选条件模式的语法示例。

{ PropertySelector EqualityOperator String }

用大括号(“{}”)括住筛选条件模式。基于字符串的筛选条件模式必须包含以下部分:

  • 属性选择器

    用美元符号后跟句点 ("$.") 来启动属性选择器。属性选择器是字母数字字符串,它还支持连字符 ("-") 和下划线 ("_") 字符。字符串不支持科学记数法。属性选择器指向 JSON 录入事件中的值节点。值节点可以是字符串或数字。将数组放在属性选择器之后。数组中的元素遵循从零开始的编号系统,即数组中的第一个元素是元素 0,第二个元素是元素 1,依此类推。将元素括在括号 ("[]") 中。如果属性选择器指向数组或对象,则筛选条件模式与日志格式将不匹配。如果 JSON 属性包含句点 (“"."”),则可以使用括号表示法来选择该属性。

    注意

    通配符选择器

    您可以使用 JSON 通配符来选择任何数组元素或任何 JSON 对象字段。

    配额

    在一个属性选择器中最多只能使用一个通配符选择器。

  • 等号运算符

    使用以下符号之一来启动等号运算符:等于 ("=") 或不等于 ("!=")。等号运算符返回布尔值(true 或 false)。

  • 字符串

    您可以用双引号 ("") 将字符串括起来。包含除字母数字字符和下划线符号以外的其他类型的字符串必须放在双引号中。使用星号 ("*") 作为通配符来匹配文本。

    注意

    创建筛选条件模式来匹配 JSON 日志事件中的字词时,可以使用任何条件正则表达式。有关支持的正则表达式的列表,请参阅支持的正则表达式

以下代码段包含筛选条件模式的示例,显示了可以如何格式化筛选条件模式,以将 JSON 字词与字符串匹配。

{ $.eventType = "UpdateTrail" }
Writing filter patterns that match numeric values

您可以创建筛选条件模式以匹配 JSON 日志事件中的数字值。以下代码段显示了与数字值匹配的筛选条件模式的语法示例。

{ PropertySelector NumericOperator Number }

用大括号(“{}”)括住筛选条件模式。与数字值匹配的筛选条件模式必须包含以下部分:

  • 属性选择器

    用美元符号后跟句点 ("$.") 来启动属性选择器。属性选择器是字母数字字符串,它还支持连字符 ("-") 和下划线 ("_") 字符。字符串不支持科学记数法。属性选择器指向 JSON 录入事件中的值节点。值节点可以是字符串或数字。将数组放在属性选择器之后。数组中的元素遵循从零开始的编号系统,即数组中的第一个元素是元素 0,第二个元素是元素 1,依此类推。将元素括在括号 ("[]") 中。如果属性选择器指向数组或对象,则筛选条件模式与日志格式将不匹配。如果 JSON 属性包含句点 (“"."”),则可以使用括号表示法来选择该属性。

    注意

    通配符选择器

    您可以使用 JSON 通配符来选择任何数组元素或任何 JSON 对象字段。

    配额

    在一个属性选择器中最多只能使用一个通配符选择器。

  • 数值运算符

    使用以下符号之一来启动数字运算符:大于 (">")、小于 ("<")、等于 ("=")、不等于 ("!=")、大于等于 (">=") 或小于等于 ("<=")。

  • 数字

    您可以使用包含加号 ("+") 或减号 ("-") 符号的整数并遵循科学记数法。使用星号 ("*") 作为通配符来匹配数字。

以下代码段包含示例,显示了可以如何格式化筛选条件模式,以将 JSON 字词与数字值匹配。

// Filter pattern with greater than symbol { $.bandwidth > 75 } // Filter pattern with less than symbol { $.latency < 50 } // Filter pattern with greater than or equal to symbol { $.refreshRate >= 60 } // Filter pattern with less than or equal to symbol { $.responseTime <= 5 } // Filter pattern with equal sign { $.errorCode = 400} // Filter pattern with not equal sign { $.errorCode != 500 } // Filter pattern with scientific notation and plus symbol { $.number[0] = 1e-3 } // Filter pattern with scientific notation and minus symbol { $.number[0] != 1e+3 }

以下示例包含代码段,显示了筛选条件模式如何与 JSON 日志事件中的字词匹配。

注意

如果您使用示例 JSON 日志事件测试示例筛选条件模式,则必须在单行中输入示例 JSON 日志。

JSON 日志事件

{ "eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ { "name": "a", "id": 1 }, { "name": "b", "id": 2 } ], "SomeObject": null, "cluster.name": "c" }
Example: Filter pattern that matches string values

此筛选条件模式与属性 "eventType" 中的字符串 "UpdateTrail" 匹配。

{ $.eventType = "UpdateTrail" }
Example: Filter pattern that matches string values (IP address)

此筛选条件模式包含通配符并与属性 "sourceIPAddress" 匹配,因为它不包含带有前缀 "123.123." 的数字。

{ $.sourceIPAddress != 123.123.* }
Example: Filter pattern that matches a specific array element with a string value

此筛选条件模式与数组 "arrayKey" 中的元素 "value" 匹配。

{ $.arrayKey[0] = "value" }
Example: Filter pattern that matches a string using regex

此筛选条件模式与属性 "eventType" 中的字符串 "Trail" 匹配。

{ $.eventType = %Trail% }
Example: Filter pattern that uses a wildcard to match values of any element in the array using regex

筛选条件模式包含与数组 "arrayKey" 中的元素 "value" 匹配的正则表达式。

{ $.arrayKey[*] = %val.{2}% }
Example: Filter pattern that uses a wildcard to match values of any element with a specific prefix and subnet using regex (IP address)

此筛选条件模式包含与属性 "sourceIPAddress" 中的元素 "111.111.111.111" 匹配的正则表达式。

{ $.* = %111\.111\.111\.1[0-9]{1,2}% }
注意

配额

在一个属性选择器中最多只能使用一个通配符选择器。

Example: Filter pattern that matches a JSON property with a period (.) in the key
{ $.['cluster.name'] = "c" }
Example: Filter pattern that matches JSON logs using IS

您可以创建筛选条件模式,它们使用 IS 变量匹配 JSON 日志中的字段。IS 变量可以匹配包含值 NULLTRUEFALSE 的字段。下面的筛选条件模式返回 JSON 日志,其中 SomeObject 的值为 NULL

{ $.SomeObject IS NULL }
Example: Filter pattern that matches JSON logs using NOT EXISTS

您可以使用 NOT EXISTS 变量创建筛选条件模式,以返回日志数据中不包含特定字段的 JSON 日志。下面的筛选条件模式使用 NOT EXISTS 返回不包含字段 SomeOtherObject 的 JSON 日志。

{ $.SomeOtherObject NOT EXISTS }
注意

目前不支持变量 IS NOTEXISTS

您可以在筛选条件模式中使用逻辑运算符 AND(“&&”)和 OR(“||”)来创建匹配两个或更多条件为 true 的日志事件的复合表达式。复合表达式支持使用括号 ("()") 和以下运算的标准顺序:() > && > ||。以下示例包含代码段,这些代码段显示了如何使用具有复合表达式的筛选条件模式来匹配 JSON 对象中的字词。

JSON 对象

{ "user": { "id": 1, "email": "John.Stiles@example.com" }, "users": [ { "id": 2, "email": "John.Doe@example.com" }, { "id": 3, "email": "Jane.Doe@example.com" } ], "actions": [ "GET", "PUT", "DELETE" ], "coordinates": [ [0, 1, 2], [4, 5, 6], [7, 8, 9] ] }
Example: Expression that matches using AND (&&)

此筛选条件模式包含复合表达式,该表达式匹配 "user" 中的 "id"(数字值为 1)和 "users" 数组中第一个元素中的 "email"(字符串为 "John.Doe@example.com")。

{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }
Example: Expression that matches using OR (||)

此筛选条件模式包含复合表达式,匹配 "user" 中的 "email"(字符串为 "John.Stiles@example.com")。

{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = "nonmatch" && $.actions[2] = "nonmatch" }
Example: Expression that doesn't match using AND (&&)

此筛选条件模式包含无法找到匹配项的复合表达式,因为该表达式与 "actions" 中的第三个操作不匹配。

{ ($.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = "nonmatch") && $.actions[2] = "nonmatch" }
注意

配额

在属性选择器中最多只能使用一个通配符选择器,在具有复合表达式的筛选条件模式中最多只能使用三个通配符选择器。

Example: Expression that doesn't match using OR (||)

此筛选条件模式包含无法找到匹配项的复合表达式,因为该表达式与 "users" 中的第一个属性不匹配,或 "actions" 中的第三个操作不匹配。

{ ($.user.id = 2 && $.users[0].email = "nonmatch") || $.actions[2] = "GET" }

使用筛选条件模式来匹配以空格分隔的日志事件中的字词

您可以创建筛选条件模式来匹配以空格分隔的日志事件中的字词。下面提供了一个以空格分隔的日志事件示例,并介绍了如何编写与以空格分隔的日志事件中的字词匹配的筛选条件模式语法。

注意

创建筛选条件模式来匹配以空格分隔的日志事件中的字词时,可以使用任何条件正则表达式。有关支持的正则表达式的列表,请参阅支持的正则表达式

Example: Space-delimited log event

以下代码段显示了以空格分隔的录入事件,其中包含七个字段:ipuserusernametimestamprequeststatus_codebytes

127.0.0.1 Prod frank [10/Oct/2000:13:25:15 -0700] "GET /index.html HTTP/1.0" 404 1534
注意

括号 ("[]") 和双引号 ("") 之间的字符被视为单个字段。

Writing filter patterns that match terms in a space-delimited log event

要创建与以空格分隔的日志事件中的字词匹配的筛选条件模式,请用方括号(“[]”)将筛选条件模式括起来,并以不同名称指定各个字段,用逗号 (“,”)隔开。以下筛选条件模式解析七个字段。

[ip=%127\.0\.0\.[1-9]%, user, username, timestamp, request =*.html*, status_code = 4*, bytes]

您可以使用数字运算符(>、<、=、!=、>= 或 <=)和星号 (*) 作为通配符或正则表达式,用于为筛选条件模式提供条件。在示例筛选条件模式中,ip 使用与 IP 地址范围 127.0.0.1 – 127.0.0.9 匹配的正则表达式,request 包含通配符,表示它必须提取以 .html 开头的值,status_code 包含通配符,表示它必须提取以 4 开头的值。

如果您不知道在以空格分隔的录入事件中解析的字段数量,则可以使用省略号 (...) 来引用任何未命名的字段。省略号可以根据需要引用尽可能多的字段。以下示例显示带省略号的筛选条件模式,该筛选条件表示之前的示例筛选条件模式中显示的前四个未命名字段。

[..., request =*.html*, status_code = 4*, bytes]

您还可以使用逻辑运算符 AND (&&) 和 OR (||) 来创建复合表达式。以下筛选条件模式包含复合表达式,该表达式表示 status_code 的值必须是 404410

[ip, user, username, timestamp, request =*.html*, status_code = 404 || status_code = 410, bytes]

您可以使用模式匹配来创建以空格分隔的筛选条件模式,以匹配特定顺序的字词。使用指示符指定字词的顺序。使用 w1 代表您的第一个字词,以及 w2 以此类推,来表示后续字词的顺序。在字词之间放置逗号 (",")。以下示例包含代码段,这些代码段显示了如何将模式匹配与以空格分隔的筛选条件模式结合使用。

注意

创建筛选条件模式来匹配以空格分隔的日志事件中的字词时,可以使用任何条件正则表达式。有关支持的正则表达式的列表,请参阅支持的正则表达式

以空格分隔的日志事件

INFO 09/25/2014 12:00:00 GET /service/resource/67 1200 INFO 09/25/2014 12:00:01 POST /service/resource/67/part/111 1310 WARNING 09/25/2014 12:00:02 Invalid user request ERROR 09/25/2014 12:00:02 Failed to process request
Example: Match terms in order

以下以空格分隔的筛选条件模式会返回日志事件,其中事件中的第一个单词是 ERROR

[w1=ERROR, w2]
注意

创建使用模式匹配的以空格分隔的筛选条件模式时,必须在指定字词顺序后包含空白指示符。例如,如果您创建了一个筛选条件模式,其返回第一个单词为 ERROR 的日志事件,在 w1 字词后包括空白 w2 指示符。

Example: Match terms with AND (&&) and OR (||)

您可以使用逻辑运算符 AND(“&&”)和 OR(“||”)创建包含条件的以空格分隔的筛选条件模式。以下筛选条件模式会返回日志事件,其中事件中的第一个单词是 ERRORWARNING

[w1=ERROR || w1=WARNING, w2]
Example: Exclude terms from matches

您可以创建以空格分隔的筛选条件模式,该筛选条件模式会返回排除一个或多个字词的日志事件。在您想排除的字词前放置不等号 ("!=")。以下代码段显示了筛选条件模式的示例,该筛选条件模式返回第一个字词不是 ERRORWARNING 的日志事件。

[w1!=ERROR && w1!=WARNING, w2]
Example: Match the top level item in a resource URI

以下代码段显示了筛选条件模式的示例,该筛选条件模式使用正则表达式匹配资源 URI 中的顶级项目。

[logLevel, date, time, method, url=%/service/resource/[0-9]+$%, response_time]
Example: Match the child level item in a resource URI

以下代码段显示了筛选条件模式的示例,该筛选条件模式使用正则表达式匹配资源 URI 中的子级项目。

[logLevel, date, time, method, url=%/service/resource/[0-9]+/part/[0-9]+$%, response_time]