# 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)을 참조하세요.

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*`를 지정하여 111122223333에 이름이 `GroupNamePrefix`로 시작하는 미국 서부(캘리포니아 북부)의 모든 로그 그룹을 지정할 수도 있습니다.  
부분 AWS 계정 ID를 와일드 카드가 있는 접두사로 지정할 수 없습니다.  
로그 그룹 ARN과 함께 와일드카드를 사용할 때는 주의해야 합니다. 규칙과 일치하는 각 로그 이벤트에 대해 요금이 발생합니다. 의도한 것보다 많은 로그 그룹을 실수로 검색하면 예기치 않은 요금이 발생할 수 있습니다. 자세한 내용은 [Amazon CloudWatch 요금](https://aws.amazon.com/cloudwatch/pricing)을 참조하세요.

LogFormat  
 유효 값은 `JSON` 및 `CLF`입니다.

Contribution  
 이 객체에는 최대 4개의 멤버가 있는 `Keys` 배열, 선택적으로 단일 `ValueOf` 및 선택적으로 최대 4개의 `Filters`가 있는 배열이 포함됩니다.

키  
 기고자를 분류하는 측정기준으로 사용되는 최대 4개의 로그 필드의 배열입니다. 두 개 이상의 키를 입력하면 키에 대한 각각의 고유한 값 조합이 고유한 기고자로 계산됩니다. 필드는 JSON 속성 형식 표기법을 사용하여 지정해야 합니다.

ValueOf  
 (선택 사항) `Sum`을 `AggregateOn`의 값으로 지정하는 경우에만 이 옵션을 지정합니다. `ValueOf`는 숫자 값을 갖는 로그 필드를 지정합니다. 이 유형의 규칙에서 기고자 순위는 로그 항목에서의 발생 횟수 대신 이 필드 값의 합계로 결정됩니다. 예를 들어 기고자를 일정 기간 동안 총 `BytesSent`로 정렬하려는 경우 `ValueOf`를 `BytesSent`로 설정하고 `AggregateOn`에 `Sum`을 지정합니다.

필터  
 보고서에 포함된 로그 이벤트의 범위를 좁히기 위해 최대 4개의 필터가 있는 배열을 지정합니다. 여러 필터를 지정하면 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"
}
```