# 조건부 처리를 위한 표현식 구문
<a name="conditional-processing"></a>

조건부 처리를 지원하는 CloudWatch 파이프라인 프로세서는 표현식을 포함하는 `when` 파라미터를 수락합니다. 표현식이 true로 평가되면 프로세서 또는 항목이 실행됩니다. 표현식은 중첩된 필드 액세스에 점 표기법(`.`)을 사용합니다. 예를 들어, `user.role`는 `user` 객체 내의 `role` 필드에 액세스합니다. 조건부 처리를 지원하는 프로세서와 특정 파라미터에 대한 자세한 내용은 [CloudWatch 파이프라인 프로세서](pipeline-processors.md) 섹션을 참조하세요. 구성 예제는 [일반적인 프로세서 사용 사례](processor-examples.md) 섹션을 참조하십시오.

## 프로세서 수준 및 항목 수준 조건
<a name="conditional-levels"></a>

프로세서에 따라 `when` 조건을 적용할 수 있는 두 가지 수준이 있습니다.

프로세서 수준 `when`(외부 수준)  
프로세서 구성의 최상위에 배치된 `when`. 표현식이 false로 평가되면 전체 프로세서를 건너뛰고 해당 프로세서 내에서 실행되는 작업이 없습니다. 조건부 처리를 지원하는 모든 프로세서가 이 수준을 지원합니다.  

**Example 프로세서 수준 조건 - 전체 프로세서 건너뛰기**  
다음 `delete_entries` 프로세서는 환경이 프로덕션 또는 스테이징인 경우에만 실행됩니다. 조건이 false이면 어떤 키도 삭제되지 않습니다.  

```
processor:
  - delete_entries:
      with_keys: ["password", "api_key", "ssn"]
      when: "environment in {'prod', 'staging'}"
```

항목 수준 `when`(각 항목 내)  
`entries` 배열의 개별 항목 내에 배치된 `when`. 각 항목은 독립적으로 평가됩니다. 표현식이 false인 경우 해당 특정 항목만 건너뛰고 동일한 프로세서의 다른 항목은 계속 실행됩니다. `entries` 배열이 있는 프로세서만 이 수준을 지원합니다(예: `add_entries`, `copy_values`, `rename_keys`, `move_keys`, `extract_value`, `substitute_string`).  

**Example 항목 수준 조건 - 개별 항목 건너뛰기**  
다음 `add_entries` 프로세서는 각 항목의 조건에 따라 서로 다른 키를 추가합니다. 첫 번째 항목에는 로그 수준이 ERROR인 경우에만 `severity`가 추가됩니다. 두 번째 항목에는 조건이 없으므로 항상 `processed`가 추가됩니다.  

```
processor:
  - add_entries:
      entries:
        - key: "severity"
          value: "high"
          when: "log.level == 'ERROR'"
        - key: "processed"
          value: "true"
```

두 수준을 모두 지원하는 프로세서는 함께 사용할 수 있습니다. 둘 다 지정되면 프로세서 수준 조건이 먼저 평가됩니다. false인 경우 전체 프로세서를 건너뛰고 항목 수준 조건은 평가되지 않습니다.

**Example 두 수준 결합**  
프로세서 수준 `when`을 통해 전체 프로세서가 프로덕션 트래픽에 대해서만 실행됩니다. 이 안에서 각 항목에는 추가되는 키를 제어하는 고유한 조건이 있습니다.  

```
processor:
  - add_entries:
      when: "environment == 'prod'"
      entries:
        - key: "alert_level"
          value: "critical"
          when: "log.level == 'ERROR'"
        - key: "alert_level"
          value: "warning"
          when: "log.level == 'WARN'"
```

