# PromQL을 사용하여 지표 쿼리
**Topics**
+ [PromQL(Prometheus Query Language)이란 무엇입니까?](#CloudWatch-PromQL-WhatIs)
+ [PromQL 한도 및 제한 사항](#CloudWatch-PromQL-Limits)
+ [지원되는 AWS 리전](#CloudWatch-PromQL-Regions)
+ [PromQL에 대한 IAM 권한](#CloudWatch-PromQL-IAM)
+ [PromQL 쿼리](CloudWatch-PromQL-Querying.md)
+ [Query Studio에서 PromQL 쿼리 실행(미리 보기)](CloudWatch-PromQL-QueryStudio.md)
+ [경보에서 PromQL 사용](CloudWatch-PromQL-Alarms.md)
**참고**
OTLP 지표 수집, PromQL 쿼리, 벤딩 AWS 지표의 OTel 보강 및 Query Studio는 공개 미리 보기 릴리스 상태로, 무료이면서 기능이 변경될 수 있습니다.
## PromQL(Prometheus Query Language)이란 무엇입니까?
PromQL(Prometheus Query Language)은 시계열 데이터를 실시간으로 선택, 집계 및 변환할 수 있는 기능 쿼리 언어입니다. PromQL은 원래 Prometheus용으로 설계되었으며 지표에 널리 사용되는 쿼리 언어가 되었습니다.
Amazon CloudWatch는 OTLP(OpenTelemetry Line Protocol)를 통해 수집된 지표와 [AWS 보강 벤딩 지표](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html)를 포함한 지표 쿼리에 PromQL을 지원합니다. OTLP 지표를 수집할 때 CloudWatch는 리소스 속성, 계측 범위, 데이터 포인트 속성 및 AWS 관련 메타데이터를 포함하여 텔레메트리의 전체 시맨틱 구조를 보존하고 쿼리 가능한 PromQL 레이블로 노출합니다.
PromQL을 사용하면 다음 작업이 가능합니다.
+ 지표 이름 및 레이블 매처를 기준으로 시계열을 선택합니다.
+ 시계열에 수학 함수와 연산자를 적용합니다.
+ 서비스, 리전 또는 계정과 같은 차원에서 지표를 집계합니다.
+ 비율, 히스토그램, 분위수 및 이동 평균을 계산합니다.
[Query Studio에서 PromQL 쿼리 실행(미리 보기)](CloudWatch-PromQL-QueryStudio.md)에서 PromQL 쿼리를 대화형으로 사용하고 CloudWatch 경보를 생성할 수도 있습니다. 자세한 내용은 [PromQL 쿼리](CloudWatch-PromQL-Querying.md) 및 [경보에서 PromQL 사용](CloudWatch-PromQL-Alarms.md)(을)를 참조하세요.
**참고**
CloudWatch는 Prometheus 3.0 사양을 기반으로 PromQL을 사용합니다. 여기에는 UTF-8 지표 이름 및 레이블 이름 지원이 포함됩니다.
다음 개념은 CloudWatch에서의 PromQL 사용과 관련된 기본 개념입니다.
| 개념 | 설명 |
| --- | --- |
| **시계열** | 지표 이름과 *레이블*이라는 키-값 페어 세트로 식별되는 타임스탬프 값 스트림입니다. 각각의 고유한 지표 이름과 레이블의 조합은 고유한 시계열을 형성합니다. |
| **인스턴트 벡터** | 각 시리즈에 대한 단일 샘플을 포함하는 시계열 세트로, 모두 동일한 타임스탬프를 공유합니다. `{"http.server.active_requests", "@resource.service.name"="myservice"}`와 같은 쿼리에서 반환됩니다. |
| **범위 벡터** | 각 시리즈의 시간 경과에 따른 데이터 포인트 범위를 포함하는 시계열 세트입니다. 대괄호로 된 기간 선택기(예: `avg_over_time({"http.server.active_requests", "@resource.service.name"="myservice"}[5m])`)를 추가하여 생성됩니다. |
| **Label** | 시계열에 연결된 키-값 페어입니다. OTLP 수집 지표에서 레이블은 리소스 속성, 계측 범위, 데이터 포인트 속성 및 AWS 관련 메타데이터로부터 파생됩니다. |
| **레이블 매처** | 레이블 값을 기준으로 시계열을 필터링하는 중괄호 안의 표현식입니다. 정확히 일치(`=`), 동일하지 않음(`!=`), 정규식 일치(`=~`) 및 부정 정규식 일치(`!~`)를 지원합니다. |
| **집계 연산자** | 여러 시계열을 더 적은 수의 시계열로 결합하는 함수입니다. 일반적인 연산자로는 `sum`, `avg`, `min`, `max`, `count`, `topk`가 있습니다. |
## PromQL 한도 및 제한 사항
다음 표에는 PromQL에 대한 한도 및 제한 사항이 나와 있습니다.
| Limit | 값 | 추가 정보 | 오류 코드 |
| --- | --- | --- | --- |
| 계정당 쿼리 요청에 대한 최대 TPS | 300 | 계정당 허용되는 초당 최대 쿼리 요청(/query, /query\$1range) 수입니다. | 422 |
| 계정당 검색 요청에 대한 최대 TPS | 10 | 계정당 허용되는 초당 최대 검색 요청(/series, /label, /label\$1values) 수입니다. | 422 |
| 계정당 최대 동시 쿼리 요청 수 | 30 | 계정에서 동시에 실행할 수 있는 최대 쿼리(/query, /query\$1range) 수입니다. | 429 |
| 계정당 최대 동시 검색 요청 수 | 30 | 계정에서 동시에 실행할 수 있는 최대 검색 요청(/series, /labels, /label\$1values) 수입니다. | 429 |
| 쿼리 요청당 반환되는 최대 시리즈 | 500 | 쿼리 요청(/query, /query\$1range)으로 반환될 수 있는 고유한 시계열의 최대 수입니다. | 200 - 응답 잘림 |
| 검색 요청당 반환되는 최대 레이블 수 | 10,000개 | 검색 요청(/series, /labels, /label\$1values)에서 반환될 수 있는 고유 레이블의 최대 수입니다. | 200 - 응답 잘림 |
| 요청당 최대 범위 | 7일 | 범위 파라미터 및 룩백 기간을 포함하여 쿼리가 포함할 수 있는 최대 시간 범위입니다. | 422 |
| 24시간 기간당 스캔된 최대 시리즈 | 100,000건 | 쿼리 실행 24시간 기간당 스캔할 수 있는 고유 시계열의 최대 수입니다. | 422 |
| 24시간 기간당 스캔된 최대 샘플 | 300,000,000 | 쿼리 실행 24시간 기간당 스캔할 수 있는 샘플의 최대 수입니다. | 422 |
| 24시간 기간당 처리된 최대 샘플 | 3,000,000,000 | 쿼리 실행 24시간 기간당 처리할 수 있는 샘플의 최대 수입니다. | 422 |
| 실행 제한 시간 | 20초 | 대기열에서 보낸 시간과 스토리지에서 데이터를 가져오는 시간을 제외하고 엔진이 쿼리를 평가하는 데 사용할 수 있는 최대 시간입니다. | 422 |
## 지원되는 AWS 리전
다음 표에는 OTLP 지표 수집, PromQL 쿼리 및 Query Studio를 사용할 수 있는 AWS 리전이 나와 있습니다.
| 리전 이름 | 리전 코드 | OTLP 지표 수집 | PromQL 쿼리 | Query Studio |
| --- | --- | --- | --- | --- |
| 미국 동부(버지니아 북부) | us-east-1 | ✓ | ✓ | ✓ |
| 미국 서부(오리건) | us-west-2 | ✓ | ✓ | ✓ |
| 유럽(아일랜드) | eu-west-1 | ✓ | ✓ | ✓ |
| 아시아 태평양(싱가포르) | ap-southeast-1 | ✓ | ✓ | ✓ |
| 아시아 태평양(시드니) | ap-southeast-2 | ✓ | ✓ | ✓ |
## PromQL에 대한 IAM 권한
PromQL 쿼리를 실행하려면 `cloudwatch:GetMetricData` 및 `cloudwatch:ListMetrics` 권한이 모두 필요합니다. 다음 표에는 새로운 PromQL API 작업과 필요한 IAM 작업이 나와 있습니다.
| API 작업 | 필수 작업 |
| --- | --- |
| ExecuteMetricQueryPost | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` |
| ExecuteMetricQueryGet | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` |
| ExecuteMetricRangeQuery | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` |
| ExecuteMetricRangeQueryGet | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` |
| ExecuteMetricSeriesPost | `cloudwatch:ListMetrics` |
| ExecuteMetricSeriesGet | `cloudwatch:ListMetrics` |
| ExecuteMetricLabelsPost | `cloudwatch:ListMetrics` |
| ExecuteMetricLabelsGet | `cloudwatch:ListMetrics` |
| ExecuteMetricLabelValuesGet | `cloudwatch:ListMetrics` |