Cloud Monitoring 측정항목에 PromQL 사용

Prometheus Query Language(PromQL)를 사용하여 Google Cloud 시스템 측정항목, Kubernetes 측정항목, 커스텀 측정항목, 로그 기반 측정항목을 포함하여 Cloud Monitoring에서 모든 측정항목을 쿼리할 수 있습니다.

Cloud Monitoring 측정항목 이름을 PromQL에 매핑

Cloud Monitoring 측정항목 이름에는 도메인(예: compute.googleapis.com/)과 경로(예: instance/disk/max_read_ops_count)의 두 가지 구성요소가 있습니다. PromQL은 특수문자 : 및 _만 지원하므로 먼저 Monitoring 측정항목 이름을 PromQL과 호환되도록 해야 합니다. Monitoring 측정항목 이름을 PromQL에 매핑하려면 다음 규칙을 적용합니다.

첫 번째 /를 :으로 바꿉니다.
다른 모든 특수문자(. 및 기타 / 문자 포함)를 _로 바꿉니다.

다음 표에는 몇 가지 측정항목 이름과 해당하는 PromQL이 나열되어 있습니다.

Cloud Monitoring 측정항목 이름	PromQL 측정항목 이름
`kubernetes.io/container/cpu/limit_cores`	`kubernetes_io:container_cpu_limit_cores`
`compute.googleapis.com/instance/cpu/utilization`	`compute_googleapis_com:instance_cpu_utilization`
`logging.googleapis.com/log_entry_count`	`logging_googleapis_com:log_entry_count`
`custom.googleapis.com/opencensus/opencensus.io/ http/server/request_count_by_method`	`custom_googleapis_com:opencensus_opencensus_io_ http_server_request_count_by_method`
`agent.googleapis.com/disk/io_time`	`agent_googleapis_com:disk_io_time`

Cloud Monitoring 분포 값 측정항목은 측정항목 이름에 _count, _sum 또는 _bucket 서픽스가 추가된 Prometheus 히스토그램처럼 쿼리될 수 있습니다.

Cloud Monitoring 측정항목 이름	PromQL 측정항목 이름
`networking.googleapis.com/vm_flow/rtt`	`networking_googleapis_com:vm_flow_rtt_sum` `networking_googleapis_com:vm_flow_rtt_count` `networking_googleapis_com:vm_flow_rtt_bucket`

모니터링 리소스 유형 지정

측정항목이 단일 Cloud Monitoring 모니터링 리소스 유형에만 연결된 경우 PromQL 쿼리는 리소스 유형을 수동으로 지정하지 않고도 작동합니다. 하지만 일부 시스템 측정항목과 로그 기반 측정항목에 의해 생성된 측정항목을 포함하여 Cloud Monitoring 내 일부 측정항목은 리소스 유형 두 개 이상에 매핑됩니다.

다음 중 하나를 수행하여 측정항목에 매핑되는 모니터링 리소스 유형을 확인할 수 있습니다.

Google에서 선별한 측정항목의 경우 Google Cloud 측정항목과 Kubernetes 측정항목을 포함한 사용 가능한 측정항목 목록을 참조할 수 있습니다. 문서의 각 항목에는 연결된 모니터링 리소스 유형이 유형 아래의 각 항목의 첫 번째 열에 나열됩니다. 모니터링 리소스 유형이 나열되지 않으면 측정항목을 모든 유형에 연결할 수 있습니다.
측정항목 탐색기에서 다음을 수행할 수 있습니다.
1. 측정항목 선택 필드에 측정항목 이름을 입력한 후 메뉴를 탐색하여 측정항목을 선택합니다. 리소스 메뉴에는 해당 측정항목에 유효한 리소스 유형이 나열됩니다(예: 'VM 인스턴스').
2. 쿼리 빌더 창의 툴바에서 이름이 MQL 또는 PromQL인 버튼을 선택합니다.
3. MQL 전환 버튼에 MQL이 선택되어 있는지 확인합니다. 언어 전환 버튼은 쿼리 형식을 지정할 수 있는 동일한 툴바에 있습니다.
  
  표시된 쿼리는 리소스 유형을 보여줍니다. 특히 MQL은 많은 모니터링 리소스 유형(예: 로그 기반 측정항목, 커스텀 측정항목, 모든 사용자 정의 측정항목)과 연결할 수 있는 측정항목에 유용합니다.

