Amazon CloudWatch Logs
사용 설명서

필터 및 패턴 구문

지표 필터를 사용하여 로그 이벤트에서 일치하는 단어, 구문 또는 값을 검색할 수 있습니다. 지표 필터가 로그 이벤트에서 단어, 구문 또는 값 중 하나를 찾으면 CloudWatch 지표의 값을 증가시킬 수 있습니다. 예를 들어 로그 이벤트에서 지표 필터를 생성하여 ERROR라는 단어를 검색하고 출현 횟수를 계산할 수 있습니다.

지표 필터는 웹 요청에 대한 지연 시간과 같이 공백으로 구분된 로그 이벤트에서도 숫자 값을 추출할 수 있습니다. 다음 예제에서 로그로부터 추출된 실제 숫자 값만큼 지표 값을 증가시킬 수 있습니다.

또한 조건 연산자 및 와일드카드를 사용하여 정확히 일치되는 값을 찾을 수도 있습니다. 지표 필터를 생성하기 전에 CloudWatch 콘솔에서 검색 패턴을 테스트할 수 있습니다. 아래 단원에는 지표 필터 구문이 보다 자세하게 설명되어 있습니다.

로그 이벤트에서 일치하는 단어 검색

로그 이벤트에서 단어를 검색하려면 이 단어를 지표 필터 패턴으로 사용합니다. 지표 필터 패턴에 여러 개의 단어를 지정할 수 있지만, 모든 단어들은 일치 항목이 될 수 있도록 로그 이벤트에 나타나야 합니다. 지표 필터는 대소문자를 구분합니다.

영숫자나 밑줄 이외의 문자가 포함된 지표 필터 단어는 큰따옴표("") 안에 위치해야 합니다.

단어를 제외하려면 단어 앞에 마이너스 부호(-)를 붙입니다.

예제 1: 모든 이벤트와 일치

"" 필터 패턴은 모든 로그 이벤트와 일치합니다.

예제 2: 단일 단어

"ERROR" 필터 패턴은 다음과 같이 이 단어를 포함하는 로그 이벤트 메시지와 일치합니다.

  • [ERROR] 치명적인 예외가 발생

  • ERRORCODE: -1를 통해 종료

예제 3: 단어 포함 및 제외

앞의 예제에서 필터 패턴을 "ERROR" - "Exiting"으로 변경하면 "Exiting with ERRORCODE: -1"라는 로그 이벤트 메시지가 제외가 됩니다.

예제 4: 여러 단어

"ERROR Exception" 필터 패턴은 다음과 같이 두 단어를 모두 포함하는 로그 이벤트 메시지와 일치합니다.

  • [ERROR] IllegalArgumentException이 발생

  • [ERROR] 처리되지 않은 예외

"Failed to process the request" 필터 패턴은 다음과 같이 모든 단어를 모두 포함하는 로그 이벤트 메시지와 일치합니다.

  • [WARN] 요청 처리에 실패

  • [ERROR] 지속이 불가능: 요청 처리에 실패

OR 패턴 일치

OR 패턴 일치를 사용하여 텍스트 기반 필터에서 용어를 일치시킬 수 있습니다. OR에는 물음표(예: ?term)를 사용합니다.

아래의 세 가지 로그 이벤트 예를 살펴보십시오. ERROR는 예시 1, 2와 일치합니다. ?ERROR ?WARN은 예시 1, 2, 3과 일치하는데, 이들 예시에는 모두 ERROR나 WARN이라는 단어가 포함되어 있기 때문입니다. ERROR WARN은 예시 1과만 일치하는데, 예시 1이 두 단어를 모두 포함하는 유일한 예시이기 때문입니다. ERROR -WARN은 예시 2와 일치하는데, 예시 2는 ERROR를 포함하고 WARN을 포함하지 않는 문자열과 일치하기 때문입니다.

  1. ERROR WARN message

  2. ERROR message

  3. WARN message

