PromQL 쿼리
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 범위 | 필드 접두사 | 속성 접두사 | 예제 |
|---|---|---|---|
리소스 |
|
|
|
계측 범위 |
|
|
|
데이터 포인트 |
|
|
|
AWS 예약 |
해당 사항 없음 |
|
|
PromQL을 사용하여 벤딩 AWS 지표 쿼리
PromQL에서 벤딩 AWS 지표를 쿼리하려면 먼저 벤딩 지표의 OTel 보강을 활성화해야 합니다. 참조: PromQL에서 벤딩 지표 활성화.
OTel 보강을 활성화하면 추가 레이블을 사용하여 PromQL을 통해 벤딩 AWS 지표를 쿼리할 수 있습니다. 지표 이름은 원본 CloudWatch 지표 이름과 동일하고, 원본 CloudWatch 차원은 데이터 포인트 속성으로 사용할 수 있습니다. 다음 레이블을 사용할 수 있습니다(아래 예제는 EC2 인스턴스에 해당됨).
| PromQL 레이블 | 설명 | 예제 |
|---|---|---|
|
원본 CloudWatch 차원, 데이터 포인트 속성 |
|
|
리소스의 전체 ARN |
|
|
클라우드 공급자 |
|
|
이 지표가 시작된 AWS 리전 |
|
|
이 지표가 시작된 AWS 계정 ID |
|
|
소스 서비스를 식별하는 계측 범위 이름 |
|
|
소스 서비스 식별자 |
|
|
보강 솔루션 식별자 |
|
|
AWS 리소스 태그 |
|
|
이 지표가 수집된 AWS 계정(시스템 레이블) |
|
|
이 지표가 수집된 AWS 리전(시스템 레이블) |
|
다음 예제에서는 특정 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"})
