View a markdown version of this page

조건부 처리를 위한 표현식 구문 - Amazon CloudWatch
프로세서 수준 및 항목 수준 조건조건부 처리 지원연산자함수예제 표현식제한 사항

조건부 처리를 위한 표현식 구문

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

프로세서 수준 및 항목 수준 조건

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

프로세서 수준 when(외부 수준)

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

예프로세서 수준 조건 - 전체 프로세서 건너뛰기

다음 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).

예항목 수준 조건 - 개별 항목 건너뛰기

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

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

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

예두 수준 결합

프로세서 수준 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'"

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

when_else가 포함된 폴백

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

예 when_else가 포함된 폴백 항목

첫 번째 항목에는 로그 수준이 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'"

조건부 처리 지원

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

프로세서 조건부 지원
처리자 조건부 지원 수준
add_entries예프로세서 및 항목
copy_values예프로세서 및 항목
delete_entries예처리자
move_keys예프로세서 및 항목
평면화예처리자
lowercase_string예처리자
uppercase_string예처리자
trim_string예처리자
substitute_string예프로세서 및 항목
truncate예처리자
extract_value예프로세서 및 항목
convert_entry_type예처리자
날짜예처리자
dissect예처리자
list_to_map예처리자
rename_keys예프로세서 및 항목
select_entries예처리자
translate예처리자
grok예처리자
drop_events예프로세서(필수)
OCSF, CSV, JSON, KeyValue, WAF, Postgres, CloudFront, VPC, Route53아니요—

연산자

지원되는 연산자
카테고리 연산자 예제
관계형 <, <=, >, >= status_code >= 200 and status_code < 300
Equality ==, != log.level == "ERROR"
조건부 and, or, not log.level == "ERROR" or log.level == "FATAL"
Arithmetic +, -, *, / response_time * 1000 > 5000
집합 소속 in, not in environment in {"prod", "staging", "preprod"}
정규식 일치 =~, !~ message =~ "^ERROR.*timeout"

함수

length(value)

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

contains(value, search)

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

startsWith(field, prefix)

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

예제 표현식

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"

제한 사항

  • 표현식 최대 길이는 256자입니다.

  • 파서 프로세서(Grok 제외)는 조건부 처리를 지원하지 않습니다. JSON, CSV, KeyValue, WAF, Postgres, CloudFront, VPC, Route53, OCSF 파서가 포함됩니다.

  • Grok 프로세서가 파이프라인에서 파서(첫 번째 프로세서)로 사용되고 해당 when 조건이 false로 평가되는 경우 전체 파이프라인이 해당 로그 이벤트에 대해 실행되지 않습니다.