공백으로 구분되는 필터에서 OR 패턴 일치를 사용하여 용어를 일치시킬 수 있습니다. 공백으로 구분되는 필터를 사용하는 경우 w1은 로그 이벤트의 첫 번째 단어를, w2는 두 번째 단어를 나타내는 식입니다. 아래의 패턴 예제에서, ERROR가 첫 번째 단어이기 때문에 [w1=ERROR, w2]는 패턴 2와 일치하고, [w1=ERROR || w1=WARN, w2]는 패턴 2 및 3과 일치하고, [w1!=ERROR&&w1!=WARN, w2]는 ERROR와 WARN이 모두 있는 줄(패턴 1)과 일치합니다.

  1. ERROR WARN 메시지

  2. ERROR 메시지

  3. WARN 메시지

공백으로 JSON 필터에서 OR 패턴 일치를 사용하여 용어를 일치시킬 수 있습니다. 아래의 패턴 예제에서, {$.foo = bar}는 패턴 1과 일치하고, {$.foo = baz }는 패턴 2와 일치하고, {$.foo = bar || $.foo = baz }는 패턴 1 및 2와 일치합니다.

  1. {"foo": "bar"}

  2. {"foo": "baz"}

JSON 로그 이벤트에서 일치하는 단어 검색

JSON 로그 이벤트에서 값을 추출할 수 있습니다. JSON 로그 이벤트에서 값을 추출하려면 문자열 기반의 지표 필터를 생성해야 합니다. 유효숫자 표기법이 포함된 문자열은 지원되지 않습니다. JSON 로그 이벤트 데이터의 항목들은 지표 필터와 정확하게 일치해야 합니다. 다음을 나타내기 위해 JSON 로그 이벤트에 지표 필터를 생성하고 싶을 수 있습니다.

  • 특정 이벤트가 발생합니다. 예를 들어 eventName은 "UpdateTrail"입니다.

  • IP는 알려진 서브넷 밖에 있습니다. 예를 들어 sourceIPAddress는 알려진 서브넷 범위에 있지 않습니다.

  • 기타 조건들이 두 개 이상 결합되면 true입니다. 예를 들어 eventName은 "UpdateTrail"이고 recipientAccountId는 123456789012입니다.

지표 필터를 사용하여 JSON 로그 이벤트에서 값을 추출

지표 필터를 사용하여 JSON 로그 이벤트에서 값을 추출할 수 있습니다. 지표 필터는 수신 로그를 확인하여 로그 데이터에서 일치가 발견되면 숫자 값을 수정합니다. 지표 필터를 생성할 때 로그에서 일치하는 텍스트가 발견될 때마다 개수만 증가시킬 수도 있고 로그로부터 숫자 값을 추출하여 지표 값을 이 값만큼 증가시킬 수도 있습니다.

지표 필터를 사용한 JSON 단어 일치

JSON 로그 이벤트에 대한 지표 필터 구문은 다음 형식을 사용합니다.

{ SELECTOR EQUALITY_OPERATOR STRING }

지표 필터를 중괄호({ })로 묶어서 이것이 JSON 표현식임을 나타내야 합니다. 지표 필터에는 다음 요소들이 포함되어 있습니다.

SELECTOR

확인할 JSON 속성을 지정합니다. 속성 선택기는 JSON의 루트를 나타내기 위해 항상 달러 문자($)로 시작됩니다. 속성 선택기는 '-' 및 '_' 문자도 지원하는 영숫자 문자열입니다. 어레이 요소들은 [NUMBER] 구문으로 표시가 되며 하나의 속성을 따라야 합니다. 예를 들면 $.eventId, $.users[0], $.users[0].id, $.requestParameters.instanceId와 같습니다.

EQUALITY_OPERATOR

= 또는 !=가 가능합니다.

STRING

