Amazon CloudWatch 쿼리 편집기

Amazon CloudWatch 쿼리 편집기 (Amazon CloudWatch query editor)

Grafana는 CloudWatch 데이터 소스용 쿼리 편집기를 제공해 Amazon CloudWatch에 저장된 로그·메트릭을 쿼리, 시각화, 알림할 수 있어요. Explore 페이지에 있으며, 메트릭(CloudWatch Metrics)과 로그(CloudWatch Logs) 각각 전용 쿼리 편집기가 있습니다.

출처: 문서

본문

Grafana는 CloudWatch 데이터 소스용 쿼리 편집기를 제공하며, Explore 페이지에 있습니다. Grafana 데이터 소스 쿼리에 대한 일반 문서는 Query and transform data를 참고하세요.

핵심 개념 (Key concepts)

용어	설명
Namespace	CloudWatch 메트릭의 컨테이너. 보통 AWS 서비스당 하나. 예: `AWS/EC2`, `AWS/Lambda`
Metric	CloudWatch에 게시되는 시간 순서 데이터 포인트 집합. 예: `CPUUtilization`
Dimension	메트릭에 대한 특정 리소스를 식별하는 이름-값 쌍. 예: `InstanceId=i-1234567890abcdef0`
Statistic	일정 기간 동안 메트릭 데이터에 적용되는 집계. 예: `Average`, `Sum`, `Maximum`
Period	메트릭 데이터 포인트를 집계하는 데 사용하는 시간(초)
Metric math	메트릭을 결합·변환하는 표현식(예: rate 또는 메트릭 간 합 계산)
Metrics Insights	네이티브에 가까운 실시간 메트릭 필터링·집계용 SQL 유사 쿼리 엔진
Search expression	쿼리 시 여러 메트릭을 매칭하는 CloudWatch 표현식. 흔히 와일드카드와 사용
Logs Insights QL	로그 데이터 검색·집계에 사용하는 CloudWatch Logs 쿼리 언어

쿼리 편집 모드 선택 (Choose a query editing mode)

CloudWatch 데이터 소스는 CloudWatch Metrics와 CloudWatch Logs 두 API에서 쿼리할 수 있으며 각각 전용 쿼리 편집기가 있습니다. 쿼리할 API는 Region 설정 오른쪽의 드롭다운으로 선택합니다.

CloudWatch Metrics 쿼리 편집기 구성 요소

설정	설명
Region	기본과 다르면 AWS 리전 선택
Namespace	AWS 서비스 네임스페이스. 예: `AWS/EC2`, `AWS/Lambda`
Metric name	시각화할 메트릭 이름. 예: `CPUUtilization`
Statistic	데이터 집계 방법 선택: `Average`, `Maximum`, `Minimum`, `Sum`, `SampleCount`, `IQM`. `p99` 같은 백분위수 커스텀 값도 입력 가능
Dimensions	드롭다운에서 차원 선택. 예: `InstanceId`, `FunctionName`, `latency`. 여러 차원 추가 가능
Match exact	(선택) 활성화 시 지정한 차원과 값에 정확히 일치하는 메트릭으로 결과 제한. 쿼리된 메트릭의 모든 차원이 쿼리에 명시적으로 정의되어야 정확한 스키마 일치 보장. 비활성화 시 정의된 스키마와 일치하지만 추가 차원이 있는 메트릭도 반환
ID	(선택) GetMetricData API가 math 표현식에서 쿼리를 참조하는 데 필요한 고유 식별자. 소문자로 시작해야 하며 문자·숫자·밑줄 포함 가능. 미지정 시 Grafana가 `query[refId]` 패턴으로 생성(예: 첫 쿼리 행은 `queryA`)
Period	데이터 포인트 사이의 최소 시간 간격(초). 기본 `auto`. CloudWatch는 1, 5, 10, 30, 또는 60의 배수 초를 허용. `auto`나 공백이면 Grafana가 시간 범위(초)를 2000으로 나눈 뒤 60, 300, 900, 3600, 21600, 86400 중 다음 값으로 올림해 계산. 사용 가능한 period는 데이터 연령에 달림: CloudWatch는 retention policy에 따라 오래된 메트릭을 더 낮은 해상도로 저장하므로 오래된 범위에는 짧은 period를 사용할 수 없음
Label	(선택) 커스터마이즈된 시계열 범례 이름. 라벨 필드는 CloudWatch 동적 라벨을 사용해 기본 메트릭 범례 이름을 재정의. `${MIN_MAX_TIME_RANGE}` 같은 시간 기반 동적 라벨은 시간 범위 선택기의 현재 시간대에서 범례 값을 파생. 전체 라벨 패턴·제한 목록은 CloudWatch dynamic labels 참고