어떤 프로세서가 어떤 수준을 지원하는지 보여주는 표는 아래에 있는 [조건부 처리 지원](#conditional-support) 섹션을 참조하세요.

**`when_else`가 포함된 폴백**  
항목 수준 조건을 지원하는 프로세서도 `when_else`를 지원합니다. `when_else`가 포함된 항목은 폴백 역할을 합니다. 동일한 프로세서의 다른 `when` 조건이 일치하지 않는 경우에만 실행됩니다. 고려해야 할 `when` 조건 집합을 식별하기 위해 `when_else`에 제공되는 표현식 값이지만, 항목 자체는 해당 조건이 모두 false로 평가되는지 여부에 따라서만 실행됩니다. 명시적 부정 확인은 없습니다. 일치된 다른 `when`이 없는 경우 항목이 실행됩니다.

**Example when\$1else가 포함된 폴백 항목**  
첫 번째 항목에는 로그 수준이 ERROR인 경우 실행됩니다. 두 번째 항목은 `when_else`를 사용하고 첫 번째 항목의 `when` 조건이 일치하지 않았을 때만 실행됩니다(즉, 로그 수준이 ERROR와는 다른 값임).  

```
processor:
  - add_entries:
      entries:
        - key: "alert_level"
          value: "critical"
          when: "log.level == 'ERROR'"
        - key: "alert_level"
          value: "info"
          when_else: "log.level == 'ERROR'"
```

## 조건부 처리 지원
<a name="conditional-support"></a>

다음 표에는 조건부 처리를 지원하는 프로세서와 수준이 나와 있습니다.


**프로세서 조건부 지원**  

| 처리자 | 조건부 지원 | 수준 | 
| --- | --- | --- | 
| add\$1entries | 예 | 프로세서 및 항목 | 
| copy\$1values | 예 | 프로세서 및 항목 | 
| delete\$1entries | 예 | 처리자 | 
| move\$1keys | 예 | 프로세서 및 항목 | 
| 평면화 | 예 | 처리자 | 
| lowercase\$1string | 예 | 처리자 | 
| uppercase\$1string | 예 | 처리자 | 
| trim\$1string | 예 | 처리자 | 
| substitute\$1string | 예 | 프로세서 및 항목 | 
| truncate | 예 | 처리자 | 
| extract\$1value | 예 | 프로세서 및 항목 | 
| convert\$1entry\$1type | 예 | 처리자 | 
| 날짜 | 예 | 처리자 | 
| dissect | 예 | 처리자 | 
| list\$1to\$1map | 예 | 처리자 | 
| rename\$1keys | 예 | 프로세서 및 항목 | 
| select\$1entries | 예 | 처리자 | 
| translate | 예 | 처리자 | 
| grok | 예 | 처리자 | 
| drop\$1events | 예 | 프로세서(필수) | 
| OCSF, CSV, JSON, KeyValue, WAF, Postgres, CloudFront, VPC, Route53 | 아니요 | — | 

## 연산자
<a name="expression-operators"></a>


**지원되는 연산자**  

| 카테고리 | 연산자 | 예제 | 
| --- | --- | --- | 
| 관계형 | <, <=, >, >= | status\$1code >= 200 and status\$1code < 300 | 
| Equality | ==, \$1= | log.level == "ERROR" | 
| 조건부 | and, or, not | log.level == "ERROR" or log.level == "FATAL" | 
| Arithmetic | \$1, -, \$1, / | response\$1time \$1 1000 > 5000 | 
| 집합 소속 | in, not in | environment in \$1"prod", "staging", "preprod"\$1 | 
| 정규식 일치 | =\$1, \$1\$1 | message =\$1 "^ERROR.\$1timeout" | 

## 함수
<a name="expression-functions"></a>

`length(value)`  
문자열 또는 배열의 길이를 반환합니다. 예시: `length(message) > 100`

`contains(value, search)`  
문자열에 하위 문자열이 포함되어 있는지 또는 배열에 요소가 포함되어 있는지 확인합니다. 예시: `contains(message, "error")`

`startsWith(field, prefix)`  
문자열이 지정된 접두사로 시작하는지 확인합니다. 예시: `startsWith(message, "ERROR")`

## 예제 표현식
<a name="expression-examples"></a>

```
log.level == "ERROR"
status_code >= 200 and status_code < 300
environment in {"prod", "staging", "preprod"}
message =~ "^ERROR.*timeout"
user.role == "admin" and user.permissions.write == true
length(message) > 100 and contains(message, "error")
(log.level == "ERROR" or log.level == "FATAL") and environment == "prod"
```

## 제한 사항
<a name="expression-limitations"></a>
+ 표현식 최대 길이는 256자입니다.
+ 파서 프로세서(Grok 제외)는 조건부 처리를 지원하지 않습니다. JSON, CSV, KeyValue, WAF, Postgres, CloudFront, VPC, Route53, OCSF 파서가 포함됩니다.
+ Grok 프로세서가 파이프라인에서 파서(첫 번째 프로세서)로 사용되고 해당 `when` 조건이 false로 평가되는 경우 전체 파이프라인이 해당 로그 이벤트에 대해 실행되지 않습니다.