# PromQL 쿼리
<a name="CloudWatch-PromQL-Querying"></a>

OTLP(OpenTelemetry Protocol)를 통해 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 지표 쿼리
<a name="CloudWatch-PromQL-Querying-Vended"></a>

PromQL에서 벤딩 AWS 지표를 쿼리하려면 먼저 벤딩 지표의 OTel 보강을 활성화해야 합니다. 참조: [PromQL에서 벤딩 지표 활성화](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`를 선택합니다.

```
histogram_sum({Invocations, FunctionName="my-api-handler"})
```

다음 예제에서는 특정 팀으로 태그가 지정된 모든 함수에 대해 Lambda `Errors`를 선택합니다.

```
histogram_sum(
  {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"})
```