측정항목이 리소스 유형 2개 이상과 연결되어 있는 경우 PromQL 쿼리에서 리소스 유형을 지정해야 합니다. 리소스 유형을 선택하는 데 사용할 수 있는 특수 라벨 monitored_resource가 있습니다.

모니터링 리소스 유형은 대부분의 경우 gce_instance와 같은 짧은 문자열이지만 monitoring.googleapis.com/MetricIngestionAttribution과 같이 전체 URI로 표시되는 경우도 있습니다. 올바른 형식의 PromQL 쿼리는 다음과 같습니다.

logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
custom_googleapis_com:opencensus_opencensus_io_http_server_request_count_by_method{monitored_resource="global"}
loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

monitored_resource 라벨의 "" 값은 특수하며 Prometheus용 관리형 서비스 측정항목에 사용되는 기본 prometheus_target 리소스 유형을 참조합니다.

필요할 때 monitored_resource 라벨을 사용하지 않으면 다음 오류가 발생합니다.

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

메타데이터 라벨 사용

PromQL에서는 다른 라벨과 마찬가지로 메타데이터 라벨을 사용할 수 있지만 측정항목 이름처럼 메타데이터 라벨을 PromQL과 호환되도록 지정해야 합니다. 메타데이터 시스템 라벨 version을 참조하는 구문은 metadata_system_version이고 메타데이터 사용자 라벨 version의 구문은 metadata_user_version입니다. 메타데이터 라벨을 사용하는 올바른 형식의 PromQL 쿼리는 다음과 같습니다.

compute_googleapis_com:instance_cpu_utilization{monitored_resource="gce_instance",metadata_user_env="prod"}
sum(compute_googleapis_com:instance_cpu_utilization) by (metadata_system_region)

메타데이터 라벨 키에 사용할 수 있는 유일한 특수문자는 _ 문자입니다. MULTI_STRING 또는 KEY_VALUE 유형의 메타데이터 라벨을 사용하는 집계는 지원되지 않습니다.

라벨 충돌 해결

Cloud Monitoring에서 라벨은 측정항목이나 리소스에 속할 수 있습니다. 측정항목 라벨에 리소스 라벨과 동일한 키 이름이 있으면 쿼리의 라벨 키 이름에 metric_ 프리픽스를 추가하여 구체적으로 측정항목 라벨을 참조할 수 있습니다.

예를 들어 example.googleapis.com/user/widget_count 측정항목에 pod_name이라는 리소스 라벨과 측정항목 라벨이 있다고 가정해 보겠습니다.

리소스 라벨 값을 필터링하려면
example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}를 사용합니다.
측정항목 라벨 값을 필터링하려면
example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}를 사용합니다.

추가 주제

규칙 및 알림

Managed Service for Prometheus의 기록 규칙과 알림 규칙 모두에서 Cloud Monitoring 측정항목을 사용할 수 있습니다. 자세한 내용은 관리형 규칙 평가 및 알림 또는 자체 배포 규칙 평가 및 알림을 참조하세요.

PromQL 학습

PromQL 사용에 대한 기본사항을 학습하려면 오픈소스 문서를 참조하는 것이 좋습니다. 유용한 링크는 다음과 같습니다.

PromQL 차이점

Prometheus용 관리형 서비스의 PromQL은 업스트림 PromQL과 약간 다르게 작동할 수 있습니다. 이러한 차이점 목록은 PromQL 차이점을 참조하세요.