CloudWatch 검색 표현식 구문 - Amazon CloudWatch
토큰화부분 일치정확히 일치지표 스키마 제외검색에서 속성 이름 지정영숫자가 아닌 문자부울 연산수학 표현식 사용

CloudWatch 검색 표현식 구문

유효한 검색 표현식의 형식은 다음과 같습니다.

SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')

예:

SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')

  • SEARCH 단어 뒤에 중괄호로 묶여 있는 쿼리의 첫 번째 부분은 검색할 지표 스키마입니다. 지표 스키마에는 하나의 지표 네임스페이스와 하나 이상의 측정기준 이름이 포함됩니다. 검색 쿼리에 지표 스키마를 포함하는 것은 선택 사항입니다. 지정된 경우 지표 스키마에는 네임스페이스가 있어야 하며, 해당 네임스페이스에서 유효한 하나 이상의 측정기준 이름을 선택적으로 포함할 수 있습니다.

    네임스페이스 또는 측정기준 이름에 공백이나 영숫자가 아닌 문자가 포함되지 않는 한 지표 스키마 내에 따옴표를 사용할 필요가 없습니다. 따옴표를 사용해야 하는 경우 해당 문자가 포함된 이름을 큰따옴표로 묶어야 합니다.

  • SearchTerm도 선택 사항이지만, 유효한 검색에는 지표 스키마, SearchTerm 또는 둘 다 포함되어야 합니다. 일반적으로 SearchTerm에는 하나 이상의 계정 ID, 지표 이름 또는 차원 값이 포함되어 있습니다. SearchTerm에는 부분 일치 및 정확한 일치로 검색할 용어가 여러 개 포함될 수 있습니다. 또한 부울 연산자도 포함될 수 있습니다.

    SearchTerm에서 계정 ID 사용은 CloudWatch 크로스 계정 관측성을 위한 모니터링 계정으로 설정된 계정에서만 가능합니다. SearchTerm의 계정 ID 구문은 :aws.AccountId = "444455556666"입니다. 'LOCAL'을 사용하여 :aws.AccountId = 'LOCAL'과 같이 모니터링 계정 자체를 지정할 수도 있습니다.

    자세한 내용은 CloudWatch 크로스 계정 관측성 단원을 참조하십시오.

    SearchTerm에는 하나 이상의 지정자가 포함될 수 있지만(이 예에서는 MetricName=), 지정자를 사용하는 것은 필수 사항이 아닙니다.

    지표 스키마 및 SearchTerm은 작은따옴표 쌍으로 함께 묶여야 합니다.

  • Statistic은 유효한 CloudWatch 통계의 이름입니다. 이는 작은따옴표로 묶여야 합니다. 자세한 내용은 Statistics 단원을 참조하십시오.

위의 예제에서는 측정기준 이름이 AWS/EC2인 지표에 대한 InstanceId 네임스페이스를 검색합니다. 찾은 모든 CPUUtilization 지표를 반환하며 그래프에는 Average 통계가 표시됩니다.

검색 표현식은 지난 2주 이내에 데이터를 보고한 지표만 찾을 수 있습니다.

검색 표현식 제한

검색 표현식 쿼리의 최대 크기는 1024자입니다. 그래프 하나에 무려 100개의 검색 표현식이 있을 수 있습니다. 그래프에는 최대 500개의 시계열이 표시될 수 있습니다.

CloudWatch 검색 표현식: 토큰화

SearchTerm을 지정하면 검색 함수는 CloudWatch가 전체 지표 이름, 측정기준 이름, 측정기준 값, 네임스페이스에서 자동으로 생성하는 하위 문자열인 ‘토큰’을 검색합니다. CloudWatch는 원래 문자열에서 낙타 대문자로 구분되는 토큰을 생성합니다. 또한 숫자 문자는 새 토큰의 시작 부분으로 사용되며, 영숫자가 아닌 문자는 구분 기호로 사용되며, 영숫자가 아닌 문자 앞/뒤에는 토큰을 생성합니다.

동일한 유형의 토큰 구분 기호로 이루어진 연속 문자열이 한 개의 토큰이 됩니다.

생성된 토큰은 모두 소문자입니다. 다음 표에는 생성된 토큰의 일부 예가 나와 있습니다.

원래 문자열 생성된 토큰

CustomCount1

customcount1, custom, count, 1

SDBFailure

sdbfailure, sdb, failure

Project2-trial333

project2trial333, project, 2, trial, 333

CloudWatch 검색 표현식: 부분 일치

SearchTerm을 지정하면 검색어도 토큰화됩니다. CloudWatch는 검색어에서 생성된 단일 토큰이 지표 이름, 네임스페이스, 측정기준 이름 또는 측정기준 값에서 생성된 단일 토큰과 일치하는 부분 일치에 따라 지표를 찾습니다.