Builder·Code 모드 사용 (Use Builder and Code modes)

Metric Search와 Metric Insights 두 쿼리 유형 모두 두 편집 모드를 제공합니다. 쿼리 편집기의 Builder·Code 토글로 전환합니다.

Builder 모드: 드롭다운·폼 필드로 쿼리 구성(구문 작성 불필요). Metric Search는 namespace·metric name·statistic·dimensions 선택. Metric Insights는 Metrics Insights keywords로 namespace·metric name·filter·group·order 옵션 선택, Grafana가 SQL 쿼리 구성.
Code 모드: 코드 편집기에 직접 쿼리 작성. Metric Search는 metric math 또는 SEARCH 표현식, Metric Insights는 Metrics Insights SQL 쿼리 작성. 코드 편집기는 키워드·집계·네임스페이스·메트릭·라벨·라벨 값 제안하는 내장 자동완성 포함. 공백, 쉼표, 달러($) 문자 입력 후 또는 CTRL+Space 로 제안이 나타납니다.
- 참고: 코드 편집기의 템플릿 변수는 자동완성과 간섭할 수 있어요.
- 쿼리 실행은 코드 편집기 위의 Run query 클릭.

CloudWatch 메트릭 쿼리 (Query CloudWatch metrics)

두 가지 쿼리 유형을 만들 수 있어요: Metric Search(메트릭 검색·필터링에 도움)와 Metric Insights(Metrics Insights 기능으로 시계열 데이터 가져오기). 쿼리 편집기 중앙 위쪽 드롭다운으로 유형을 선택합니다.

Metric Search 쿼리: 와일드카드와 필터로 정확한 메트릭 이름을 몰라도 메트릭을 발견합니다. 유효한 메트릭 쿼리는 네임스페이스, 메트릭 이름, 최소 하나의 statistic을 지정해야 해요. 차원은 선택 사항이지만 포함할 경우 key와 value를 모두 제공해야 합니다.

Match Exact 옵션은 차원 필터링 적용 방식을 제어합니다. 활성화하면 지정 기준과 정확히 일치하는 차원의 메트릭만 반환하며, 대상 메트릭의 모든 차원이 명시적으로 지정되어야 하고, 필터링하지 않을 차원은 와일드카드(*) 필터를 사용해야 합니다. 비활성화하면 필터링 차원의 어떤 하위 집합이든 지정할 수 있으며, 지정된 namespace·metric name과 일치하고 모든 정의된 차원 필터와 일치하며 추가 차원을 가질 수 있는 메트릭을 반환합니다(더 유연하지만 예상치 못한 추가 차원이 있는 메트릭 반환 가능). 데이터 소스는 CloudWatch GetMetricData API를 통해 메트릭을 가져오므로, 단일 쿼리는 필터 기준에 맞는 최대 100개 메트릭의 데이터를 반환합니다(AWS가 시행하는 요청당 한도).

