筛选条件和模式语法
注意
如果您正在寻找有关如何使用 Amazon CloudWatch Logs Insights 查询语言查询日志组的信息,请参阅查询语法。
您可以创建指标筛选条件以匹配录入事件中的字词,并将日志数据转换为指标。当指标筛选条件与字词匹配时,它会增加指标的计数。例如,您可以创建一个指标筛选条件以计算录入事件中单词 ERROR 出现的次数。
您可以为指标分配单位和维度。例如,如果您创建了一个指标筛选条件,该筛选条件计算了单词 ERROR 在您的录入事件中出现的次数,则可以指定名为 ErrorCode
的维度,以显示包含单词 ERROR 的录入事件总数,并按报告的错误代码筛选数据。
提示
为指标分配单位时,请确保指定正确的单位。如果稍后更改单位,则您的更改可能无法生效。
主题
使用筛选条件模式匹配录入事件中的字词
筛选条件模式构成了指标筛选条件用来匹配录入事件中的字词的语法。字词可以是单词、准确的短语或数字值。使用要匹配的字词创建筛选条件模式。筛选条件模式仅返回包含您定义的字词的录入事件。您可以在 CloudWatch 控制台中测试筛选条件模式。以下示例包含代码段,这些代码段显示了如何使用筛选条件模式匹配录入事件中的字词。
注意
筛选条件模式区分大小写。将包含非字母数字字符的精确短语和字词用双引号括起来 ("")。
示例:匹配单个字词
下面的代码段显示了单个字词筛选条件模式的示例,该模式返回其中的消息包含字词 ERROR 的所有录入事件。
ERROR
筛选条件模式匹配录入事件消息,例如以下内容:
[ERROR 400] BAD REQUEST
[ERROR 401] UNAUTHORIZED REQUEST
[ERROR 419] MISSING ARGUMENTS
[ERROR 420] INVALID ARGUMENTS
示例:匹配多个字词
下面的代码段显示了多个字词筛选条件模式的示例,该模式返回其中的消息包含字词 ERROR 和 ARGUMENTS 的所有录入事件。
ERROR ARGUMENTS
筛选条件返回录入事件消息,例如以下内容:
[ERROR 419] MISSING ARGUMENTS
[ERROR 420] INVALID ARGUMENTS
筛选条件模式不会返回以下录入事件消息,因为它们不包含筛选条件模式中指定的两个字词。
[ERROR 400] BAD REQUEST
[ERROR 401] UNAUTHORIZED REQUEST
示例:匹配单个和多个字词
您可以使用模式匹配来创建返回包含单个和多个字词的录入事件的筛选条件模式。在您想匹配的字词前放置问号 ("?")。下面的代码片段将显示筛选条件模式的一个示例,它将返回消息中包含单词 ERROR 或 ARGUMENTS 以及单词 ERROR 和 ARGUMENTS 的所有日志事件。
?ERROR ?ARGUMENTS
筛选条件模式匹配录入事件消息,例如以下内容:
[ERROR 400] BAD REQUEST
[ERROR 401] UNAUTHORIZED REQUEST
[ERROR 419] MISSING ARGUMENTS
[ERROR 420] INVALID ARGUMENTS
示例:匹配精确短语
下面的代码段显示了筛选条件模式的示例,该模式返回其中的消息包含精确短语 INTERNAL SERVER ERROR 的录入事件。
"INTERNAL SERVER ERROR"
筛选条件模式返回以下录入事件消息:
[ERROR 500] INTERNAL SERVER ERROR
示例:包括和排除字词
您可以创建筛选条件模式,该模式返回录入事件,其中的消息包含一些字词并排除其他字词。在您想排除的字词前放置减号 ("-")。下面的代码段显示了筛选条件模式的示例,该模式返回其中的消息包含字词 ERROR 并排除字词 ARGUMENTS 的录入事件。
ERROR -ARGUMENTS
筛选条件模式返回录入事件消息,例如以下内容:
[ERROR 400] BAD REQUEST
[ERROR 401] UNAUTHORIZED REQUEST
筛选条件模式不会返回以下录入事件消息,因为它们包含单词 ARGUMENTS。
[ERROR 419] MISSING ARGUMENTS
[ERROR 420] INVALID ARGUMENTS
示例:完全匹配
您可以用双引号匹配录入事件中的所有内容。下面的代码段显示了筛选条件模式的示例,该模式返回所有录入事件。
" "
使用指标筛选条件匹配字词并从 JSON 录入事件中提取值
指标筛选条件是包含筛选条件模式的配置。您可以创建指标筛选条件以匹配录入事件中的字词,并将日志数据转换为指标。当指标筛选条件与字词匹配时,您可以增加指标的计数。指标筛选条件仅与您在筛选条件模式中定义的字词匹配。您可以在 CloudWatch 控制台中测试指标筛选条件。您也可以创建指标筛选条件,以匹配字词并从 JSON 录入事件中提取值。以下示例描述了与包含字符串和数字值的 JSON 字词匹配的指标筛选条件语法。
示例:匹配字符串的指标筛选条件
您可以创建指标筛选条件以匹配 JSON 录入事件中的字符串。以下代码段显示了基于字符串的指标筛选条件的语法示例。
{
PropertySelector
EqualityOperator
String
}
用大括号 ("{}") 将指标筛选条件括起来。基于字符串的指标筛选条件必须包含以下部分:
属性选择器
用美元符号后跟句点 ("$.") 来启动属性选择器。属性选择器是字母数字字符串,它还支持连字符 ("-") 和下划线 ("_") 字符。字符串不支持科学记数法。属性选择器指向 JSON 录入事件中的值节点。值节点可以是字符串或数字。将数组放在属性选择器之后。数组包含遵循从零开始的排序系统(0 = 1、1 = 2 等)的元素。将元素括在括号 ("[]") 中。如果属性选择器指向数组或对象,则指标筛选条件与日志格式将不匹配。如果 JSON 属性包含点/句点 (“.”),则可以使用括号表示法来选择该属性。
等号运算符
使用以下符号之一来启动等号运算符:等于 ("=") 或不等于 ("!=")。等号运算符返回布尔值(true 或 false)。
字符串
您可以用双引号 ("") 将字符串括起来。包含除字母数字字符和下划线符号以外的其他类型的字符串必须放在双引号中。使用星号 ("*") 作为通配符来匹配文本。
以下代码段包含指标筛选条件的示例,显示了可以如何格式化指标筛选条件以将 JSON 字词与字符串匹配。
{ $.eventType = "UpdateTrail" }
示例:与数字值匹配的指标筛选条件
您可以创建指标筛选条件以匹配 JSON 录入事件中的数字值。以下代码段显示了与数字值匹配的指标筛选条件的语法示例。
{
PropertySelector
NumericOperator
Number
}
用大括号 ("{}") 将指标筛选条件括起来。与数字值匹配的指标筛选条件必须包含以下部分:
属性选择器
用美元符号后跟句点 ("$.") 来启动属性选择器。属性选择器是字母数字字符串,它还支持连字符 ("-") 和下划线 ("_") 字符。字符串不支持科学记数法。属性选择器指向 JSON 录入事件中的值节点。值节点可以是字符串或数字。将数组放在属性选择器之后。数组包含遵循从零开始的排序系统(0 = 1、1 = 2 等)的元素。将元素括在括号 ("[]") 中。如果属性选择器指向数组或对象,则指标筛选条件与日志格式将不匹配。如果 JSON 属性包含点/句点 (“.”),则可以使用括号表示法来选择该属性。
数值运算符
使用以下符号之一来启动数字运算符:大于 (">")、小于 ("<")、等于 ("=")、不等于 ("!=")、大于等于 (">=") 或小于等于 ("<=")。
数字
您可以使用包含加号 ("+") 或减号 ("-") 符号的整数并遵循科学记数法。使用星号 ("*") 作为通配符来匹配数字。
以下代码段包含示例,显示了可以如何格式化指标筛选条件以将 JSON 字词与数字值匹配。
// Metric filter with greater than symbol { $.bandwidth > 75 } // Metric filter with less than symbol { $.latency < 50 } // Metric filter with greater than or equal to symbol { $.refreshRate >= 60 } // Metric filter with less than or equal to symbol { $.responseTime <= 5 } // Metric filter with equal sign { $.errorCode = 400} // Metric filter with not equal sign and scientific notation { $.errorCode != 500 } // Metric filter with scientific notation and plus symbol { $.number[0] = 1e-3 } // Metric filter with scientific notation and minus symbol { $.number[0] != 1e+3 }
匹配 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" }
注意
如果您使用示例 JSON 录入事件测试示例指标筛选条件,则必须在单行中输入示例 JSON 日志。
示例:匹配字符串的指标筛选条件
指标筛选条件与属性 "eventType"
中的字符串 "UpdateTrail"
匹配。
{ $.eventType = "UpdateTrail" }
示例:匹配数字的指标筛选条件
指标筛选条件包含通配符并与属性 "sourceIPAddress"
匹配,因为它不包含带有前缀 "123.123."
的数字。
{ $.sourceIPAddress != 123.123.* }
示例:与数组中的元素匹配的指标筛选条件
指标筛选条件与数组 "arrayKey"
中的元素 "value"
匹配。
{ $.arrayKey[0] = "value" }
示例:与数组中的对象匹配的指标筛选条件
指标筛选条件与数组 "objectList"
中的对象 "id":2
匹配。
{ $.objectList[1].id = 2 }
示例:使用 IS
匹配 JSON 日志的指标筛选条件
您可以创建指标筛选条件,它们使用 IS
变量匹配 JSON 日志中的字段。IS
变量可以匹配包含值 NULL
、TRUE
或 FALSE
的字段。下面的指标筛选条件将返回 SomeObject
的值为 NULL
的 JSON 日志。
{ $.SomeObject IS NULL }
示例:使用 NOT EXISTS
匹配 JSON 日志的指标筛选条件
您可以使用 NOT EXISTS
变量创建指标筛选条件,以返回日志数据中不包含特定字段的 JSON 日志。下面的指标筛选条件将使用 NOT EXISTS
返回不包含字段 SomeOtherObject
的 JSON 日志。
{ $.SomeOtherObject NOT EXISTS }
注意
目前不支持变量 IS NOT
和 EXISTS
。
使用复合表达式匹配 JSON 对象中的字词
您可以在指标筛选条件中使用逻辑运算符 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] ] }
示例:使用 AND (&&) 匹配的表达式
指标筛选条件包含复合表达式,该表达式匹配 "user"
中的 "id"
(数字值为 1
)和 "email"
中的 "users"
(字符串为 "John.Doe@example.com"
)。
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }
示例:使用 OR (||) 匹配的表达式
指标筛选条件包含复合表达式,匹配 "user"
中的 "email"
(字符串为 "John.Stiles@example.com"
)。
{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = "nonmatch" && $.actions[2] = "nonmatch" }
示例:使用 AND (&&) 不匹配的表达式
指标筛选条件包含无法找到匹配项的复合表达式,因为该表达式与 "coordinates"
中的第一个和第二个坐标不匹配,以及与 "actions"
中的第三个操作不匹配。
{ ($.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = "nonmatch") && $.actions[2] = "nonmatch" }
示例:使用 OR (||) 不匹配的表达式
指标筛选条件包含无法找到匹配项的复合表达式,因为该表达式与 "users"
中的第一个属性不匹配,或 "actions"
中的第三个操作不匹配。
{ ($.user.id = 2 && $.users[0].email = "nonmatch") || $.actions[2] = "GET" }
使用指标筛选条件从空格分隔的日志事件中提取值
您可以创建指标筛选条件,该筛选条件映射至以空格分隔的录入事件字段,并从中提取值。以下示例包含显示以空格分隔的录入事件的代码段、映射到以空格分隔的录入事件字段的指标筛选条件,以及指标筛选条件从以空格分隔的录入事件字段中提取的值。
示例:以空格分隔的录入事件
以下代码段显示了以空格分隔的录入事件,其中包含七个字段:ip
、user
、username
、timestamp
、request
、status_code
和 bytes
。
127.0.0.1 Prod frank [10/Oct/2000:13:25:15 -0700] "GET /index.html HTTP/1.0" 404 1534
注意
括号 ("[]") 和双引号 ("") 之间的字符被视为单个字段。
示例:指标筛选条件
要创建指标筛选条件(该筛选条件映射至以空格分隔的录入事件中的字段并从中提取值),将指标筛选条件用括号 ("[]") 括起来,并指定名称用逗号 (",") 隔开的字段。以下指标筛选条件解析七个字段。
[ip, user, username, timestamp, request =*.html*, status_code = 4*, bytes]
您可以使用数字运算符(>、<、=、!=、>>= 或 <=)和星号 (*) 作为通配符,用于为指标筛选条件提供条件。在示例指标筛选条件中,request
包含通配符,指出它必须提取具有 .html
的值,且 status_code
包含通配符,指出它必须提取以 4
开头的值。
如果您不知道在以空格分隔的录入事件中解析的字段数量,则可以使用省略号 (...) 来引用任何未命名的字段。省略号可以根据需要引用尽可能多的字段。以下示例显示带省略号的指标筛选条件,该筛选条件表示之前的示例指标筛选条件中显示的前四个未命名字段。
[..., request =*.html*, status_code = 4*, bytes]
您还可以使用逻辑运算符 AND (&&) 和 OR (||) 来创建复合表达式。以下指标筛选条件包含复合表达式,该表达式指出 status_code
的值必须是 404
或 410
。
[ip, user, username, timestamp, request =*.html*, status_code = 404 || status_code = 410, bytes]
示例:提取的字段和值
以下代码段显示了指标筛选条件从以空格分隔的录入事件字段中提取的值。
{ "$bytes": "1534", "$status_code": "404", "$request": "GET /index.html HTTP/1.0", "$timestamp": "10/Oct/2000:13:25:15 -0700", "$username": "frank", "$user": "Prod", "$ip": "127.0.0.1" }
使用模式匹配来匹配以空格分隔的录入事件中的字词
您可以使用模式匹配来创建以空格分隔的指标筛选条件,以匹配特定顺序的字词。使用指示符指定字词的顺序。使用 w1 代表您的第一个字词,以及 w2 以此类推,来表示后续字词的顺序。在字词之间放置逗号 (",")。以下示例包含代码段,显示了如何将模式匹配与以空格分隔的指标筛选条件结合使用。
示例:按顺序匹配字词
以下以空格分隔的指标筛选条件会返回其中第一个单词是 ERROR 的录入事件。
[w1=ERROR, w2]
注意
当您创建使用模式匹配的以空格分隔的指标筛选条件时,必须在指定字词顺序后包含空白指示符。例如,如果您创建了一个指标筛选条件,它返回第一个单词为 ERROR 的日志事件,在 w1 字词后包括空白 w2 指示符。
示例:使用 AND (&&) 和 OR (||) 匹配字词
您可以使用逻辑运算符 AND ("&&") 和 OR ("||") 创建包含条件的以空格分隔的指标筛选条件。以下以空格分隔的指标筛选条件会返回录入事件,其中事件中的第一个单词是 ERROR 或 WARNING。
[w1=ERROR || W1=WARNING, w2]
示例:从匹配项中排除字词
您可以创建以空格分隔的指标筛选条件,该筛选条件会返回排除一个或多个字词的录入事件。在您想排除的字词前放置不等号 ("!=")。以下代码段显示了指标筛选条件的示例,该筛选条件返回第一个字词不是 ERROR 和 WARNING 的录入事件。
[w1!=ERROR && w1!=WARNING, w2]
为指标筛选条件配置指标值
创建指标筛选条件时,您可以定义筛选条件模式并指定指标的值和原定设置值。您可以将指标值设置为数字、命名标识符或数字标识符。如果您没有指定原定设置值,则当指标筛选条件找不到匹配项时,CloudWatch 将不会报告数据。即使该值为 0,也建议您指定原定设置值。设置原定设置值有助于 CloudWatch 更准确地报告数据,并防止 CloudWatch 聚合断点指标。CloudWatch 每分钟聚合和报告指标值。
当您的指标筛选条件在录入事件中找到匹配项时,它会按指标值增加指标的计数。如果指标筛选条件找不到匹配项,则 CloudWatch 会报告该指标的原定设置值。例如,您的日志组每分钟发布两条记录,指标值为 1,原定设置值为 0。如果指标筛选条件在第一分钟内的两个日志记录中均找到了匹配项,则该分钟的指标值为 2。如果指标筛选条件在第二分钟内未找到任何记录中的匹配项,则该分钟的原定设置值为 0。如果将维度分配给指标筛选条件生成的指标,则无法为这些指标指定原定设置值。
您还可以设置指标筛选条件,使用从录入事件中提取的值而不是静态值来增加指标。有关更多信息,请参阅使用录入事件中的值来增加指标的值。
使用来自 JSON 或以空格分隔的录入事件的指标发布维度
您可以使用 CloudWatch 控制台或 Amazon CLI 来创建指标筛选条件,该筛选条件使用 JSON 和以空格分隔的录入事件生成的指标来发布维度。维度是名称/值值对,仅适用于 JSON 和以空格分隔的筛选条件模式。您可以创建最多三个维度的 JSON 和以空格分隔的指标筛选条件。有关维度的更多信息以及有关如何将维度分配给指标的信息,请参阅以下各部分:
《Amazon CloudWatch 用户指南》中的维度
《Amazon CloudWatch Logs 用户指南》中的示例:从 Apache 日志中提取字段并分配维度
重要
维度包含收集费用的值,与自定义指标相同。为了防止意外费用,请不要将高基数字段(例如 IPAddress
或 requestID
)指定为维度。
从录入事件中提取的指标按自定义指标收费。为了防止意外的高额费用,如果指标筛选条件为在一定时间内指定的维度生成 1000 个不同的名称/值对,则 Amazon 可能会禁用该指标筛选条件。
您可以创建账单告警,通知您预估费用。有关更多信息,请参阅创建账单告警以监控 Amazon 预估费用。
使用来自 JSON 日志事件的指标发布维度
以下示例包含描述如何在 JSON 指标筛选条件中指定维度的代码段。
示例:JSON 录入事件
{ "eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ {"name": "a", "id": 1 }, {"name": "b", "id": 2 } ] }
注意
如果您使用示例 JSON 录入事件测试示例指标筛选条件,则必须在单行中输入示例 JSON 日志。
示例:指标筛选条件
每当 JSON 录入事件包含属性 eventType
和 "sourceIPAddress"
时,指标筛选条件都会增加指标。
{ $.eventType = "*" && $.sourceIPAddress != 123.123.* }
在创建 JSON 指标筛选条件时,您可以将指标筛选条件中的任何属性指定为维度。例如,要设置 eventType
为维度,请使用以下内容:
"eventType" : $.eventType
示例指标包含名为 "eventType"
的维度,并且示例录入事件中维度的值为 "UpdateTrail"
。
使用来自以空格分隔的日志事件的指标发布维度
以下示例包含描述如何在以空格分隔的指标筛选条件中指定维度的代码段。
示例:以空格分隔的录入事件
127.0.0.1 Prod frank [10/Oct/2000:13:25:15 -0700] "GET /index.html HTTP/1.0" 404 1534
示例:指标筛选条件
[ip, server, username, timestamp, request, status_code, bytes > 1000]
当以空格分隔的录入事件包含筛选条件中指定的任何字段时,指标筛选条件将增加指标。例如,指标筛选条件在以空格分隔的录入事件示例中查找以下字段和值。
{ "$bytes": "1534", "$status_code": "404", "$request": "GET /index.html HTTP/1.0", "$timestamp": "10/Oct/2000:13:25:15 -0700", "$username": "frank", "$server": "Prod", "$ip": "127.0.0.1" }
在创建以空格分隔的指标筛选条件时,您可以将指标筛选条件中的任何字段指定为维度。例如,要设置 server
为维度,请使用以下内容:
"server" : $server
示例指标筛选条件包含名为 server
的维度,并且示例录入事件中维度的值为 "Prod"
。
使用录入事件中的值来增加指标的值
您可以创建指标筛选条件,该筛选条件会发布在录入事件中找到的数字值。本部分中的过程使用以下示例指标筛选条件来显示可以如何将 JSON 录入事件中的数字值发布到指标。
{ $.latency = * } metricValue: $.latency
创建在录入事件中发布值的指标筛选条件
通过以下网址打开 CloudWatch 控制台:https://console.aws.amazon.com/cloudwatch/
。 -
在左侧导航窗格中,选择 Logs(日志),然后选择 Log groups(日志组)。
-
选择或创建日志组。
有关如何建立日志组的更多信息,请参阅《Amazon CloudWatch Logs 用户指南》中的在 CloudWatch Logs 中创建日志组。
-
选择 Actions(操作),然后选择 Create metric filter(创建指标筛选条件)。
-
对于 Filter Pattern(筛选条件模式),输入
{ $.latency = * }
,然后选择 Next(下一步)。 -
对于 Metric Name(指标名称),输入 myMetric。
-
对于 Metric Value(指标值),输入
$.latency
。 (可选)对于 Default Value(原定设置值),输入 0,然后选择 Next(下一步)。
即使该值为 0,也建议您指定原定设置值。设置原定设置值有助于 CloudWatch 更准确地报告数据,并防止 CloudWatch 聚合断点指标。CloudWatch 每分钟聚合和报告指标值。
选择 Create metric filter(创建指标筛选条件)。
示例指标筛选条件与示例 JSON 录入事件中的字词 "latency"
匹配,并将 50 的数字值发布到指标 myMetric。
{ "latency": 50, "requestType": "GET" }