Amazon CloudWatch Logs
用户指南
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

筛选器和模式语法

您需使用指标筛选器在日志事件中搜索和匹配字词、短语或值。当指标筛选器在日志事件中找到其中一个字词、短语或值时,您可以累加 CloudWatch 指标的值。例如,您可以创建一个指标筛选器以在日志事件中搜索 ERROR 并对这个词的出现次数进行计数。

指标筛选器还将从空格分隔的日志事件中提取数字值,例如 Web 请求的延迟。在这些示例中,您可以按照从日志中提取的实际数字值来累加指标值。

此外,您也可以使用条件运算符和通配符创建精确匹配。在创建指标筛选器之前,您可以在 CloudWatch 控制台中测试您的搜索模式。以下各个部分更为详细地描述了指标筛选器语法。

匹配事件日志中的字词

要搜索日志事件中的字词,可将该字词用作指标筛选器模式。您可以在指标筛选器模式中指定多个字词,但所有字词都必须出现在日志事件中才算是匹配。指标筛选器区分大小写。

包括字母数字或下划线之外其他字符的指标筛选器字词必须放在双引号 ("") 内。

要排除某个字词,可在该字词前使用减号 (-)。

示例 1:单个字词

“ERROR”筛选器模式匹配包含此字词的日志事件消息,例如以下内容:

  • [ERROR] A fatal exception has occurred

  • Exiting with ERRORCODE: -1

示例 2:包括一个字词,同时排除一个字词

在上面的示例中,如果您将筛选器模式更改为“ERROR”-“Exiting”,将会排除日志事件消息“Exiting with ERRORCODE: -1”。

示例 3:多个字词

“ERROR Exception”筛选器模式匹配同时包含这两个字词的日志事件消息,例如以下内容:

  • [ERROR] Caught IllegalArgumentException

  • [ERROR] Unhandled Exception

“Failed to process the request”筛选器模式匹配包含所有这些字词的日志事件消息,例如以下内容:

  • [WARN] Failed to process the request

  • [ERROR] Unable to continue: Failed to process the request

匹配 JSON 日志事件中的字词

您可以从 JSON 日志事件中提取值。要从 JSON 日志事件中提取值,您需要创建基于字符串的指标筛选器。不支持包含科学表示法的字符串。JSON 日志事件数据中的项目必须与指标筛选器完全匹配。您可能要在 JSON 日志事件中创建指标筛选器以便指示以下情况:

  • 特定事件发生。例如 eventName 是“UpdateTrail”。

  • IP 处于已知子网外部。例如,sourceIPAddress 不在某个已知子网范围内。

  • 满足两个或更多其他条件的组合。例如,eventName 是“UpdateTrail”,并且 recipientAccountId 是 123456789012。

使用指标筛选器从 JSON 日志事件中提取值

您可以使用指标筛选器从 JSON 日志事件中提取值。指标筛选器检查传入日志,并在筛选器找到日志数据中的匹配时修改数字值。创建指标筛选器时,您可以每次在日志中找到匹配文本时累加计数,或者可以从日志中提取数值并使用这些值来累加指标值。

使用指标筛选器匹配 JSON 字词

JSON 日志事件的指标筛选语法使用以下格式:

Copy
{ SELECTOR EQUALITY_OPERATOR STRING }

指标筛选器必须包含在大括号 { } 内,以指示这是 JSON 表达式。指标筛选器包含以下部分:

SELECTOR

指定要检查的 JSON 属性。属性选择器始终以美元符号 ($) 开头,这表示 JSON 的根。属性选择器是字母数字字符串,它还支持“-”和“_”字符。数组元素通过 [NUMBER] 语法表示,必须跟在属性之后。示例:$.eventId、$.users[0]、$.users[0].id、$.requestParameters.instanceId。

EQUALITY_OPERATOR

可以是 = 或 !=.

STRING

带或不带引号的字符串。您可以在搜索词中、之前或之后使用星号“*”通配符来匹配任何文本。例如,*Event 将与 PutEventGetEvent 匹配。Event* 将与 EventIdEventName 匹配。Ev*ent 只与实际字符串 Ev*ent 匹配。完全由字母数字字符组成的字符串无需引号。包含 unicode 和其他字符 (如“@”、“$”、“\”等) 的字符串必须包含在双引号内才有效。