따옴표가 있거나 없는 문자열. '*' 와일드카드 문자를 사용하여 검색 단어의 텍스트나 검색 단어 앞뒤의 텍스트가 일치하는 것을 검색할 수 있습니다. 예를 들어 *EventPutEventGetEvent와 일치하게 됩니다. Event*EventIdEventName과 일치하게 됩니다. Ev*ent는 실제 문자열 Ev*ent하고만 일치하게 됩니다. 영숫자 문자로만 이루어진 문자열에는 따옴표를 붙일 필요가 없습니다. 유니코드와 ‘@,‘ ‘$,' ‘\,' 같은 다른 문자들을 가진 문자열이 유효하려면 큰 따옴표로 묶어야 합니다.

JSON 지표 필터 예제

다음은 JSON의 한 예입니다.

{ "eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ { "name": "a", "id": 1 }, { "name": "b", "id": 2 } ], "SomeObject": null, "ThisFlag": true }

다음 필터들이 일치합니다.

{ $.eventType = "UpdateTrail" }

이벤트 유형이 UpdateTrail인 경우에 대한 필터.

{ $.sourceIPAddress != 123.123.* }

IP 주소가 서브넷 123.123 접두사 밖에 있는 경우에 대한 필터.

{ $.arrayKey[0] = "value" }

arrayKey의 첫 항목이 "value"인 경우에 대한 필터. arrayKey가 어레이가 아니면 false가 됩니다.

{ $.objectList[1].id = 2 }

objectList의 두 번째 항목이 id = 2라는 속성을 가지고 있는 경우에 대한 필터. objectList가 어레이가 아니면 false가 됩니다. objectList의 항목들이 개체가 아니거나 id 속성을 가지고 있지 않으면 false가 됩니다.

{ $.SomeObject IS NULL }

SomeObject가 null로 설정 중인 경우에 대한 필터. 지정된 개체가 null로 설정된 경우에만 true가 됩니다.

{ $.SomeOtherObject NOT EXISTS }

SomeOtherObject가 존재하지 않는 경우에 대한 필터. 지정된 개체가 로그 데이터에 존재하지 않는 경우에만 true가 됩니다.

{ $.ThisFlag IS TRUE }

ThisFlag가 TRUE인 경우에 대한 필터. FALSE 값을 확인하는 부울 필터에도 적용됩니다.

JSON 복합 조건식

OR (||) 및 AND (&&)를 사용하여 여러 조건식을 하나의 복합 표현식으로 결합할 수 있습니다. 괄호가 허용되며 구문은 () > && > ||라는 연산의 표준 순서를 따릅니다.

{ "user": { "id": 1, "email": "John.Stiles@example.com" }, "users": [ { "id": 2, "email": "John.Doe@example.com" }, { "id": 3, "email": "Jane.Doe@example.com" } ], "actions": [ "GET", "PUT", "DELETE" ], "coordinates": [ [0, 1, 2], [4, 5, 6], [7, 8, 9] ] }
예제
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }

위의 JSON과 일치합니다.

{ ($.user.id = 2 && $.users[0].email = "nonmatch") || $.actions[2] = "GET" }

위의 JSON과 일치하지 않습니다.

{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch && $.actions[2] = nomatch }

위의 JSON과 일치합니다.

{ ($.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch) && $.actions[2] = nomatch }

위의 JSON과 일치하지 않습니다.

JSON 특별 고려 사항

SELECTOR는 JSON에서 값 노드(문자열이나 숫자)를 가리켜야 합니다. 어레이나 개체를 가리킬 경우에는 로그 형식이 해당 필터와 일치하지 않기 때문에 필터가 적용되지 않습니다. 예를 들어 .{$.users = 1} 및 {$.users != 1} 모두 사용자가 어레이인 로그 이벤트와 일치하지 않게 됩니다.

{ "users": [1, 2, 3] }
숫자 비교식

