# 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 ルールのフィールド

Schema  
 CloudWatch Logs データを分析するルールの `Schema` の値は、常に `{"Name": "CloudWatchLogRule", "Version": 1}` である必要があります。

LogGroupNames  
 文字列の配列です。配列の各要素で、必要に応じて文字列の最後に `*` を使用して、そのプレフィックスで始まる名前を持つすべてのロググループを含めることができます。  
ロググループ名でワイルドカードを使用するときはご注意ください。ルールと一致するログイベントごとに料金が発生します。誤って意図したより多くのロググループを検索すると、予期しない料金が発生することがあります。詳細については、[Amazon CloudWatch 料金表](https://aws.amazon.com/cloudwatch/pricing)をご覧ください。

LogGroupARNs  
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*` を指定すると、名前が `GroupNamePrefix` で始まる米国西部 (北カリフォルニア) 内の 111122223333 のロググループすべてを指定することもできます。  
AWS アカウント ID の一部を、ワイルドカードが付いたプレフィックスとして指定することはできません。  
ロググループ ARN でワイルドカードを使用するときはご注意ください。ルールと一致するログイベントごとに料金が発生します。誤って意図したより多くのロググループを検索すると、予期しない料金が発生することがあります。詳細については、[Amazon CloudWatch 料金表](https://aws.amazon.com/cloudwatch/pricing)をご覧ください。

LogFormat  
 有効な値は、`JSON` および `CLF` です。

寄与度  
 このオブジェクトには、最大で 4 つのメンバーがある `Keys` 配列、オプションで 1 つの `ValueOf`、およびオプションで最大 4 つの `Filters` がある配列が含まれます。

キー  
 最大 4 つのログフィールドの配列であり、コントリビューターを分類するためのディメンションとして使用されます。複数のキーを入力すると、これらのキーの一意な値の組み合わせごとに一意のコントリビューターとしてカウントされます。フィールドは、JSON プロパティフォーマット表記を使用して指定する必要があります。

ValueOf  
 (オプション) `Sum` を `AggregateOn` の値として指定する場合のみこれを指定します。`ValueOf` は数値を持つログフィールドを指定します。このタイプのルールでは、コントリビューターはログエントリでの出現回数ではなく、このフィールドの値の合計によってランク付けされます。たとえば、コントリビューターを特定期間にわたる合計 `BytesSent` でソートする場合は、`ValueOf` を `BytesSent` に設定し、`Sum` を `AggregateOn` に指定します。

フィルター  
 最大 4 つのフィルターの配列を指定し、レポートに含まれるログイベントを絞り込みます。複数のフィルターを指定した場合、Contributor Insights は論理 AND 演算子で評価します。これを使用して、検索から無関係なログイベントを除外したり、1 つのコントリビューターを選択して動作を分析したりできます。  
配列内の各メンバーは、`Match` フィールドと、使用する一致する演算子のタイプを示すフィールドを含める必要があります。  
`Match` フィールドは、フィルターで評価するログフィールドを指定します。ログフィールドは JSON プロパティフォーマット表記を使用して指定されます。  
一致する演算子フィールドは、`In`、`NotIn`、`StartsWith`、`GreaterThan`、`LessThan`、`EqualTo`、`NotEqualTo`、または `IsPresent` のいずれかである必要があります。演算子フィールドが`In`、`NotIn`、または `StartsWith` である場合、チェックする文字列値の配列が続きます。Contributor Insights は文字列値の配列を OR 演算子で評価します。配列には最大で 10 個の文字列値を含めることができます。  
演算子フィールドが `GreaterThan`、`LessThan`、`EqualTo`、または `NotEqualTo` である場合、比較する 1 つの数値が続きます。  
演算子フィールドが `IsPresent` である場合、`true` または `false` が続きます。この演算子は、指定したログフィールドがログイベント内にあるかどうかに基づいて、ログイベントを照合します。`isPresent` は JSON プロパティの葉ノードの値に対してのみ機能します。たとえば、`c-count` との一致を検索するフィルターは、`details.c-count.c1` を値とするログイベントを評価しません。  
次の 4 つのフィルターの例を参照してください。  

```
{"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 ログのルールの追加フィールド**

Common Log Format (CLF) ログイベントには、JSON にはあるようなフィールドの名前はありません。Contributor Insights ルールで使用するフィールドを提供するために、CLF ログイベントを `1` で始まるインデックスを持つ配列として扱うことができます。最初のフィールドを **"1"** として指定し、2 番目のフィールドを **"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"
}
```