# CloudWatch 中的 Contributor Insights 规则语法
<a name="ContributorInsights-RuleSyntax"></a>

此部分说明了 Contributor Insights 规则的语法。仅当您通过输入 JSON 块来创建规则时使用此语法。如果您使用此向导创建规则，则无需知道语法。有关使用此向导创建规则的更多信息，请参阅 [在 CloudWatch 中创建 Contributor Insights 规则](ContributorInsights-CreateRule.md)。

日志事件字段名称和值的所有规则匹配都区分大小写。

以下示例说明了 JSON 日志的语法。

```
{
    "Schema": {
        "Name": "CloudWatchLogRule",
        "Version": 1
    },
    "LogGroupNames": [
        "API-Gateway-Access-Logs*",
        "Log-group-name2"
    ],
    "LogFormat": "JSON",
    "Contribution": {
        "Keys": [
            "$.ip"
        ],
        "ValueOf": "$.requestBytes",
        "Filters": [
            {
                "Match": "$.httpMethod",
                "In": [
                    "PUT"
                ]
            }
        ]
    },
    "AggregateOn": "Sum"
}
```Contributor Insights 规则中的字段

架构  
 用于分析 CloudWatch Logs 数据 `Schema` 的规则的值必须始终为 `{"Name": "CloudWatchLogRule", "Version": 1}` 

LogGroupNames  
 字符串数组。对于数组中的每个元素，您可以选择在字符串末尾使用 `*` 以包含名称以该前缀开头的所有日志组。  