지표 필터 구문은 숫자 비교식에서 정밀 매칭을 지원합니다. <, >, >=, <=, =, != 등의 숫자 비교식이 지원됩니다.

숫자 필터는 다음에 대한 구문을 가집니다.

{ SELECTOR NUMERIC_OPERATOR NUMBER }

지표 필터를 중괄호({ })로 묶어서 이것이 JSON 표현식임을 나타내야 합니다. 지표 필터에는 다음 요소들이 포함되어 있습니다.

SELECTOR

확인할 JSON 속성을 지정합니다. 속성 선택기는 JSON의 루트를 나타내기 위해 항상 달러 문자($)로 시작됩니다. 속성 선택기는 '-' 및 '_' 문자도 지원하는 영숫자 문자열입니다. 어레이 요소들은 [NUMBER] 구문으로 표시가 되며 하나의 속성을 따라야 합니다. $.latency, $.numbers[0], $.errorCode, $.processes[4].averageRuntime 등이 그 예입니다.

NUMERIC_OPERATOR

=, !=, <, >, <= 또는 >= 중 하나일 수 있습니다.

숫자

+ 또는 - 기호 옵션이 있는 정수, + 또는 - 기호 옵션이 있는 10진수, 유효숫자 표기법을 따르는 숫자(+ 또는 - 기호 옵션이 있는 정수 또는 10진수, 'e'가 뒤에 따라 나오는 숫자, + 또는 - 기호 옵션이 있는 정수가 뒤에 따라 나오는 숫자).

예제:

{ $.latency >= 500 } { $.numbers[0] < 10e3 } { $.numbers[0] < 10e-3 } { $.processes[4].averageRuntime <= 55.5 } { $.errorCode = 400 } { $.errorCode != 500 } { $.latency > +1000 }

지표 필터를 사용하여 공백으로 구분된 로그 이벤트에서 값을 추출

지표 필터를 사용하여 공백으로 구분된 로그 이벤트에서 값을 추출할 수 있습니다. 대괄호 [] 또는 큰 따옴표("")로 묶인 문자들은 단일 필드로 처리가 됩니다. 예:

127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] "GET /apache_pb.gif HTTP/1.0" 200 1534 127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] "GET /apache_pb.gif HTTP/1.0" 500 5324 127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] "GET /apache_pb.gif HTTP/1.0" 200 4355

공백으로 구분된 이벤트를 구문 분석하는 지표 필터 패턴을 지정하려면 이름이 쉼표로 구분이 되고 전체 패턴이 대괄호로 묶여 있도록 필드를 지정해야 합니다. 예를 들면 [ip, user, username, timestamp, request, status_code, bytes]와 같이 말입니다.

필드 수를 모르는 경우에는 줄임표(…)를 이용해 간편 알림을 사용할 수 있습니다. 예:

[..., status_code, bytes] [ip, user, ..., status_code, bytes] [ip, user, ...]

모든 조건이 일치하는 로그 이벤트만 필터와 일치가 되도록 하기 위해 필드에 조건을 추가할 수도 있습니다. 예:

[ip, user, username, timestamp, request, status_code, bytes > 1000] [ip, user, username, timestamp, request, status_code = 200, bytes] [ip, user, username, timestamp, request, status_code = 4*, bytes] [ip, user, username, timestamp, request = *html*, status_code = 4*, bytes]

다음 예제와 같이 &&를 AND 연산자로 사용할 수 있습니다.

[ip, user, username, timestamp, request, status_code = 4* && bytes > 1000] [ip, user, username, timestamp, request, status_code = 4* && status_code != 403, bytes]

CloudWatch Logs는 문자열과 숫자 조건 필드를 모두 지원합니다. 문자열 필드에서는 = 또는 != 연산자를 별표(*)와 함께 사용할 수 있습니다.

숫자 필드에서는 >, <, >=, <=, = 및 != 연산자를 사용할 수 있습니다.

