# PromQL 쿼리
[지표 엔드포인트](CloudWatch-OTLPEndpoint.md#CloudWatch-MetricsEndpoint)를 통해 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 범위 | 필드 접두사 | 속성 접두사 | 예제 |
| --- | --- | --- | --- |
| 리소스 | `@resource.@` | `@resource.` | `@resource.service.name="myservice"` |
| 계측 범위 | `@instrumentation.@` | `@instrumentation.` | `@instrumentation.@name="otel-go/metrics"` |
| 데이터 포인트 | `@datapoint.@` | `@datapoint.` 또는 베어 | `cpu="cpu0"` 또는 `@datapoint.cpu="cpu0"` |
| AWS 예약 | 해당 사항 없음 | `@aws.` | `@aws.account_id="123456789"` |
## PromQL을 사용하여 벤딩 AWS 지표 쿼리
PromQL에서 벤딩 AWS 지표를 쿼리하려면 먼저 벤딩 지표의 OTel 보강을 활성화해야 합니다. 참조: [OpenTelemetry 형식의 AWS 발급 지표](CloudWatch-OTelEnrichment.md).
OTel 보강을 활성화하면 추가 레이블을 사용하여 PromQL을 통해 벤딩 AWS 지표를 쿼리할 수 있습니다. 지표 이름은 원본 CloudWatch 지표 이름과 동일하고, 원본 CloudWatch 차원은 데이터 포인트 속성으로 사용할 수 있습니다. 다음 레이블을 사용할 수 있습니다(아래 예제는 EC2 인스턴스에 해당됨).
| PromQL 레이블 | 설명 | 예제 |
| --- | --- | --- |
| `InstanceId` | 원본 CloudWatch 차원, 데이터 포인트 속성 | `i-0123456789abcdef0` |
| `"@resource.cloud.resource_id"` | 리소스의 전체 ARN | `arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0` |
| `"@resource.cloud.provider"` | 클라우드 공급자 | `aws` |
| `"@resource.cloud.region"` | AWS이 지표가 시작된 리전 | `us-east-1` |
| `"@resource.cloud.account.id"` | AWS이 지표가 시작된 계정 ID | `123456789012` |
| `"@instrumentation.@name"` | 소스 서비스를 식별하는 계측 범위 이름 | `cloudwatch.aws/ec2` |
| `"@instrumentation.cloudwatch.source"` | 소스 서비스 식별자 | `aws.ec2` |
| `"@instrumentation.cloudwatch.solution"` | 보강 솔루션 식별자 | `CloudWatchOTelEnrichment` |
| `"@aws.tag.Environment"` | AWS 리소스 태그 | `production` |
| `"@aws.account"` | AWS이 지표가 수집된 계정(시스템 레이블) | `123456789012` |
| `"@aws.region"` | AWS이 지표가 수집된 리전(시스템 레이블) | `us-east-1` |
다음 예제에서는 특정 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/](https://grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/)에 게시됩니다. 데이터 소스를 추가하기 전에 Grafana 플러그인 카탈로그에서 설치합니다. AMP 플러그인 v3.0.0에는 Grafana `>=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 권한](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)을 참조하세요.
Grafana를 구성하려면 다음 단계를 완료합니다.
1. Grafana 플러그인 카탈로그에서 **Amazon Managed Service for Prometheus** 데이터 소스 플러그인을 설치합니다.
1. Grafana에서 **연결**, **데이터 소스**로 이동하여 **데이터 소스 추가**를 선택하고 **Amazon Managed Service for Prometheus**를 선택합니다.
1. 데이터 소스 **URL**을 `https://monitoring.{{AWS Region}}.amazonaws.com`으로 설정합니다.
1. **리전**을 해당 AWS 리전으로 설정합니다. 환경에 적합한 **인증 공급자**(기본 자격 증명 체인, 액세스 키 또는 작업 영역 IAM 역할)를 선택합니다.
1. **저장 및 테스트**를 선택하세요.
## 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 데이터 소스에 연결](https://docs.aws.amazon.com/grafana/latest/userguide/amazon-prometheus-data-source.html)을 참조하세요.
**IAM 사전 조건** - Amazon Managed Grafana 작업 영역 IAM 역할에는 `cloudwatch:GetMetricData`(인스턴트 및 범위 쿼리에 필요)와 `cloudwatch:ListMetrics`(시리즈 및 레이블 검색에 필요)가 모두 있어야 합니다. 자세한 내용은 [PromQL에 대한 IAM 권한](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)을 참조하세요.
데이터 소스를 구성하려면 다음 단계를 완료합니다.
1. Amazon Managed Grafana 작업 영역에서 **Amazon Managed Service for Prometheus 데이터 소스**를 추가합니다.
1. 데이터 소스 **URL**을 `https://monitoring.{{AWS Region}}.amazonaws.com`으로 설정합니다.
1. **리전**을 해당 AWS 리전으로 설정합니다. Amazon Managed Grafana는 작업 영역 IAM 역할에서 자격 증명을 자동으로 주입하므로 정적 키를 구성할 필요가 없습니다.
1. **저장 및 테스트**를 선택하세요.
## MCP 도구를 사용한 쿼리
[CloudWatch MCP 서버](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/)는 AI 어시스턴트와 개발 도구가 사용자를 대신하여 CloudWatch PromQL 데이터를 쿼리할 수 있는 Model Context Protocol(MCP) 도구를 제공합니다. MCP 도구는 인증 및 요청 형식을 자동으로 처리하므로 HTTP 요청 및 SigV4 서명을 관리하는 대신 PromQL 쿼리를 작성하는 데 집중할 수 있습니다.
CloudWatch MCP 서버에서 사용할 수 있는 PromQL 도구는 다음과 같습니다.
| 도구 | 설명 |
| --- | --- |
| `execute_promql_query` | 인스턴트 PromQL 쿼리를 실행하여 단일 시점에 지표 값을 반환합니다. |
| `execute_promql_range_query` | 일정 기간 동안 PromQL 범위 쿼리를 실행하여 추세 분석 및 그래프 작성을 위한 시계열 데이터를 반환합니다. |
| `get_promql_label_values` | 지표 이름의 경우 `__name__`, 서비스의 경우 `@resource.service.name`과 같은 특정 PromQL 레이블의 값을 검색합니다. |
| `get_promql_series` | PromQL 레이블 선택기와 일치하는 시계열을 찾고 일치하는 각 시리즈의 전체 레이블 세트를 반환합니다. |
| `get_promql_labels` | 지표의 레이블 구조를 검색하는 데 도움이 되는 사용 가능한 모든 PromQL 레이블 이름을 나열합니다. |
파라미터, 구성 및 설정 지침에 대한 자세한 내용은 CloudWatch MCP 서버 설명서의 [CloudWatch PromQL용 도구](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server#tools-for-cloudwatch-promql)를 참조하세요.
## HTTP API를 사용한 쿼리
Prometheus 호환 HTTP 엔드포인트를 직접 호출하여 프로그래밍 방식으로 CloudWatch PromQL 데이터를 쿼리할 수도 있습니다. 요청은 `monitoring`을 서비스 이름으로 사용하여 [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)로 서명해야 합니다.
PromQL 엔드포인트는 `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/{{operation}}` 패턴을 따릅니다. 예를 들어 미국 동부(버지니아 북부)(us-east-1) 리전의 경우 인스턴트 쿼리의 엔드포인트는 `https://monitoring.us-east-1.amazonaws.com/api/v1/query`입니다.
지원되는 작업, 요청 파라미터 및 응답 형식을 포함한 전체 API 참조는 [Prometheus 호환 API](CloudWatch-PromQL-APIs.md) 섹션을 참조하세요. PromQL 쿼리를 사용할 수 있는 AWS 리전 목록은 [지원되는 AWS 리전](CloudWatch-PromQL.md#CloudWatch-PromQL-Regions) 섹션을 참조하세요. 각 작업에 필요한 IAM 작업은 [PromQL에 대한 IAM 권한](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM) 섹션을 참조하세요.