단일 토큰과 일치하는 부분 일치 검색은 대/소문자를 구별하지 않습니다. 예를 들어, 다음 검색어를 사용하면 CustomCount1 지표가 반환될 수 있습니다.

  • count

  • Count

  • COUNT

그러나 couNT를 검색어로 사용하면 검색어 couNT의 대문자가 cou 및 NT로 토큰화되므로 CustomCount1을 찾지 않습니다.

검색 시 원래 이름에 연속으로 나타나는 여러 토큰인 복합 토큰과도 일치할 수 있습니다. 복합 토큰과 일치시키기 위해 검색 시 대/소문자를 구별합니다. 예를 들어, 원래 용어가 CustomCount1인 경우 CustomCount 또는 Count1에 대한 검색은 성공하지만 customcount 또는 count1에 대한 검색은 실패합니다.

CloudWatch 검색 표현식: 정확한 일치

정확하게 일치해야 하는 검색어 부분을 큰따옴표로 묶어 검색어와 정확하게 일치하는 용어만 찾도록 검색을 정의할 수 있습니다. 이러한 큰따옴표는 전체 검색어에 주위에 사용되는 작은따옴표로 묶여 있습니다. 예를 들어, SEARCH(' {MyNamespace}, "CustomCount1" ', 'Maximum')는 이름이 CustomCount1인 네임스페이스에 지표 이름, 측정기준 이름 또는 측정기준 값으로 있는 경우 정확한 문자열 MyNamespace을 찾습니다. 그러나 SEARCH(' {MyNamespace}, "customcount1" ', 'Maximum') 또는 SEARCH(' {MyNamespace}, "Custom" ', 'Maximum') 검색은 이 문자열을 찾지 않습니다.

단일 검색 표현식에서 부분 일치 용어와 정확한 일치 용어를 결합할 수 있습니다. 예를 들어 SEARCH(' {AWS/NetworkELB, LoadBalancer} "ConsumedLCUs" OR flow ', 'Maximum') 표현식은 ConsumedLCUs라는 Elastic Load Balancing 지표를 반환하는 것은 물론 flow 토큰이 포함된 모든 Elastic Load Balancing 지표 또는 측정기준을 반환합니다.

또한 다음 예제와 같이 영숫자가 아닌 문자 또는 공백 같은 특수 문자가 있는 이름을 찾을 때 정확한 일치를 사용하는 것이 좋습니다.

SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')

CloudWatch 검색 표현식: 지표 스키마 제외

지금까지 살펴본 모든 예제의 지표 스키마는 중괄호 안에 포함되어 있습니다. 지표 스키마를 생략하는 검색도 유효합니다.

예를 들어, SEARCH(' "CPUUtilization" ', 'Average')는 CPUUtilization 문자열과 정확하게 일치하는 모든 지표 이름, 측정기준 이름, 측정기준 값 및 네임스페이스를 반환합니다. AWS 지표 네임스페이스에서는 여기에 Amazon EC2, Amazon ECS, SageMaker 및 기타 서비스를 비롯한 여러 서비스의 지표가 포함될 수 있습니다.

이 검색 범위를 AWS 서비스 하나만으로 좁히려면 다음 예제와 같이 지표 스키마에 네임스페이스와 필요한 측정기준을 지정하는 것이 좋습니다. 이렇게 하면 검색 범위가 AWS/EC2 네임스페이스로 좁혀지지만 CPUUtilization을 해당 지표의 측정기준 값으로 정의한 경우 다른 지표의 결과가 계속 반환됩니다.

SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')

또는 다음 예제와 같이 SearchTerm에 네임스페이스를 추가할 수 있습니다. 그러나 이 예제에서는 검색 시 사용자 지정 측정기준 이름 또는 값인 경우에도 AWS/EC2 문자열과 일치합니다.

SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')

CloudWatch 검색 표현식: 검색에서 속성 이름 지정

"CustomCount1"에 대해 다음의 정확한 일치 검색을 수행하면 해당 이름과 정확하게 일치하는 모든 지표를 반환합니다.

SEARCH(' "CustomCount1" ', 'Maximum')

그러나 CustomCount1의 측정기준 이름, 측정기준 값 또는 네임스페이스가 있는 지표도 반환합니다. 검색을 자세히 구성하려면 검색에서 찾으려는 객체 유형의 속성 이름을 지정하면 됩니다. 다음 예제는 모든 네임스페이스를 검색하고 이름이 CustomCount1인 지표를 반환합니다.

SEARCH(' MetricName="CustomCount1" ', 'Maximum')

다음 예제와 같이 네임스페이스와 측정기준 이름/값 페어를 속성 이름으로 사용할 수도 있습니다. 이러한 예제의 첫 번째는 부분 일치 검색에도 속성 이름을 사용할 수 있음을 보여줍니다.

SEARCH(' InstanceType=micro ', 'Average')
SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')

