CloudWatch Logs Insights 쿼리 구문
CloudWatch Logs Insights에서는 로그 그룹을 쿼리하는 데 사용할 수 있는 쿼리 언어를 지원합니다. 쿼리 구문은 일반 함수, 산술 및 비교 연산, 정규 표현식을 포함하되 이에 국한되지 않는 다양한 함수 및 연산을 지원합니다. 여러 쿼리 명령이 포함된 쿼리를 생성할 수 있습니다. UNIX 스타일 파이프 문자(|)를 사용하여 쿼리에서 쿼리 명령을 구분합니다. 쿼리 구문에 대한 자세한 내용은 지원되는 함수 및 연산을 참조하세요.
CloudWatch Logs Insights는 쿼리에서 주석 사용을 지원합니다. CloudWatch Logs Insights는 해시 기호(#)로 시작하는 줄을 무시합니다. CloudWatch Logs Insights는 많은 로그 유형의 필드를 자동으로 검색하고 @ 기호로 시작하는 필드를 생성합니다. CloudWatch Logs가 자동으로 생성하는 필드에 대한 자세한 내용은 Amazon CloudWatch 사용 설명서의 지원되는 로그 및 검색된 필드를 참조하세요.
CloudWatch Logs Insights 쿼리 명령
다음 표에는 CloudWatch Logs Insights에 대해 지원되는 쿼리 명령과 기본 예제가 나와 있습니다. 일반 쿼리 및 다른 로그 유형에 대한 쿼리 예제는 Amazon CloudWatch Logs 사용 설명서의 샘플 쿼리 섹션을 참조하세요.
명령 | 설명 | 예 |
---|---|---|
|
쿼리 결과에 표시할 필드를 지정합니다. 쿼리에서 이 명령을 두 번 이상 사용할 경우, 쿼리 결과에는 마지막으로 발생한 사용 중인 |
다음 예제 쿼리는
|
|
로그 이벤트에서 지정된 필드를 검색하고 표시합니다. 쿼리에 |
다음 예제에서는
다음 예제에서는 임시 필드
|
|
하나 이상의 조건을 기반으로 쿼리 결과를 필터링합니다. |
다음 예제에서는
다음 예제에서는 유사한 쿼리를 보여주지만, 쿼리 결과에 별도의 필드가 표시되지 않습니다. 대신, 쿼리 결과에는
다음 예제에서는
다음 예제에서는 필드
그 다음 예제에서는 필드
다음 예제에서는
이 마지막 예제에서는 값이 "foo", "bar" 또는 "1"인
|
|
로그 필드 값을 사용하여 집계 통계를 계산합니다.
|
다음 예제에서는
다음 예제에서는 시간당 발생한 예외 수를 계산합니다.
이 예제에서는 |
|
검색된 로그 이벤트를 정렬합니다. 오름차순( |
다음 예제에서는 반환되는 이벤트를
|
|
쿼리에서 반환되는 로그 이벤트 수를 지정합니다. 이 옵션을 사용하여 결과를 소수로 제한하여 관련 결과의 소집합을 볼 수 있습니다. 1,000에서 10,000 사이의 숫자와 제한을 지정하지 않으면 쿼리의 기본값은 최대 1,000개 행을 표시합니다. |
다음 예제에서는
|
|
로그 필드에서 데이터를 추출하고, 쿼리에서 추가로 처리할 수 있는 임시 필드를 하나 이상 생성합니다.
글로브 표현식의 경우 정규식을 슬래시(/)로 둘러쌉니다. 표현식에는 추출될 일치 스트링의 각 부분이 네임드 캡처링 그룹에 묶여있습니다. 네임드 캡처링 그룹의 예는 |
단일 로그 라인을 예로 사용합니다.
아래의 두 가지
단일 로그 라인을 예로 사용합니다.
다음 예제에서는 정규식을 사용하여 로그 필드
|
쿼리 명령 작업 지침
쿼리에서 이름이 지정되고 @
기호, 마침표(.
), 영숫자 이외의 문자를 포함하는 로그 필드는 반드시 백틱 키(`
)로 둘러싸야 합니다. 예를 들어, foo-bar
로그 필드는 영숫자가 아닌 문자인 하이픈(-
)을 포함하고 있기 때문에 백틱 키(`foo-bar`
)로 묶어야 합니다.
쿼리 결과에 표시하려는 필드를 보려면 display
명령을 사용합니다. display
명령은 사용자가 지정한 필드만 표시합니다. 쿼리에 여러 display
명령이 포함된 경우, 쿼리 결과는 마지막 display
명령에서 지정한 필드만 표시합니다.
as 키워드와 함께 fields
명령을 사용하면 로그 이벤트에 있는 필드 및 함수를 사용하는 임시 필드를 생성할 수 있습니다. 예를 들어, fields ispresent as isRes
는 쿼리의 나머지 부분에서 사용할 수 있는 isRes
라는 임시 필드를 생성합니다.
resolverArn
이 검색된 필드인지 여부에 따라 isRes
값은 0 또는 1이 됩니다. 쿼리에 fields
명령이 여러 개 포함되어 있는데 display
명령은 포함되지 않은 경우, fields
명령에 지정된 모든 필드가 표시됩니다.
필터 명령의 일치 항목 및 정규식
필터 명령은 정규 표현식 사용을 지원합니다. 비교 연산자(=
, !=
, <
, <=
, >
, >=
) 및 부울 연산자(and
, or
, not
)를 사용할 수 있습니다.
여기서는 사용자가 정규 표현식에 대해 잘 알고 있다고 가정합니다. CloudWatch Logs Insights는 여러 정규 표현식 매칭 라이브러리인 Hyperscan을 지원합니다. Hyperscan에 대한 자세한 내용은 Hyperscan 웹 사이트
in
키워드를 사용하여 설정된 멤버십을 테스트하고 배열의 요소를 확인할 수 있습니다. 배열에서 요소를 확인하려면 in
뒤에 해당 배열을 넣습니다. in
과 함께 부울 연산자 not
을 사용할 수 있습니다. in
을 사용하여 필드가 문자열과 일치하는 로그 이벤트를 반환하는 쿼리를 생성할 수 있습니다. 필드는 완전한 문자열이어야 합니다. 예를 들어, 다음 코드 조각은 in
을 사용하여 logGroup
필드가 완전한 문자열 example_group
인 로그 이벤트를 반환하는 쿼리를 보여줍니다.
fields @timestamp, @message | filter logGroup in ["example_group"]
키워드 구문 like
및 not like
를 사용하여 하위 문자열을 일치시킬 수 있습니다. 정규 표현식 연산자 =~
를 사용하여 하위 문자열을 일치시킬 수 있습니다. like
및 not like
로 하위 문자열을 일치시키려면, 일치해야 하는 하위 문자열을 큰따옴표 또는 작은따옴표로 둘러쌉니다. like
및 not like
와 함께 정규식 패턴을 사용할 수 있습니다. 하위 문자열을 정규식 연산자와 일치시키려면 원하는 하위 문자열을 슬래시로 둘러쌉니다. 다음 예제에는 filter
명령을 사용하여 하위 문자열을 일치시키는 방법을 보여주는 코드 조각이 포함되어 있습니다.
예: 하위 문자열 일치
다음 예제에서는 f1
에 단어 Exception이 포함된 모든 이벤트를 반환합니다. 세 예제 모두 대/소문자를 구별합니다.
첫 번째 예제에서는 like
를 사용하여 하위 문자열과 일치시킵니다.
fields f1, f2, f3 | filter f1 like "Exception"
두 번째 예제에서는 like
및 정규 표현식 패턴을 사용하여 하위 문자열을 일치시킵니다.
fields f1, f2, f3 | filter f1 like /Exception/
마지막 예제에서는 정규 표현식을 사용하여 하위 문자열을 일치시킵니다.
fields f1, f2, f3 | filter f1 =~ /Exception/
예: 와일드카드로 하위 문자열 일치
정규 표현식에서 별표 기호(*
)를 와일드카드로 사용하여 하위 문자열을 일치시킬 수 있습니다. 다음 예에서는 f1
에 문자 E로 시작하는 단어가 포함된 로그 이벤트를 반환합니다. 이 예제에서는 대/소문자를 구분합니다.
fields f1, f2, f3 | filter f3 like /E*/
별표 기호 앞에 마침표를 입력(.*)하여 가능한 한 많은 일치를 반환하는 탐욕적 수량자(Greedy Quantifier)를 생성할 수 있습니다.
예제: 일치 항목에서 하위 문자열 제외
다음 예제에서는 f1
에 단어 Exception이 포함되지 않은 모든 로그 이벤트를 반환하는 쿼리를 보여줍니다. 이 예제에서는 대/소문자를 구분합니다.
fields f1, f2, f3 | filter f1 not like "Exception"
예: 대/소문자를 구분하지 않는 패턴과 하위 문자열 일치
대/소문자를 구분하지 않는 하위 문자열을 like
및 정규 표현식을 사용하여 일치시킬 수 있습니다. 일치시키려는 하위 문자열 앞에 다음 파라미터(?i)를 입력합니다. 다음 예제에서는 f1
에 단어 Exception 또는 exception이 포함된 모든 로그 이벤트를 반환하는 쿼리를 보여줍니다.
fields f1, f2, f3 | filter f1 like /(?i)Exception/
쿼리에 별칭 사용
as
를 사용하여 쿼리에서 별칭을 하나 이상 생성할 수 있습니다. 별칭은 fields
, stats
및 sort
명령에서 지원됩니다.
로그 필드에 대한 별칭과 연산 및 함수의 결과에 대한 별칭을 생성할 수 있습니다.
예제
다음 예제는 쿼리 명령에서 별칭 사용을 보여줍니다.
fields abs(myField) as AbsoluteValuemyField, myField2
myField
의 절대값을 AbsoluteValuemyField
로 반환하고 필드 myField2
도 반환합니다.
stats avg(f1) as myAvgF1 | sort myAvgF1 desc
f1
의 값 평균을 myAvgF1
으로 계산하여 해당 값을 기준으로 내림차순으로 반환합니다.
쿼리에서 주석 사용
#
문자를 사용하여 쿼리에서 행을 주석 처리할 수 있습니다. #
문자로 시작되는 행은 무시됩니다. 이 기능을 쿼리를 문서화하는 경우 또는 단일 호출에서 해당 행을 삭제하지 않고 복잡한 쿼리의 일부를 일시적으로 무시하려는 경우 유용할 수 있습니다.
다음 예제에서 두 번째 행이 무시됩니다.
fields @timestamp, @message # | filter @message like /delay/ | limit 20
지원되는 연산 및 함수
이 쿼리 언어는 다음 표에 나와 있는 다양한 유형의 연산 및 함수를 지원합니다.
비교 연산
비교 연산은 filter
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다. 비교 연산은 모든 데이터 형식을 인수로 수락하고 부울 결과를 반환합니다.
= != < <= > >=
부울 연산
부울 연산자 and
, or
및 not
을 사용할 수 있습니다. 부울 값을 반환하는 함수에서만 이러한 부울 연산자를 사용할 수 있습니다.
산술 연산
산술 연산을 filter
및 fields
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다. 산술 연산은 숫자 데이터 형식을 인수로 수락하고 숫자 결과를 반환합니다.
작업 | 설명 |
---|---|
|
덧셈 |
|
뺄셈 |
|
곱셈 |
|
나눗셈 |
|
거듭제곱. |
|
나머지 또는 모듈러스. |
수치 연산
숫자 연산을 filter
및 fields
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다. 숫자 연산은 숫자 데이터 형식을 인수로 수락하고 숫자 결과를 반환합니다.
작업 | 결과 유형 | 설명 |
---|---|---|
|
숫자 |
절대값입니다. |
|
숫자 |
천장값으로 반올림합니다( |
|
숫자 |
바닥값으로 반올림합니다( |
|
숫자 |
가장 큰 값을 반환합니다. |
|
숫자 |
가장 작은 값을 반환합니다. |
|
숫자 |
자연 로그입니다. |
|
숫자 |
제곱근입니다. |
일반 함수
일반 함수를 filter
및 fields
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.
함수 | 결과 유형 | 설명 |
---|---|---|
|
부울 |
이 필드가 존재하는 경우 |
|
LogField |
목록에서 null이 아닌 첫 번째 값을 반환합니다. |
문자열 함수
문자열 함수를 filter
및 fields
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.
함수 | 결과 유형 | 설명 |
---|---|---|
|
숫자 |
필드가 누락되어 있거나 빈 문자열일 경우 |
|
숫자 |
필드가 누락되어 있거나 빈 문자열이거나 빈 공백만 포함된 경우 |
|
문자열 |
문자열을 연결합니다. |
|
문자열 |
함수에 두 번째 인수가 없는 경우에는 문자열의 왼쪽에서 공백을 제거합니다. 함수에 두 번째 문자열 인수가 없는 경우에는 공백을 제거하지 않습니다. 대신 |
|
문자열 |
함수에 두 번째 인수가 없는 경우에는 문자열의 오른쪽에서 공백을 제거합니다. 함수에 두 번째 문자열 인수가 없는 경우에는 공백을 제거하지 않습니다. 대신 |
|
문자열 |
함수에 두 번째 인수가 없는 경우에는 문자열의 양쪽 끝에서 공백을 제거합니다. 함수에 두 번째 문자열 인수가 없는 경우에는 공백을 제거하지 않습니다. 대신 |
|
숫자 |
문자열 길이를 Unicode 코드 포인트로 반환합니다. |
|
문자열 |
문자열을 대문자로 변환합니다. |
|
문자열 |
문자열을 소문자로 변환합니다. |
|
문자열 |
숫자 인수가 지정한 인덱스의 하위 문자열을 문자열 끝에 반환합니다. 함수에 두 번째 숫자 인수가 있는 경우 해당 인수에는 검색되는 하위 문자열의 길이가 포함됩니다. 예를 들어, |
|
문자열 |
예를 들어, |
|
숫자 |
|
날짜/시간 함수
날짜/시간 함수를 filter
및 fields
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다. 이러한 함수를 사용해 집계 함수가 포함된 쿼리에 대한 시간 버킷을 생성할 수 있습니다. 숫자와 함께 분을 나타내는 m
또는 시간을 나타내는 h
로 구성된 기간을 사용할 수도 있습니다. 예를 들어, 10m
은 10분을, 1h
는 1시간을 나타냅니다. 다음 표에는 쿼리 명령에 사용할 수 있는 여러 날짜 시간 함수 목록이 포함되어 있습니다. 이 표에는 각 함수의 결과 유형이 나열되며 각 함수에 대한 설명이 포함되어 있습니다.
쿼리 명령을 생성할 때 시간 간격 선택기를 사용하여 쿼리할 기간을 선택할 수 있습니다. 예를 들어, 5~30분 간격, 1, 3, 12시간 간격 또는 사용자 지정 시간 범위 중에서 설정할 수 있습니다. 특정 날짜 사이의 기간을 설정할 수도 있습니다. 쿼리 명령을 실행하는 방법에 대한 자세한 내용은 Amazon CloudWatch Logs 사용 설명서의 자습서: 샘플 쿼리 실행 및 수정을 참조하세요.
함수 | 결과 유형 | 설명 |
---|---|---|
|
타임스탬프 |
|
|
타임스탬프 |
타임스탬프를 지정한 기간으로 자릅니다. 예를 들어, |
|
타임스탬프 |
타임스탬프를 지정한 기간으로 반올림한 다음 자릅니다. 예를 들어, |
|
타임스탬프 |
입력 필드를 Unix Epoch 밀리초로 해석하여 타임스탬프로 변환합니다. |
|
숫자 |
지정된 필드에 있는 타임스탬프를 Unix Epoch 밀리초를 나타내는 숫자로 변환합니다. 예를 들어 |
현재 CloudWatch Logs Insights는 사람이 읽을 수 있는 타임스탬프가 있는 로그 필터링을 지원하지 않습니다.
IP 주소 함수
IP 주소 문자열 함수를 filter
및 fields
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.
함수 | 결과 유형 | 설명 |
---|---|---|
|
부울 |
필드가 유효한 IPv4 또는 IPv6 주소인 경우 |
|
부울 |
필드가 유효한 IPv4 주소인 경우 |
|
부울 |
필드가 유효한 IPv6 주소인 경우 |
|
부울 |
필드가 지정된 v4 또는 v6 서브넷 내 유효한 IPv4 또는 IPv6 주소인 경우 |
|
부울 |
필드가 지정된 v4 서브넷 내 유효한 IPv4 주소인 경우 |
|
부울 |
필드가 지정된 v6 서브넷 내 유효한 IPv6 주소인 경우 |
통계 집계 함수
집계 함수를 stats
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.
함수 | 결과 유형 | 설명 |
---|---|---|
|
숫자 |
지정된 필드의 값 평균입니다. |
|
숫자 |
로그 이벤트를 계산합니다. |
|
숫자 |
필드에 대해 고유한 값의 개수를 반환합니다. 필드의 카디널리티가 매우 높은 경우(고유한 값이 많이 포함되어 있음) |
|
LogFieldValue |
쿼리된 로그에서 이 로그 필드에 대한 최댓값입니다. |
|
LogFieldValue |
쿼리된 로그에서 이 로그 필드에 대한 최솟값입니다. |
|
LogFieldValue |
백분위수는 데이터 세트에서 값의 상대적 위치를 나타냅니다. 예를 들어, |
|
숫자 |
지정된 필드의 값에 대한 표준 편차입니다. |
|
숫자 |
지정된 필드의 값 합계입니다. |
통계 비집계 함수
비집계 함수를 stats
명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.
함수 | 결과 유형 | 설명 |
---|---|---|
|
LogField |
쿼리된 로그에서 가장 이른 타임스탬프가 있는 로그 이벤트에서 |
|
LogField |
쿼리된 로그에서 최신 타임스탬프가 있는 로그 이벤트에서 |
|
LogField |
쿼리된 로그에서 가장 빨리 정렬된 |
|
LogField |
쿼리된 로그에서 가장 늦게 정렬된 |