将通配符用于日志组名称时要小心。您需要为与规则匹配的每个日志事件支付费用。如果不小心搜索了超出预期数量的日志组，可能会产生意外费用。有关更多信息，请参阅 [Amazon CloudWatch 定价](https://aws.amazon.com/cloudwatch/pricing)。

LogGroupARN  
如果您在 CloudWatch 跨账户可观测性监控账户中创建此规则，则可以使用 `LogGroupARNs` 在与该监控账户关联的源账户中指定日志组，然后指定该监控账户本身的日志组。您必须在规则中指定 `LogGroupNames` 或 `LogGroupARNs`，但不能同时指定两者。  
 `LogGroupARNs` 是一个字符串数组。对于该数组中的每个元素，在某些情况下可以选择使用 `*` 作为通配符。例如，您可以指定 `arn:aws:logs:us-west-1:*:log-group/MyLogGroupName2`，以便在美国西部（北加利福尼亚）地区的所有源账户和该监控账户中指定名为 `MyLogGroupName2` 的日志组。您还可以指定 `arn:aws:logs:us-west-1:111122223333:log-group/GroupNamePrefix*`，以便在 111122223333 中指定美国西部（北加利福尼亚）所有名称以 `GroupNamePrefix` 开头的日志组。  
您不能将部分 AWS 账户 ID 指定为带通配符的前缀。  
将通配符用于日志组 ARN 时要小心。您需要为与规则匹配的每个日志事件支付费用。如果不小心搜索了超出预期数量的日志组，可能会产生意外费用。有关更多信息，请参阅 [Amazon CloudWatch 定价](https://aws.amazon.com/cloudwatch/pricing)。

LogFormat  
 有效值为 `JSON` 和 `CLF`。

贡献  
 此对象包含一个具有最多个四个成员的 `Keys` 数组、（可选）一个 `ValueOf`、（可选）一个具有最多四个 `Filters` 的数组。

键  
 一个最多具有四个日志字段的数组，这些字段用作维度以对贡献者进行分类。如果您输入多个键，则这些键的每个唯一值组合将被计为一个独特贡献者。必须使用 JSON 属性格式表示法指定字段。

ValueOf  
 （可选）仅当您指定 `Sum` 作为 `AggregateOn` 的值时指定此选项。`ValueOf` 指定具有数值的日志字段。在此类规则中，贡献者按其在此字段中的值的和来进行排名，而不是按其在日志条目中的出现次数进行排名。例如，如果您希望按贡献者在一段时间内的 `BytesSent` 总数对其进行排名，则需要将 `ValueOf` 设置为 `BytesSent`，并为 `AggregateOn` 指定 `Sum`。

筛选条件  
 指定具有最多四个筛选条件的数组可缩小报告中包含的日志事件的范围。如果您指定多个筛选条件，则 Contributor Insights 会使用逻辑 AND 运算符对它们进行评估。您可以使用此选项来筛掉搜索中不相关的日志事件，也可以使用它选择单个贡献者来分析其行为。  
数组中的每个成员必须包含一个 `Match` 字段和一个指示要使用的匹配运算符类型的字段。  
`Match` 字段指定要在筛选条件中评估的日志字段。使用 JSON 属性格式表示法指定日志字段。  
匹配的运算符字段必须是下列项目之一：`In`、`NotIn`、`StartsWith`、`GreaterThan`、`LessThan`、`EqualTo`、`NotEqualTo` 或 `IsPresent`。如果运算符字段为 `In`、`NotIn` 或 `StartsWith`，则它后跟一个要检查的字符串值数组。Contributor Insights 使用 OR 运算符评估字符串值的数组。该数组可以包含最多 10 个字符串值。  
如果运算符字段为 `GreaterThan`、`LessThan`、`EqualTo` 或 `NotEqualTo`，则它后跟要比较的单个数值。  
如果运算符字段为 `IsPresent`，则它后跟 `true` 或 `false`。此运算符将根据日志事件中是否存在指定的日志字段来匹配日志事件。`isPresent` 仅使用 JSON 属性的叶节点中的值。例如，查找 `c-count` 的匹配项的筛选条件不会返回具有值 `details.c-count.c1` 的日志事件。  
有关四个筛选条件示例，请参阅以下内容:  

```
{"Match": "$.httpMethod", "In": [ "PUT", ] }
{"Match": "$.StatusCode", "EqualTo": 200 }
{"Match": "$.BytesReceived", "GreaterThan": 10000}
{"Match": "$.eventSource", "StartsWith": [ "ec2", "ecs" ] }
```

AggregateOn  
 有效值为 `Count` 和 `Sum`。指定是基于出现次数，还是基于 `ValueOf` 字段中指定的字段值的总和来聚合报告。

**JSON 属性格式表示法**

`Keys`、`ValueOf` 和 `Match` 字段遵循带点符号的 JSON 属性格式，其中 `$` 表示 JSON 对象的根。这之后是句点，然后是带子属性名称的字母数字字符串。支持多个属性级别。

字符串的第一个字符只能是 A-Z 或 a-z。字符串的后续字符可以是 A-Z、a-z 或 0-9。

以下列表显示了 JSON 属性格式的有效示例：

```
$.userAgent
$.endpoints[0]
$.users[1].name
$.requestParameters.instanceId
```

**CLF 日志规则中的其他字段**

常用日志格式 (CLF) 日志事件不像 JSON 那样具有字段的名称。要提供用于 Contributor Insights 规则的字段，CLF 日志事件可被视为具有从 `1` 开始的索引的数组。您可以将第一个字段指定为 **"1"**，将第二个字段指定为 **"2"**，以此类推。

要使 CLF 日志的规则更易于读取，可以使用 `Fields`。这可让您为 CLF 字段位置提供命名别名。例如，您可以指定位置“4”为 IP 地址。指定后，`IpAddress` 可用作规则中的 `Keys`、`ValueOf` 和 `Filters` 中的属性。

以下是使用 `Fields` 字段的 CLF 日志规则的示例。

```
{
    "Schema": {
        "Name": "CloudWatchLogRule",
        "Version": 1
    },
    "LogGroupNames": [
        "API-Gateway-Access-Logs*"
    ],
    "LogFormat": "CLF",
    "Fields": {
        "4": "IpAddress",
        "7": "StatusCode"
    },
    "Contribution": {
        "Keys": [
            "IpAddress"
        ],
        "Filters": [
            {
                "Match": "StatusCode",
                "EqualTo": 200
            }
        ]
    },
    "AggregateOn": "Count"
}
```