JSON 指标筛选器示例

以下是一个 JSON 示例:

Copy
{ "eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ { "name": "a", "id": 1 }, { "name": "b", "id": 2 } ], "SomeObject": null, "ThisFlag": true }

以下筛选器将匹配:

Copy
{ $.eventType = "UpdateTrail" }

针对事件类型是 UpdateTrail 的筛选器。

Copy
{ $.sourceIPAddress != 123.123.* }

针对处于子网 123.123 前缀之外的 IP 地址的筛选器。

Copy
{ $.arrayKey[0] = "value" }

针对 arrayKey 中的第一个条目是“value”的筛选器。如果 arrayKey 不是数组,则为 false。

Copy
{ $.objectList[1].id = 2 }

针对 objectList 中的第二个条目的 id 属性 = 2 的筛选器。如果 objectList 不是数组,则为 false。如果 objectList 中的项目不是对象或者没有 id 属性,则为 false。

Copy
{ $.SomeObject IS NULL }

针对 SomeObject 设置为 null 的筛选器。仅当指定的对象为 null 时,此条件才成立。

Copy
{ $.SomeOtherObject NOT EXISTS }

针对 SomeOtherObject 不存在的筛选器。仅当指定的对象在日志数据中不存在时,此条件才成立。

Copy
{ $.ThisFlag IS TRUE }

针对 ThisFlag 为 TRUE 的筛选器。这也适用于看检查是否有 FALSE 值的布尔筛选器。

JSON 复合条件

您可以使用 OR (||) 和 AND (&&) 将多个条件合并为复合表达式。允许使用圆括号,语法遵循标准运算顺序 () > && > ||。

Copy
{ "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] ] }
示例
Copy
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }

与以上 JSON 匹配。

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

与以上 JSON 不匹配。

Copy
{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch && $.actions[2] = nomatch }

与以上 JSON 匹配。

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

与以上 JSON 不匹配。

JSON 特殊注意事项

SELECTOR 必须指向 JSON 中的一个值节点 (字符串或数字)。如果它指向数组或对象,则不会应用筛选器,因为日志格式与筛选器不匹配。例如,{$.users = 1} 和 {$.users != 1} 都无法与其中用户是数组的日志事件匹配:

Copy
{ "users": [1, 2, 3] }
数字比较

指标筛选器语法支持数字比较的精确匹配。支持以下数字比较:<、>、>=、<=、=、!=

数字筛选器的语法为

Copy
{ SELECTOR NUMERIC_OPERATOR NUMBER }

指标筛选器必须包含在大括号 { } 内,以指示这是 JSON 表达式。指标筛选器包含以下部分:

SELECTOR

指定要检查的 JSON 属性。属性选择器始终以美元符号 ($) 开头,这表示 JSON 的根。属性选择器是字母数字字符串,它还支持“-”和“_”字符。数组元素通过 [NUMBER] 语法表示,必须跟在属性之后。示例:$.latency、$.numbers[0]、$.errorCode、$.processes[4].averageRuntime。

NUMERIC_OPERATOR

可能是以下值之一:=、!=, <, >, <=, 或者 >=.

NUMBER

带可选 + 或 - 符号的整数、带可选 + 或 - 符号的小数或采用科学表示法的数字 (带可选 + 或 - 符号的整数或小数,后跟“e”,后跟带可选 + 或 - 符号的整数)。

示例:

Copy
{ $.latency >= 500 } { $.numbers[0] < 10e3 } { $.numbers[0] < 10e-3 } { $.processes[4].averageRuntime <= 55.5 } { $.errorCode = 400 } { $.errorCode != 500 } { $.latency > +1000 }

使用指标筛选器从空格分隔的日志事件中提取值

您可以使用指标筛选器从空格分隔的日志事件中提取值。将一对方括号 [] 或两个双引号 ("") 之间的字符视为单个字段。例如:

Copy
127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] "GET /apache_pb.gif HTTP/1.0" 200 1534 127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] "GET /apache_pb.gif HTTP/1.0" 500 5324 127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] "GET /apache_pb.gif HTTP/1.0" 200 4355

