CloudWatch の Contributor Insights ルール構文

{
    "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 料金表をご覧ください。

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 料金表をご覧ください。

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 フィールドで指定されたフィールドの値の合計に基づいてレポートを集計するかを指定します。

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

{
    "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"
}