CloudWatch Logs Insights 쿼리 구문

CloudWatch Logs Insights에서는 로그 그룹을 쿼리하는 데 사용할 수 있는 쿼리 언어를 지원합니다. 쿼리에는 Unix 스타일 파이프 문자(|)로 구분된 쿼리 명령을 한 개 이상 포함할 수 있습니다.

CloudWatch Logs Insights는 일반 함수, 산술 및 비교 연산, 정규 표현식을 포함하되 이에 국한되지 않는 다양한 함수 및 연산을 지원합니다. 자세한 내용은 지원되는 함수 및 연산을 참조하세요.

참고

CloudWatch Logs Insights에서는 사용자가 정규 표현식에 대해 잘 알고 있다고 가정합니다. CloudWatch Logs Insights는 여러 정규 표현식 매칭 라이브러리인 Hyperscan을 지원합니다. Hyperscan 및 관련 구문에 대한 자세한 내용은 Hyperscan 웹 사이트를 참조하세요.

또한 CloudWatch Logs Insights에서는 주석을 지원하고 해시 기호(#)로 시작하는 쿼리의 행을 무시합니다

@ 기호로 시작하는 필드는 CloudWatch Logs Insights에서 자동으로 생성한 것입니다. CloudWatch Logs가 자동으로 생성하는 필드에 대한 자세한 내용은 Amazon CloudWatch 사용 설명서의 지원되는 로그 및 검색된 필드를 참조하세요.

CloudWatch Logs Insights 쿼리 명령

다음 표에는 지원되는 쿼리 명령과 기본 예제가 나와 있습니다. 일반 쿼리 및 다른 로그 유형에 대한 쿼리 예제는 Amazon CloudWatch Logs 사용 설명서의 샘플 쿼리 섹션을 참조하세요.

명령	설명	예
display	쿼리 결과에 표시할 필드를 지정합니다. 쿼리에서 이 명령을 두 번 이상 지정하면 마지막에 지정한 필드만 사용됩니다.	다음 예제에서는 @message 필드를 사용하고 쿼리에서 사용하기 위한 임시 필드 loggingType 및 loggingMessage를 생성합니다. 이는 loggingType 값으로 ERROR를 가진 필드에만 적용되는 이벤트를 필터링하고 결과에 해당 이벤트의 loggingMessage 필드만 표시합니다. fields @message | parse @message "[*] *" as loggingType, loggingMessage | filter loggingType = "ERROR" | display loggingMessage
fields	표시를 위해 로그 이벤트에서 지정된 필드를 검색합니다. 필드 명령 내에서 함수 및 연산을 사용하여 표시할 필드 값을 수정하고 쿼리의 나머지 부분에서 사용할 새 필드를 만들 수 있습니다.	다음 예제에서는 foo-bar 및 action 필드를 표시하고 로그 그룹의 모든 로그 이벤트에 대해 f3와 f4 간 차이의 절대 값을 검색합니다. fields `foo-bar`, action, abs(f3-f4) 다음 예제에서는 임시 필드 opStatus를 만들고 표시합니다. 각 로그 항목에 대한 opStatus의 값은 Operation 및 StatusCode 필드의 값을 하이픈으로 연결한 것입니다. fields concat(Operation, '-', StatusCode) as opStatus
filter	하나 이상의 조건을 기반으로 쿼리 결과를 필터링합니다. filter 명령에서 다양한 연산자와 표현식을 사용할 수 있습니다. 자세한 정보는 필터 명령의 일치 항목 및 정규식 섹션을 참조하세요.	다음 예제에서는 duration 필드의 값이 2,000이 넘는 모든 로그 이벤트에 대해 f1, f2 및 f3 필드를 검색합니다. fields f1, f2, f3 | filter (duration>2000) 또한 다음 예제에서는 유효한 쿼리이긴 하지만 그 결과에는 별도의 필드가 표시되지 않습니다. 대신, 결과에는 @timestamp가 표시되고 기간이 2,000보다 큰 모든 로그 이벤트에 대한 @message 필드의 로그 데이터가 모두 표시됩니다. filter (duration>2000) 다음 예제에서는 f1이 10이거나 f3이 25 이상인 모든 로그 이벤트에 대한 f1 및 f2 필드를 검색합니다. fields f1, f2 | filter (f1=10 or f3>25) 다음 예제에서는 필드 statusCode의 값이 200~299인 로그 이벤트를 반환합니다. fields f1 | filter statusCode like /2\d\d/ 다음 예제에서는statusCode가 "300", "400" 또는 "500"인 로그 이벤트를 반환합니다. fields @timestamp, @message | filter statusCode in [300,400,500] 이 마지막 예제에서는 값이 "foo", "bar" 또는 "1"인 Type 필드가 없는 로그 이벤트를 반환합니다. fields @timestamp, @message | filter Type not in ["foo","bar",1]
stats	로그 필드의 값을 기반으로 집계 통계를 계산합니다. stats를 사용하는 경우 by를 사용하여 통계를 계산할 때 데이터를 그룹화하는 데 사용할 기준을 하나 이상 지정할 수 있습니다. sum(), avg(), count(), min() 및 max()를 포함하나 여러 가지 통계 연산자가 지원됩니다.	다음 예제에서는 f2의 고유한 개별 값에 대해 f1의 평균 값을 계산합니다. stats avg (f1) by f2
sort	검색된 로그 이벤트를 정렬합니다. 오름차순(asc) 및 내림차순(desc)이 둘 다 지원됩니다.	다음 예제에서는 반환되는 이벤트를 f1의 값을 기준으로 내림차순으로 정렬하고 f1, f2, 및 f3 필드를 표시합니다. fields f1, f2, f3 | sort f1 desc
limit	쿼리에서 반환되는 로그 이벤트 수를 지정합니다. 이 옵션을 사용하여 결과를 소수로 제한하여 관련 결과의 소집합을 볼 수 있습니다. 1,000에서 10,000 사이의 숫자와 limit를 함께 사용하여 콘솔에 표시되는 쿼리 결과 행 수를 기본값인 1,000행보다 크게 늘릴 수도 있습니다. 제한을 지정하지 않으면 쿼리의 기본값은 최대 1,000개 행을 표시합니다.	다음 예제에서는 @timestamp의 값을 기준으로 이벤트를 내림차순으로 정렬하고 정렬 순서에 따라 처음 25개 이벤트에 대해 f1 및 f2 필드를 표시합니다. 이 경우, 정렬 순서는 타임스탬프를 기준으로 최신 타임스탬프부터 표시되므로, 최근 25개 이벤트가 반환됩니다. sort @timestamp desc | limit 25 | display f1, f2
parse	로그 필드에서 데이터를 추출하고, 쿼리에서 추가로 처리할 수 있는 임시 필드가 하나 이상 생성됩니다. parse는 glob 표현식과 정규식을 모두 허용합니다. glob 표현식의 경우, 문자의 각 변수가 별표(*)로 대체될 수 있는 상수 문자열로 parse 명령을 제공합니다(큰따옴표 또는 작은따옴표로 문자를 묶음). 이는 as 다음의 별칭을 키워드로 하여 위치 순서로 임시 필드로 추출됩니다. 정규식을 슬래시(/)로 둘러쌉니다. 표현식에는 추출될 일치 스트링의 각 부분이 네임드 캡처링 그룹에 묶여있습니다. 네임드 캡처링 그룹의 예는 (?<name>.*)이 이름이고, name가 패턴인 .*입니다.	단일 로그 라인을 예로 사용합니다. 25 May 2019 10:24:39,474 [ERROR] {foo=2, bar=data} The error was: DataIntegrityException 아래의 두 가지 parse 표현식이 각각 수행하는 작업: 휘발성 필드 level, config 및 exception이 생성됩니다. level은 ERROR, config는 {foo=2, bar=data}, exception은 DataIntegrityException이라는 값을 갖습니다. 첫 번째 예제는 glob 표현식을 사용하고, 두 번째는 정규식을 사용합니다. parse @message "[*] * The error was: *" as level, config, exception parse @message /\[(?<level>\S+)\]\s+(?<config>\{.*\})\s+The error was: (?<exception>\S+)/ 다음 예제에서는 정규식을 사용하여 로그 필드 user2에서 임시 필드 method2, latency2 및 @message를 추출하고 method2 및 user2의 고유한 개별 조합에 대한 평균 지연 시간을 반환합니다. parse @message /user=(?<user2>.*?), method:(?<method2>.*?), latency := (?<latency2>.*?)/ | stats avg(latency2) by method2, user2

쿼리 명령 작업 지침

• 쿼리에서 이름이 지정되고 @ 기호, 마침표(.), 영숫자 문자 이외의 문자를 포함한 로그 필드는 반드시 백틱 ` 키로 둘러싸야 합니다. 예를 들어, foo-bar 필드는 영숫자가 아닌 문자 하이픈(-)을 포함하고 있기 때문에 백틱으로 묶어야 합니다.(`foo-bar`)

• display 및 fields를 사용해 쿼리 결과에 표시하려는 필드를 보여줍니다.

  display는 쿼리 결과에 표시할 필드만 지정합니다. display 명령이 여러 개 있는 경우 최종 display 명령에 지정된 필드만 표시됩니다.

  as 키워드와 함께 fields를 사용하면 로그 이벤트에 있는 함수 및 필드를 사용하는 새 임시 필드를 생성할 수 있습니다. 예를 들어, fields ispresent as isRes가 이름이 isRes인 임시 필드를 생성합니다. 임시 필드는 나머지 쿼리에서 사용할 수 있습니다.

  resolverArn이 로그 이벤트에서 검색되는 필드인지에 따라 isRes 값은 0 또는 1이 됩니다. fields 명령이 여러 개인데 display를 포함하지 않은 경우 fields 명령에 지정된 모든 필드가 표시됩니다.

필터 명령의 일치 항목 및 정규식

filter 명령에서 정규 표현식, 비교 연산자(=, !=, <, <=, >, >=), 부울 연산자(and, or, not)를 사용할 수 있습니다.

in을 사용하여 집합 소속을 테스트할 수 있습니다. in 바로 뒤에 확인할 요소가 있는 배열을 배치합니다. not를 in과 함께 사용할 수 있습니다. in을 사용하는 문자열 일치는 문자열이 완전히 일치해야 합니다.

like 또는 =~ 연산자를 사용하여 하위 문자열을 필터링할 수 있습니다. 하위 문자열 일치의 경우에는 일치해야 하는 하위 문자열을 큰따옴표 또는 작은따옴표로 둘러쌉니다. 정규식 일치를 수행하려면 일치해야 하는 정규식을 슬래시로 둘러쌉니다. 쿼리는 설정한 기준과 일치하는 로그 이벤트만 반환합니다.

예제

다음 세 가지 예제에서는 f1에 단어 Exception이 포함된 모든 이벤트를 반환합니다. 첫 번째 예제에서는 부분 문자열 일치를 사용합니다. 마지막 두 예제는 정규 표현식을 사용합니다. 세 예제 모두 대/소문자를 구별합니다.

fields f1, f2, f3 | filter f1 like "Exception"

fields f1, f2, f3 | filter f1 like /Exception/

fields f1, f2, f3 | filter f1 =~ /Exception/

다음 예제에서는 “Exception”에 대한 검색을 대/소문자를 구분하지 않도록 변경합니다.

fields f1, f2, f3 | filter f1 like /(?i)Exception/ 

다음 예제에서는 정규식을 사용합니다. f1에 정확하게 단어 Exception이 포함된 모든 이벤트를 반환합니다. 이 쿼리는 대/소문자를 구분하지 않습니다.

fields f1, f2, f3 | filter f1 =~ /^(?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 명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다. 산술 연산은 숫자 데이터 형식을 인수로 수락하고 숫자 결과를 반환합니다.

작업	설명
a + b	덧셈
a - b	뺄셈
a * b	곱셈
a / b	나눗셈
a ^ b	거듭제곱. 2 ^ 3은 8을 반환합니다.
a % b	나머지 또는 모듈러스. 10 % 3은 1을 반환합니다.

산술 연산

숫자 연산을 filter 및 fields 명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다. 숫자 연산은 숫자 데이터 형식을 인수로 수락하고 숫자 결과를 반환합니다.

작업	결과 유형	설명
abs(a: number)	숫자	절대값입니다.
ceil(a: number)	숫자	천장값으로 반올림합니다(a의 값보다 큰 수 중 가장 작은 정수).
floor(a: number)	숫자	바닥값으로 반올림합니다(a 값보다 작은 수 중 가장 큰 정수).
greatest(a: number, ...numbers: number[])	숫자	가장 큰 값을 반환합니다.
least(a: number, ...numbers: number[])	숫자	가장 작은 값을 반환합니다.
log(a: number)	숫자	자연 로그입니다.
sqrt(a: number)	숫자	제곱근입니다.

일반 함수

일반 함수를 filter 및 fields 명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.

함수	결과 유형	설명
ispresent(fieldName: LogField)	부울	이 필드가 존재하는 경우 true를 반환합니다.
coalesce(fieldName: LogField, ...fieldNames: LogField[])	LogField	목록에서 null이 아닌 첫 번째 값을 반환합니다.

문자열 함수.

문자열 함수를 filter 및 fields 명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.

함수	결과 유형	설명
isempty(fieldName: string)	부울	필드가 누락되어 있거나 빈 문자열일 경우 true를 반환합니다.
isblank(fieldName: string)	부울	필드가 누락되어 있거나 빈 문자열이거나 빈 공백만 포함된 경우 true를 반환합니다.
concat(str: string, ...strings: string[])	string	문자열을 연결합니다.
ltrim(str: string) ltrim(str: string, trimChars: string)	string	함수에 두 번째 인수가 없는 경우에는 문자열의 왼쪽에서 공백을 제거합니다. 함수에 두 번째 문자열 인수가 없는 경우에는 공백을 제거하지 않습니다. 대신 str의 왼쪽에서 trimChars의 문자를 제거합니다. 예를 들어, ltrim("xyZxyfooxyZ","xyZ")는 "fooxyZ"을 반환합니다.
rtrim(str: string) rtrim(str: string, trimChars: string)	string	함수에 두 번째 인수가 없는 경우에는 문자열의 오른쪽에서 공백을 제거합니다. 함수에 두 번째 문자열 인수가 없는 경우에는 공백을 제거하지 않습니다. 대신 str의 오른쪽에서 trimChars의 문자를 제거합니다. 예를 들어, rtrim("xyZfooxyxyZ","xyZ")는 "xyZfoo"을 반환합니다.
trim(str: string) trim(str: string, trimChars: string)	string	함수에 두 번째 인수가 없는 경우에는 문자열의 양쪽 끝에서 공백을 제거합니다. 함수에 두 번째 문자열 인수가 없는 경우에는 공백을 제거하지 않습니다. 대신 str의 양쪽에서 trimChars의 문자를 제거합니다. 예를 들어, trim("xyZxyfooxyxyZ","xyZ")는 "foo"을 반환합니다.
strlen(str: string)	숫자	문자열 길이를 Unicode 코드 포인트로 반환합니다.
toupper(str: string)	string	문자열을 대문자로 변환합니다.
tolower(str: string)	string	문자열을 소문자로 변환합니다.
substr(str: string, startIndex: number) substr(str: string, startIndex: number, length: number)	string	숫자 인수가 지정한 인덱스의 하위 문자열을 문자열 끝에 반환합니다. 함수에 두 번째 숫자 인수가 있는 경우 해당 인수에는 검색되는 하위 문자열의 길이가 포함됩니다. 예를 들어, substr("xyZfooxyZ",3, 3)는 "foo"을 반환합니다.
replace(str: string, searchValue: string, replaceValue: string)	string	searchValue에서 str의 모든 인스턴스를 replaceValue로 바꿉니다. 예를 들어, replace("foo","o","0")는 "f00"을 반환합니다.
strcontains(str: string, searchValue: string)	숫자	str에 searchValue와 0이 포함되어 있으면 1을 반환합니다.

날짜/시간 함수

날짜/시간 함수를 filter 및 fields 명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다. 이러한 함수를 사용해 집계 함수가 포함된 쿼리에 대한 시간 버킷을 생성할 수 있습니다.

날짜/시간 함수의 일부로 숫자 다음에 분을 나타내는 m 또는 시간을 나타내는 h로 구성된 기간을 사용할 수 있습니다. 예를 들어, 10m은 10분을, 1h는 1시간을 나타냅니다.

함수	결과 유형	설명
bin(period: Period)	타임스탬프	@timestamp의 값을 지정한 기간으로 반올림한 다음 자릅니다. 예를 들어, bin(5m)은 @timestamp 값이 잘리기 전에 5분으로 반올림합니다.
datefloor(timestamp: Timestamp, period: Period)	타임스탬프	타임스탬프를 지정한 기간으로 자릅니다. 예를 들어, datefloor(@timestamp, 1h)는 @timestamp의 모든 값을 해당 시간 아래로 자릅니다.
dateceil(timestamp: Timestamp, period: Period)	타임스탬프	타임스탬프를 지정한 기간으로 반올림한 다음 자릅니다. 예를 들어, dateceil(@timestamp, 1h)는 @timestamp의 모든 값을 해당 시간 위로 자릅니다.
fromMillis(fieldName: number)	타임스탬프	입력 필드를 Unix Epoch 밀리초로 해석하여 타임스탬프로 변환합니다.
toMillis(fieldName: Timestamp)	숫자	지정된 필드에 있는 타임스탬프를 Unix Epoch 밀리초를 나타내는 숫자로 변환합니다.

IP 주소 함수

IP 주소 문자열 함수를 filter 및 fields 명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.

함수	결과 유형	설명
isValidIp(fieldName: string)	부울	필드가 유효한 IPv4 또는 IPv6 주소인 경우 true를 반환합니다.
isValidIpV4(fieldName: string)	부울	필드가 유효한 IPv4 주소인 경우 true를 반환합니다.
isValidIpV6(fieldName: string)	부울	필드가 유효한 IPv6 주소인 경우 true를 반환합니다.
isIpInSubnet(fieldName: string, subnet: string)	부울	필드가 지정된 v4 또는 v6 서브넷 내 유효한 IPv4 또는 IPv6 주소인 경우 true를 반환합니다. 서브넷을 지정할 때는 192.0.2.0/24 또는 2001:db8::/32와 같은 CIDR 표기법을 사용합니다.
isIpv4InSubnet(fieldName: string, subnet: string)	부울	필드가 지정된 v4 서브넷 내 유효한 IPv4 주소인 경우 true를 반환합니다. 서브넷을 지정할 때는 192.0.2.0/24와 같은 CIDR 표기법을 사용합니다.
isIpv6InSubnet(fieldName: string, subnet: string)	부울	필드가 지정된 v6 서브넷 내 유효한 IPv6 주소인 경우 true를 반환합니다. 서브넷을 지정할 때는 2001:db8::/32와 같은 CIDR 표기법을 사용합니다.

통계 집계 함수

집계 함수를 stats 명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.

함수	결과 유형	설명
avg(fieldName: NumericLogField)	숫자	지정된 필드의 값 평균입니다.
count() count(fieldName: LogField)	숫자	로그 이벤트를 계산합니다. count()(또는count(*))는 쿼리에서 반환하는 이벤트 수를 모두 세고 count(fieldName)은 지정한 필드 이름이 포함된 레코드 수를 모두 계산합니다.
count_distinct(fieldName: LogField)	숫자	필드에 대해 고유한 값의 개수를 반환합니다. 필드의 카디널리티가 매우 높은 경우(고유한 값이 많이 포함되어 있음) count_distinct가 반환하는 값은 근사치입니다.
max(fieldName: LogField)	LogFieldValue	쿼리된 로그에서 이 로그 필드에 대한 최댓값입니다.
min(fieldName: LogField)	LogFieldValue	쿼리된 로그에서 이 로그 필드에 대한 최솟값입니다.
pct(fieldName: LogFieldValue, percent: number)	LogFieldValue	백분위수는 데이터 세트에서 값의 상대적 위치를 나타냅니다. 예를 들어, pct(@duration, 95)는 @duration의 값 중 95퍼센트가 이 값보다 낮고 5퍼센트는 이 값보다 큰 @duration 값을 반환합니다.
stddev(fieldName: NumericLogField)	숫자	지정된 필드의 값에 대한 표준 편차입니다.
sum(fieldName: NumericLogField)	숫자	지정된 필드의 값 합계입니다.

통계 비집계 함수

비집계 함수를 stats 명령에서 사용하고 다른 함수의 인수로 사용할 수 있습니다.

함수	결과 유형	설명
earliest(fieldName: LogField)	LogField	쿼리된 로그에서 가장 이른 타임스탬프가 있는 로그 이벤트에서 fieldName의 값을 반환합니다.
latest(fieldName: LogField)	LogField	쿼리된 로그에서 최신 타임스탬프가 있는 로그 이벤트에서 fieldName의 값을 반환합니다.
sortsFirst(fieldName: LogField)	LogField	쿼리된 로그에서 가장 빨리 정렬된 fieldName의 값을 반환합니다.
sortsLast(fieldName: LogField)	LogField	쿼리된 로그에서 가장 늦게 정렬된 fieldName의 값을 반환합니다.