공백으로 구분된 필터를 사용하는 경우에는 추출된 필드가 공백으로 구분된 필드의 이름(필터에 표현)과 각 필드의 값에 매핑됩니다. 공백으로 구분된 필터를 사용하지 않는 경우에는 필드가 비게 됩니다.

필터 예제:

[..., request=*.html*, status_code=4*,]

필터를 위한 로그 이벤트 예제:

127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /index.html HTTP/1.0\" 404 1534

로그 이벤트 및 필터 패턴을 위해 추출된 필드:

{ "$status_code": "404", "$request": "GET /products/index.html HTTP/1.0", "$7": "1534", "$4": "10/Oct/2000:13:25:15 -0700", "$3": "frank", "$2": "-", "$1": "127.0.0.1" }

일치가 발견될 경우 지표 값 변경 방법 설정

지표 필터는 로그 이벤트에서 일치하는 단어, 구문 또는 값 중 하나를 발견할 경우 지표 값에 지정된 값만큼 CloudWatch 지표에서 개수를 증가시킵니다. 지표 값은 집계되며 1분마다 보고됩니다.

1분 기간 동안 로그가 수집되었지만 일치가 발견되지 않은 경우 기본값(있는 경우)으로 지정된 값이 보고됩니다. 하지만 1분 기간 동안 로그 이벤트가 수집되지 않은 경우에는 아무 값도 보고되지 않습니다.

기본값을 지정할 경우 값이 0이라 해도 데이터가 보다 자주 보고되도록 하므로, 일차가 발견되지 않을 경우 지표가 불규칙해지는 것을 방지할 수 있습니다.

예를 들어 1분마다 두 개의 레코드를 게시하는 로그 그룹이 있고, 지표 값은 1, 기본값은 0이라고 가정해 보겠습니다. 처음 1분 동안 두 로그 레코드 모두에서 일치가 발견될 경우 이 기간의 지표 값은 2입니다. 두 번째 1분 동안 게시된 로그 레코드에서 일치가 발견되지 않을 경우 두 로그 레코드에 기본값 0이 사용되며 이 기간의 지표 값은 0입니다.

기본값을 지정하지 않을 경우 패턴 일치가 발견되지 않은 기간 동안에는 데이터가 보고되지 않습니다.

로그 항목에서 발견된 수치 값 게시

단순히 로그에서 발견된 일치 항목의 수를 계산하는 대신 지표 필터를 사용하여 로그에서 발견된 수치 값을 기반으로 값을 게시할 수 있습니다. 다음 절차는 JSON 요청 metricFilter: { $.latency = * } metricValue: $.latency에서 발견된 지연 시간이 포함된 지표를 게시하는 방법을 보여줍니다.

JSON 요청에서 지연 시간이 포함된 지표를 게시하려면

  1. https://console.aws.amazon.com/cloudwatch/에서 CloudWatch 콘솔을 엽니다.

  2. 탐색 창에서 로그를 선택합니다.

  3. 콘텐츠 창에서 로그 그룹을 선택한 다음 지표 필터 생성을 선택합니다.

  4. 로그 지표 필터 정의 화면의 필터 패턴{ $.latency = * }를 입력하고 지표 할당을 선택합니다.

  5. 지표 필터 생성 및 지표 할당 화면에서 고급 지표 설정 표시를 선택합니다.

  6. 지표 이름myMetric을 입력합니다.

  7. 지표 값$.latency를 입력합니다.

  8. 기본값에 0을 입력한 후 필터 생성을 선택합니다. 기본값을 지정할 경우 로그 이벤트가 발생하지 않는 기간에도 데이터가 보고되므로 때때로 데이터가 존재하지 않아 지표가 불규칙해지는 것을 방지할 수 있습니다.

아래 로그 이벤트는 필터 생성에 뒤이어 myMetric 지표에 50이라는 값을 게시하게 됩니다.

{ "latency": 50, "requestType": "GET" }