차원 와일드카드로 동적 쿼리 만들기: 차원 값에 별표(*) 와일드카드 사용. Match Exact 비활성화 + InstanceId에 와일드카드 사용 시 추가 차원과 무관하게 모든 EC2 인스턴스의 메트릭을 검색합니다. Query inspector 버튼 → Meta Data 클릭 시 와일드카드를 지원하도록 자동 생성된 검색 표현식을 확인할 수 있어요. 검색 표현식은 기본적으로 쿼리된 메트릭이 정의된 차원 이름과 정확히 일치하도록 정의됩니다. Match Exact 비활성화 시 와일드카드 없이도 추가 차원이 있는 메트릭을 포함하고 검색 표현식을 생성합니다.

다중 값 템플릿 변수 사용: 차원 값을 다중 값 템플릿 변수로 정의할 때 데이터 소스는 검색 표현식으로 매칭 메트릭을 쿼리합니다. 이를 통해 한 쿼리에 여러 템플릿 변수를 사용하고 Match Exact 비활성화 쿼리에도 템플릿 변수를 쓸 수 있어요. 검색 표현식은 1,024자로 제한되므로 긴 값 목록이면 쿼리가 실패할 수 있습니다. 특정 차원 이름에 어떤 값이든 있는 모든 메트릭을 쿼리하려면 All 옵션 대신 별표(*) 와일드카드를 권장합니다. 다중 값 템플릿 변수는 차원 값에만 지원되며 Region, Namespace, Metric Name에는 지원되지 않아요.

Metric math 표현식 사용: CloudWatch 메트릭에 수학 함수를 적용해 새 시계열 메트릭 생성. 산술 연산자, 단항 뺄셈 등 지원. 사용 가능한 함수는 AWS Metric Math 참고. 원시 메트릭에 고유 문자열 ID를 할당하고 새 메트릭의 Expression 필드에서 이 ID를 참조해 산술 연산을 적용합니다.

참고: 표현식 필드에서 다른 쿼리(예: queryA * 2)를 참조하면 해당 쿼리 기반 알림 규칙을 만들 수 없어요.

AWS 모니터링 계정 간 메트릭 쿼리: Metric search 편집기에서 Builder 모드를 선택하면 새 Account 필드가 표시됩니다. 링크된 모니터링 계정 중 어떤 계정을 대상으로 할지 지정하며, 기본 All은 모든 링크 계정을 대상으로 합니다. Code 모드에서는 모든 math 표현식을 지정할 수 있고, Monitoring account 배지가 표시되면 이 필드의 모든 SEARCH 표현식이 기본적으로 계정 간(cross-account)이며 링크 계정의 메트릭을 쿼리할 수 있어요. 계정 간 쿼리 동안 자동완성은 계정 간 리소스를 가져오지 않으므로 계정 간 쿼리 작성 시 리소스 이름을 수동으로 지정해야 합니다. 검색을 한 계정이나 계정 집합으로 제한할 수 있습니다.

Period 매크로: CloudWatch SEARCH 표현식을 사용한다면 period를 명시적으로 지정하기보다 $__period_auto 매크로 사용을 고려하세요. 이 매크로는 선택한 시간 범위에 적합한 CloudWatch period로 해석됩니다.

패널을 CloudWatch 콘솔로 딥 링크: 패널에서 시계열을 왼쪽 클릭하면 View in CloudWatch console 링크가 있는 컨텍스트 메뉴가 표시됩니다. 클릭 시 새 탭에서 CloudWatch 콘솔로 이동해 해당 쿼리의 모든 메트릭을 표시합니다. 로그인하지 않았다면 로그인 페이지로 이동합니다. 이 기능은 metric math 표현식 기반 메트릭에는 사용할 수 없어요.

Metric Insights 구문 사용 (Use Metric Insights syntax)

Metric Insights는 SQL 방언과 다음 쿼리 구문을 사용합니다:

SELECT FUNCTION(MetricName)
FROM Namespace | SCHEMA(...)
[ WHERE labelKey OPERATOR labelValue [AND|...]]
[ GROUP BY labelKey [, ...]]
[ ORDER BY FUNCTION() [DESC | ASC] ]
[ LIMIT number]

