PromQL 쿼리
지표 엔드포인트를 통해 OpenTelemetry 지표를 CloudWatch에 수집하면 계층적 OTLP 데이터 모델이 PromQL 호환 레이블로 평면화됩니다. 이 섹션에서는 레이블 구조, 이러한 레이블을 쿼리하기 위한 PromQL 구문 및 PromQL의 UTF-8 지원에 대해 설명합니다.
참고
Prometheus 3의 PromQL은 지표 이름 및 레이블 이름에서 전체 UTF-8 문자를 지원합니다. OpenTelemetry 시맨틱 규칙은 service.name과 같은 속성 이름에 점을 사용하기 때문에 이는 OTLP 지표에 있어 특히 중요합니다. 이전에는 변환 중에 이러한 점이 밑줄로 대체되어 OTel 규칙에 정의된 것과 Prometheus에서 쿼리 가능한 것 사이에 불일치가 발생했습니다.
CloudWatch에서 PromQL을 사용할 때 @ 접두사 규칙은 OTLP 범위 레이블을 표준 Prometheus 레이블과 구분합니다. 각 범위 내의 필드는 이중 @ 접두사(예: @resource.@schema_url)를 사용하는 반면 속성은 @resource.service.name와 같은 단일 @ 범위 접두사를 사용합니다. 또한 데이터 포인트 속성은 표준 PromQL 쿼리와의 역호환성을 위해 베어(접두사 없음) 액세스를 지원하는데, 예를 들어 {"http.server.active_requests"}와 {"@datapoint.@name"="http.server.active_requests"}는 동일합니다.
PromQL 표현식은 지표 이름과 선택 사항인 레이블 매처 세트를 지정하는 중괄호로 묶여 있습니다. 다음 예제에서는 http.server.active_requests 지표에 대한 모든 시계열을 선택합니다.
{"http.server.active_requests"}
다음 예제에서는 OpenTelemetry 리소스 속성 service.name이 myservice와 동일한 http.server.active_requests 지표의 모든 시계열을 선택합니다.
{"http.server.active_requests", "@resource.service.name"="myservice"}
단일 쿼리에서 여러 개의 레이블 매처를 결합할 수 있습니다. 다음 예제에서는 모든 미국 리전에서 OpenTelemetry 리소스 속성 service.name이 myservice와 동일한 http.server.active_requests 지표의 모든 시계열을 선택합니다.
{"http.server.active_requests", "@resource.service.name"="myservice", "@aws.region"=~"us-.*"}
다음 예제에서는 쿼리 범위를 보여줍니다. 각 시계열에 대해 지정된 시간 범위 내에 있는 모든 데이터 포인트의 평균값을 계산합니다.
avg_over_time( {"http.server.active_requests", "@resource.service.name"="myservice"}[5m] )
다음 표에는 각 OTLP 범위에 대한 접두사 규칙이 요약되어 있습니다.
| OTLP 범위 | 필드 접두사 | 속성 접두사 | 예제 |
|---|---|---|---|
리소스 |
|
|
|
계측 범위 |
|
|
|
데이터 포인트 |
|
|
|
AWS 예약 |
해당 사항 없음 |
|
|
PromQL을 사용하여 벤딩 AWS 지표 쿼리
PromQL에서 벤딩 AWS 지표를 쿼리하려면 먼저 벤딩 지표의 OTel 보강을 활성화해야 합니다. 참조: OpenTelemetry 형식의 AWS 발급 지표.
OTel 보강을 활성화하면 추가 레이블을 사용하여 PromQL을 통해 벤딩 AWS 지표를 쿼리할 수 있습니다. 지표 이름은 원본 CloudWatch 지표 이름과 동일하고, 원본 CloudWatch 차원은 데이터 포인트 속성으로 사용할 수 있습니다. 다음 레이블을 사용할 수 있습니다(아래 예제는 EC2 인스턴스에 해당됨).
| PromQL 레이블 | 설명 | 예제 |
|---|---|---|
|
원본 CloudWatch 차원, 데이터 포인트 속성 |
|
|
리소스의 전체 ARN |
|
|
클라우드 공급자 |
|
|
이 지표가 시작된 AWS 리전 |
|
|
이 지표가 시작된 AWS 계정 ID |
|
|
소스 서비스를 식별하는 계측 범위 이름 |
|
|
소스 서비스 식별자 |
|
|
보강 솔루션 식별자 |
|
|
AWS 리소스 태그 |
|
|
이 지표가 수집된 AWS 계정(시스템 레이블) |
|
|
이 지표가 수집된 AWS 리전(시스템 레이블) |
|
다음 예제에서는 특정 Lambda 함수에 대해 Invocations를 선택합니다.
{Invocations, FunctionName="my-api-handler"}
다음 예제에서는 특정 팀으로 태그가 지정된 모든 함수에 대해 Lambda Errors를 선택합니다.
{Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"}
다음 예제에서는 팀별로 그룹화된 총 Lambda Invocations를 계산합니다.
sum by ("@aws.tag.Team")( {Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"} )
다음 예제에서는 EC2 CPUUtilization 지표에 대한 모든 시계열을 선택합니다. "@instrumentation.@name"="cloudwatch.aws/ec2"를 사용하면 Amazon Relational Database Service와 같은 다른 AWS 서비스가 아닌 EC2의 CPUUtilization만 일치시킵니다.
histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})
Grafana에서 쿼리
Amazon Managed Service for Prometheus 데이터 소스 플러그인을 추가하고 CloudWatch 모니터링 엔드포인트를 가리키면 Grafana에서 CloudWatch PromQL 데이터를 쿼리할 수 있습니다. SigV4 서명은 플러그인에 내장되어 있으며 항상 활성화되어 있으므로 켤 토글이 없습니다. 플러그인은 grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/>=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7
<12.2 || >=12.2.5가 필요합니다.
IAM 사전 조건 - Grafana에서 자격 증명을 사용하는 IAM 보안 주체에는 cloudwatch:GetMetricData(인스턴트 및 범위 쿼리에 필요) 및 cloudwatch:ListMetrics(시리즈 및 레이블 검색에 필요)가 모두 있어야 합니다. 자세한 내용은 PromQL에 대한 IAM 권한을 참조하세요.
Grafana를 구성하려면 다음 단계를 완료합니다.
-
Grafana 플러그인 카탈로그에서 Amazon Managed Service for Prometheus 데이터 소스 플러그인을 설치합니다.
-
Grafana에서 연결, 데이터 소스로 이동하여 데이터 소스 추가를 선택하고 Amazon Managed Service for Prometheus를 선택합니다.
-
데이터 소스 URL을
https://monitoring.으로 설정합니다.AWS Region.amazonaws.com -
리전을 해당 AWS 리전으로 설정합니다. 환경에 적합한 인증 공급자(기본 자격 증명 체인, 액세스 키 또는 작업 영역 IAM 역할)를 선택합니다.
-
저장 및 테스트를 선택하세요.
Amazon Managed Grafana에서 쿼리
CloudWatch 모니터링 엔드포인트를 가리키는 Amazon Managed Service for Prometheus 데이터 소스를 추가하여 Amazon Managed Grafana 작업 영역에서 CloudWatch PromQL 데이터를 쿼리할 수 있습니다. 이 데이터 소스 플러그인은 작업 영역 IAM 역할을 사용하여 SigV4로 요청에 자동으로 서명합니다. SigV4는 항상 활성화되며 구성할 수 있는 토글이 없습니다. 플러그인은 Amazon Managed Grafana 버전 12 이상에서 사용할 수 있습니다. 자세한 내용은 Amazon Managed Grafana 사용 설명서의 Amazon Managed Service for Prometheus 데이터 소스에 연결을 참조하세요.
IAM 사전 조건 - Amazon Managed Grafana 작업 영역 IAM 역할에는 cloudwatch:GetMetricData(인스턴트 및 범위 쿼리에 필요)와 cloudwatch:ListMetrics(시리즈 및 레이블 검색에 필요)가 모두 있어야 합니다. 자세한 내용은 PromQL에 대한 IAM 권한을 참조하세요.
데이터 소스를 구성하려면 다음 단계를 완료합니다.
-
Amazon Managed Grafana 작업 영역에서 Amazon Managed Service for Prometheus 데이터 소스를 추가합니다.
-
데이터 소스 URL을
https://monitoring.으로 설정합니다.AWS Region.amazonaws.com -
리전을 해당 AWS 리전으로 설정합니다. Amazon Managed Grafana는 작업 영역 IAM 역할에서 자격 증명을 자동으로 주입하므로 정적 키를 구성할 필요가 없습니다.
-
저장 및 테스트를 선택하세요.
MCP 도구를 사용한 쿼리
CloudWatch MCP 서버
CloudWatch MCP 서버에서 사용할 수 있는 PromQL 도구는 다음과 같습니다.
| 도구 | 설명 |
|---|---|
|
인스턴트 PromQL 쿼리를 실행하여 단일 시점에 지표 값을 반환합니다. |
|
일정 기간 동안 PromQL 범위 쿼리를 실행하여 추세 분석 및 그래프 작성을 위한 시계열 데이터를 반환합니다. |
|
지표 이름의 경우 |
|
PromQL 레이블 선택기와 일치하는 시계열을 찾고 일치하는 각 시리즈의 전체 레이블 세트를 반환합니다. |
|
지표의 레이블 구조를 검색하는 데 도움이 되는 사용 가능한 모든 PromQL 레이블 이름을 나열합니다. |
파라미터, 구성 및 설정 지침에 대한 자세한 내용은 CloudWatch MCP 서버 설명서의 CloudWatch PromQL용 도구
HTTP API를 사용한 쿼리
Prometheus 호환 HTTP 엔드포인트를 직접 호출하여 프로그래밍 방식으로 CloudWatch PromQL 데이터를 쿼리할 수도 있습니다. 요청은 monitoring을 서비스 이름으로 사용하여 AWS Signature Version 4로 서명해야 합니다.
PromQL 엔드포인트는 https://monitoring. 패턴을 따릅니다. 예를 들어 미국 동부(버지니아 북부)(us-east-1) 리전의 경우 인스턴트 쿼리의 엔드포인트는 AWS
Region.amazonaws.com/api/v1/operationhttps://monitoring.us-east-1.amazonaws.com/api/v1/query입니다.
지원되는 작업, 요청 파라미터 및 응답 형식을 포함한 전체 API 참조는 Prometheus 호환 API 섹션을 참조하세요. PromQL 쿼리를 사용할 수 있는 AWS 리전 목록은 지원되는 AWS 리전 섹션을 참조하세요. 각 작업에 필요한 IAM 작업은 PromQL에 대한 IAM 권한 섹션을 참조하세요.