要指定解析空格分隔的事件的指标筛选器模式,指标筛选器模式必须使用名称指定字段,以逗号隔开,且整个模式包括在方括号中。例如:[ip, user, username, timestamp, request, status_code, bytes]。

如果您不知道字段数,可以使用省略号 (…) 进行快速输入。例如:

Copy
[..., status_code, bytes] [ip, user, ..., status_code, bytes] [ip, user, ...]

您还可以对您的字段添加条件,以使只有满足所有条件的日志事件才能与筛选器匹配。例如:

Copy
[ip, user, username, timestamp, request, status_code, bytes > 1000] [ip, user, username, timestamp, request, status_code = 200, bytes] [ip, user, username, timestamp, request, status_code = 4*, bytes] [ip, user, username, timestamp, request = *html*, status_code = 4*, bytes]

CloudWatch Logs 支持字符串和数字条件字段。对于字符串字段,您可以将 = 或 != 运算符和星号 (*) 一起使用。

对于数字字段,您可以使用 >、<、>=、<=、= 和 != 运算符。

如果您使用的是以空格分隔的筛选条件,提取的域将映射到以空格分隔的域的名称 (如筛选条件中所示),再映射到所有这些域的值。如果您使用的不是以空间分隔的筛选条件,这将为空。

示例筛选条件:

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

筛选条件的示例日志事件:

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

日志事件和筛选器模式的提取的域:

Copy
{ "$status_code": "400", "$request": "GET /products/index.html HTTP/1.0", "$7": "1534", "$4": "10/Oct/2000:13:25:15 -0700", "$3": "frank", "$2": "-", "$1": "127.0.0.1" }

设置在发现匹配项时如何更改指标值

指标筛选器在日志事件中找到一个匹配字词、短语或值时,它会按照您为“Metric Value”指定的数量累加 CloudWatch 指标中的计数。指标值每分钟聚合并报告。

如果在 1 分钟时段内提取日志,但未找到任何匹配项,则报告为 Default Value 指定的值 (如果有)。不过,如果在 1 分钟时段内未提取日志事件,则不会报告任何值。

指定 Default Value (即使该值为 0) 可帮助确保更频繁地报告数据,从而在未找到匹配项时帮助防止断点指标。

例如,假设有一个日志组,每分钟发布两条记录,并且“Metric Value”为 1,“Default Value”为 0。如果在第一分钟内的两个日志记录中均找到了匹配项,则该分钟的指标值为 2。如果第二分钟内发布的日志记录中没有匹配项,则为两个日志记录均使用“Default Value”(即 0),该分钟的指标值为 0。

如果您未指定“Default Value”,则对于未找到模式匹配的任意时间段,不报告任何数据。

发布日志条目中找到的数值

您也可以使用指标筛选器根据在日志中找到的数值来发布值,而不是计算在日志中找到的匹配项的数目。以下步骤介绍了如何使用在 JSON 请求 metricFilter: { $.latency = * } metricValue: $.latency 中发现的延迟发布指标。

使用 JSON 请求中的延迟发布指标

  1. 通过以下网址打开 CloudWatch 控制台:https://console.amazonaws.cn/cloudwatch/

  2. 在导航窗格中,选择 Logs

  3. 在内容窗格中,选择一个日志组,然后选择 Create Metric Filter

  4. Define Logs Metric Filter 屏幕上,为 Filter Pattern 键入 { $.latency = * },然后选择 Assign Metric

  5. Create Metric Filter and Assign a Metric 屏幕上,选择 Show advanced metric settings

  6. Metric Name 键入 myMetric

  7. 对于 Metric Value,输入 $.latency

  8. 对于 Default Value,键入 0,然后选择 Create Filter。指定默认值可确保即使在未出现日志事件的时间段内也报告有数据,防止出现有时不存在数据的断点指标。

以下日志事件会在过滤器创建之后将值 50 发布到指标 myMetric

Copy
{ "latency": 50, "requestType": "GET" }