Metrics Insights 키워드:

키워드	설명
`FUNCTION`	필수. 사용할 집계 함수와 쿼리할 메트릭 이름 지정. 유효 값: AVG, COUNT, MAX, MIN, SUM
`MetricName`	필수. 예: `CPUUtilization`
`FROM`	필수. 메트릭 소스 지정. 메트릭을 포함하는 namespace 또는 SCHEMA 테이블 함수 지정. 예: `AWS/EC2`, `AWS/Lambda`
`SCHEMA`	선택. 정확히 일치하거나 일치하지 않는 메트릭으로만 쿼리 결과 좁힘
`WHERE`	선택. 지정한 표현식과 일치하는 메트릭만 필터링. 예: `WHERE InstanceType != 'c3.4xlarge'`
`GROUP BY`	선택. 여러 시계열로 결과 그룹핑. 예: `GROUP BY ServiceName`
`ORDER BY`	선택. 시계열 반환 순서 지정. 옵션: `ASC`, `DESC`
`LIMIT`	선택. 반환할 시계열 수 제한

CloudWatch Logs 쿼리 (Query CloudWatch Logs)

로그 쿼리 편집기는 선택한 리전과 로그 그룹(local group) 집합 또는 Amazon CloudWatch Logs 데이터 소스에서 쿼리를 작성합니다. 세 가지 지원 쿼리 언어 옵션이 있습니다:

Logs Insights QL — CloudWatch Logs용으로 설계된 AWS 네이티브 쿼리 언어. fields, filter, stats, sort 같은 명령의 SQL 유사 구문. CloudWatch 로그 구조에 최적화되어 있으며 타임스탬프 파싱, JSON 로그 필드 추출, 집계 수행용 내장 함수 제공.
OpenSearch SQL — OpenSearch 데이터를 쿼리하는 SQL 유사 구문 언어. 표준 SQL 쿼리 지원, SQL에 익숙한 사용자용.
OpenSearch PPL — Elasticsearch의 query DSL 기반 OpenSearch 쿼리 언어. Unix 명령줄 도구·Splunk 검색 언어와 비슷한 파이프 기반 구문. 복잡한 boolean 로직, 범위 쿼리, 와일드카드 매칭, 전체 텍스트 검색 지원.

CloudWatch Logs 쿼리 만들기:

리전 선택.
쿼리 유형 드롭다운에서 CloudWatch Logs 선택.
Logs Mode 선택기로 Logs Insights와 Log Anomalies 쿼리 사이 선택.

Log Anomalies: 이상 탐지는 기계 학습·패턴 인식으로 일반적인 로그 내용의 기준선을 설정합니다. Log Anomalies 쿼리 편집기는 CloudWatch 서비스에서 감지된 이상 목록을 가져옵니다. 편집기에서 로그 이상을 쿼리하려면 먼저 AWS CloudWatch 콘솔에서 로그 이상 탐지기(log anomaly detector)를 만들어야 해요. 로그 추세 셀은 선택한 쿼리 시간 범위에 걸친 패턴 발생 횟수를 보여줍니다. 테이블은 한 번에 50개의 로그 이상을 표시하며, ARN과 억제(suppressed) 상태로 필터링할 수 있습니다. 또한 Logs Insights QL 편집기에서 anomaly 명령을 patterns 명령과 함께 사용해 실시간으로 로그 이상을 정의·표시할 수 있어요.

Logs Insights: Query language 드롭다운은 Logs Mode가 Logs Insights일 때만 사용 가능합니다. 쿼리 언어를 선택하고, 쿼리할 로그 그룹·CloudWatch Logs 데이터 소스·둘 다를 지정한 뒤 기본 입력 영역에 로그 쿼리를 작성합니다. Amazon CloudWatch는 OpenSearch SQL·PPL 명령의 하위 집합만 지원하므로 지원 구문은 Amazon CloudWatch Logs 문서를 확인하세요.