CloudWatch 검색 표현식: 영숫자가 아닌 문자

영숫자가 아닌 문자는 구분 기호로 사용되며, 지표, 측정기준, 네임스페이스 및 검색어의 이름을 토큰으로 구분할 위치를 표시합니다. 용어가 토큰화되면 영숫자가 아닌 문자가 제거되며 토큰에 표시되지 않습니다. 예를 들어, Network-Errors_2는 network, errors 및 2 토큰을 생성합니다.

검색어에 영숫자가 아닌 문자가 포함될 수 있습니다. 검색어에 이러한 문자가 표시되면 해당 문자는 부분 일치에서 복합 토큰을 지정할 수 있습니다. 예를 들어, 다음 검색에서는 이름이 Network-Errors-2 또는 NetworkErrors2인 지표를 모두 찾습니다.

network/errors
network+errors
network-errors
Network_Errors

정확한 값 검색을 수행할 경우 정확한 검색에 사용된 영숫자가 아닌 문자는 검색할 문자열에 표시되는 정확한 문자여야 합니다. 예를 들어, Network-Errors-2를 찾으려는 경우 "Network-Errors-2"에 대한 검색은 성공하지만 "Network_Errors_2"에 대한 검색은 실패합니다.

정확한 일치 검색을 수행할 경우 다음 문자는 백슬래시로 이스케이프되어야 합니다.

" \ ( )

예를 들어, 정확한 일치로 이름이 Europe\France Traffic(Network)인 지표를 찾으려면 "Europe\\France Traffic\(Network\)" 검색어를 사용해야 합니다.

CloudWatch 검색 표현식: 부울 연산자

검색 시 SearchTerm 내에 부울 연산자 AND, OR 및 NOT을 사용할 수 있습니다. 부울 연산자는 전체 검색어를 묶을 때 사용하는 작은따옴표로 묶습니다. 부울 연산자는 대/소문자를 구별하므로 and, or 및 not은 부울 연산자로 사용할 수 없습니다.

SEARCH('{AWS/EC2,InstanceId} network AND packets', 'Average') 같이 검색에서 AND를 명시적으로 사용할 수 있습니다. 검색어 사이에 부울 연산자를 사용하지 않으면 암시적으로 AND 연산자가 있는 것처럼 검색합니다. 따라서 SEARCH(' {AWS/EC2,InstanceId} network packets ', 'Average')의 경우 동일한 검색 결과가 발생합니다.

결과에서 데이터의 하위 집합을 제외하려면 NOT을 사용합니다. 예를 들어, SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average')는 i-1234567890123456 인스턴스를 제외한 모든 인스턴스에 대해 CPUUtilization을 반환합니다. NOT 절을 유일한 검색어로 사용할 수도 있습니다. 예를 들어, SEARCH( 'NOT Namespace=AWS ', 'Maximum')는 사용자 지정 지표(AWS가 포함되지 않은 네임스페이스가 있는 지표)를 모두 생성합니다.

쿼리에 여러 NOT 구문을 사용할 수 있습니다. 예를 들어, SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average')는 리전에서 CPUUtilization 또는 ProjectA의 측정기준 값이 있는 것을 제외한 모든 인스턴스의 ProjectB을 반환합니다.

다음 예제와 같이 더욱 강력하고 상세한 검색을 위해 부울 연산자를 결합할 수 있습니다. 연산자를 그룹화하려면 괄호를 사용합니다.

다음의 두 예제는 EC2 및 EBS 네임스페이스 둘 다의 ReadOps이 포함된 지표 이름을 모두 반환합니다.

SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')
SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')

다음 예제는 이전 검색을 ProjectA(측정기준 값일 수 있음)만 포함된 결과로 범위를 좁힙니다.

SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')

다음 예제는 중첩 그룹화를 사용합니다. 모든 함수의 Errors 및 이름에 ProjectA 또는 ProjectB 문자열이 포함된 함수의 Invocations에 대한 Lambda 지표를 반환합니다.

SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')

CloudWatch 검색 표현식: 수학 표현식 사용

그래프의 수학 표현식 내에서 검색 표현식을 사용할 수 있습니다.

예를 들어 SUM(SEARCH(' {AWS/Lambda, FunctionName} MetricName="Errors" ', 'Sum')) 표현식은 모든 Lambda 함수의 Errors 지표에 대한 합계를 반환합니다.

검색 표현식과 수학 표현식에 별도의 줄을 사용하면 더 유용한 결과를 얻을 수 있습니다. 예를 들어, 그래프에서 다음의 두 표현식을 사용한다고 가정해 보겠습니다. 첫 번째 줄은 각 Lambda 함수에 대한 별도의 Errors 줄을 표시합니다. 이 표현식의 ID는 e1입니다. 두 번째 줄은 모든 함수의 오류 합계를 표시하는 다른 줄을 추가합니다.

SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)