쿼리할 로그 그룹 지정:

Log group name: 특정 로그 그룹 선택(기본). 최대 50개 선택. Select log groups 클릭. Monitoring account 배지가 있으면 여러 계정에서 로그 그룹 검색·선택 가능, Accounts 필터로 계정별 좁힘. 큰 목록은 prefix 검색 사용, 선택기는 페이지 단위로 로드되며 스크롤로 더 불러올 수 있음.
Name prefix: Name prefix 쿼리 범위 선택 후 최대 5개 로그 그룹 이름 접두사 제공. 지정한 접두사로 시작하는 이름의 로그 그룹 대상. 각 접두사는 최소 3자이며 * 포함 불가. Logs Insights QL에서만 사용 가능.
All log groups: 선택한 리전의 모든 로그 그룹 쿼리. Logs Insights QL에서만 사용 가능.

Name prefix·All log groups 범위에는 선택적 필터 적용 가능: Class(로그 그룹 클래스별 필터링: Standard 또는 Infrequent Access), Accounts(AWS 계정별 필터링. Monitoring account 배지 있을 때만, 최대 20개 계정).

쿼리할 Amazon CloudWatch Logs 데이터 소스 지정: Amazon CloudWatch Logs 데이터 소스는 이를 생성하는 서비스·애플리케이션과 로그 유형으로 로그를 분류합니다. 로그 그룹을 보완하며 개별 로그 그룹 이름을 몰라도 로그를 쿼리할 수 있어요. 데이터 소스 선택기 사용 전에 Grafana 데이터 소스의 IAM 역할·사용자에 logs:ListAggregateLogGroupSummaries 권한이 있는지 확인하세요. 완전한 IAM 정책 예시는 IAM policy examples 참고.

Select data sources 클릭 → 데이터 소스 이름·유형 검색 → 최대 10개 선택 → Apply selection.
CloudWatch Logs 데이터 소스 선택을 특정 로그 그룹이나 Name prefix·All log groups 쿼리 범위와 결합할 수 있어요. Monitoring account 배지가 있으면 선택기는 모니터링 계정과 그 링크된 소스 계정의 데이터 소스를 포함합니다.
CloudWatch 데이터 소스는 선택한 CloudWatch Logs 데이터 소스를 Logs Insights QL과 OpenSearch PPL 쿼리에 자동 추가합니다.

참고: Logs Insights QL, OpenSearch PPL, OpenSearch SQL 사용 시 반드시 리전을 지정하고 로그 그룹 선택, CloudWatch Logs 데이터 소스 선택, 또는 지원되는 로그 그룹 쿼리 범위 선택으로 쿼리할 로그를 정의해야 합니다. OpenSearch SQL에서는 여러 방식으로 로그 그룹을 지정할 수 있습니다.

View in CloudWatch console 클릭 시 CloudWatch Logs Insights 콘솔에서 로그 데이터를 대화형으로 보기·검색·분석할 수 있습니다.

OpenSearch SQL로 로그 그룹·데이터 소스 쿼리:

$__source 매크로는 쿼리 편집기에서 선택한 로그 그룹과 CloudWatch Logs 데이터 소스를 자동으로 참조합니다. 두 유형의 선택을 UI로 관리할 수 있어 권장되는 접근이에요.

SELECT window.start, COUNT(*) AS exceptionCount
FROM `$__source`
WHERE `@message` LIKE '%Exception%'

$__source 매크로는 UI에서 선택한 로그 그룹·데이터 소스의 적절한 구문으로 확장됩니다. 또는 단일 로그 그룹을 FROM 절에 직접 수동 지정할 수 있습니다:

SELECT window.start, COUNT(*) AS exceptionCount
FROM `log_group`
WHERE `@message` LIKE '%Exception%'

여러 로그 그룹 쿼리 시 반드시 logGroups(logGroupIdentifier: [...]) 구문을 사용합니다:

SELECT window.start, COUNT(*) AS exceptionCount
FROM `logGroups(logGroupIdentifier: ['LogGroup1', 'LogGroup2'])`
WHERE `@message` LIKE '%Exception%'

모니터링 계정의 로그 그룹 참조 시 LogGroup 이름 대신 ARN을 사용하세요. stats 명령으로 시계열 데이터를 반환하는 쿼리도 작성할 수 있어요. Explore에서 stats 쿼리를 만들 때는 Metrics Explore 모드에 있는지 확인하세요.

알림용 쿼리 만들기 (Create queries for alerting)

알림은 숫자 데이터를 반환하는 쿼리가 필요하며, CloudWatch Logs가 지원합니다. 예를 들어 stats 명령으로 알림을 활성화할 수 있습니다. "Exception" 텍스트가 포함된 메시지에 알림하는 유효한 쿼리:

filter @message like /Exception/
    | stats count(*) as exceptionCount by bin(1h)
    | sort exceptionCount desc

참고: 쿼리 알림 시 input data must be a wide series but got ... 같은 오류가 발생하면, 쿼리가 Time series 패널로 출력할 수 있는 유효한 숫자 데이터를 반환하는지 확인하세요. Grafana 알림에 대한 자세한 내용은 Alerting 참고.

일반 사용 사례 (Common use cases)

EC2 플릿 모니터링: AWS/EC2 CPUUtilization Metric Search 쿼리 + InstanceId 차원 와일드카드(*) + Match Exact 비활성화. 플릿이 확장되면 그래프에 새 인스턴스 자동 포함.
Lambda 오류·호출 추적: AWS/Lambda 네임스페이스에서 Errors·Invocations 메트릭 쿼리 후 errors / invocations * 100 같은 metric math 표현식으로 오류율 차팅.
가장 바쁜 리소스 순위: ORDER BY와 LIMIT가 있는 Metrics Insights 쿼리로 메트릭 기준 상위 N 리소스 반환(예: 평균 CPU가 가장 높은 10개 EC2 인스턴스).
애플리케이션 오류 조사: filter와 stats가 있는 CloudWatch Logs 쿼리로 시간 경과 오류 수 계산 후 같은 대시보드의 메트릭 패널과 상관 관계.
로그 오류율 알림: stats 명령으로 숫자 데이터를 반환하는 Logs 쿼리를 만들고 결과에 알림 규칙 생성. Create queries for alerting 참고.

계정 간 옵저버빌리티 (Cross-account observability)

CloudWatch 플러그인은 한 리전 내 여러 계정에 걸친 애플리케이션을 모니터링·문제 해결합니다. 계정 간 옵저버빌리티로 계정 경계를 넘어 메트릭·로그를 원활히 검색·시각화·분석할 수 있어요. 활성화하려면:

Amazon CloudWatch 문서로 이동해 계정 간 옵저버빌리티 활성화 지침을 따릅니다.
플러그인을 실행하는 역할/사용자에 연결된 IAM 정책에 두 개의 API 작업을 추가합니다.

계정 간 쿼리는 플러그인에서 Logs, Metric search, Metric Insights 모드로 사용할 수 있습니다. 구성 후 쿼리 편집기 헤더에 Monitoring account 배지가 표시됩니다.

쿼리 캐싱 (Query caching)

쿼리·리소스 캐싱을 활성화하면 Grafana가 데이터 소스 쿼리·리소스 요청 결과를 임시 저장합니다. 쿼리 캐싱은 Grafana Cloud와 Grafana Enterprise의 CloudWatch Metrics에서 사용 가능하며, AWS에서 쿼리 결과를 폴링하는 방식 때문에 CloudWatch Logs Insights에서는 사용할 수 없어요.

Amazon CloudWatch 쿼리 편집기