Cloud Monitoring용 PromQL

이 문서에서는 Cloud Monitoring에서 Prometheus Query Language(PromQL)를 사용하는 방법을 설명합니다. PromQL은 차트와 대시보드를 만들 수 있도록 측정항목 탐색기 메뉴 기반 인터페이스의 대안을 제공합니다.

PromQL을 사용하여 다음 소스에서 Cloud Monitoring 데이터를 쿼리하고 차트로 작성할 수 있습니다.

Grafana와 같은 도구를 사용하여 Cloud Monitoring에 수집된 측정항목 데이터를 차트로 표시할 수도 있습니다. 사용 가능한 측정항목에는 측정항목 목록에 설명된 Prometheus용 관리형 서비스 및 Cloud Monitoring 측정항목의 측정항목이 포함됩니다. Prometheus API를 기반으로 Grafana 및 기타 도구를 설정하는 방법은 Grafana에 대한 Prometheus용 관리형 서비스를 참조하세요.

또한 Grafana 대시보드를 Cloud Monitoring에 가져올 수 있습니다.

PromQL을 사용하여 Cloud Monitoring 측정항목 쿼리

PromQL의 UTF-8 사양을 사용하여 Cloud Monitoring 측정항목을 쿼리할 수 있습니다. UTF-8 측정항목 이름은 따옴표로 묶고 중괄호 안에 있어야 합니다. 라벨 이름에 기존 버전과 호환되지 않는 문자가 포함된 경우에도 따옴표로 묶어야 합니다. Cloud Monitoring 측정항목 kubernetes.io/container/cpu/limit_utilization의 경우 다음 쿼리는 동일합니다.

  • {"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
  • {__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
  • {"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

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

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)
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env)
  • {"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}
  • sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")

메타데이터 라벨 키에 _ 문자 이외의 특수 문자가 포함된 경우에는 PromQL UTF-8 사양에 따라 큰따옴표(")로 라벨 키를 래핑해야 합니다. 메타데이터 라벨에는 여전히 metadata_user_ 문자열을 프리픽스로 추가해야 합니다.

UTF-8 호환성 이전에 만들어진 차트와 대시보드는 이름을 기존 PromQL 호환 이름으로 변환하여 Cloud Monitoring 측정항목을 쿼리합니다. 기존 PromQL 변환 규칙에 대한 자세한 내용은 Cloud Monitoring 측정항목을 기존 PromQL에 매핑을 참고하세요.

Cloud Monitoring에서 PromQL에 액세스

Google Cloud 콘솔의 다음 페이지에 있는 코드 탭에서 PromQL을 사용할 수 있습니다.

  • 측정항목 탐색기
  • 커스텀 대시보드를 만들 때 차트 추가

편집기 액세스 및 사용 방법은 PromQL 편집기 사용을 참조하세요.

PromQL 규칙 및 알림

PromQL을 사용하여 Cloud Monitoring의 모든 측정항목에 대한 알림 정책을 만들 수 있습니다. 자세한 내용은 PromQL 기반 알림 정책을 참고하세요.

PromQL을 사용하여 Cloud Monitoring에서 Prometheus 스타일 클러스터 내 알림을 사용하여 Cloud Monitoring의 모든 측정항목에 대한 기록 및 알림 규칙을 만들 수도 있습니다. 자세한 내용은 관리형 규칙 평가 및 알림 또는 자체 배포 규칙 평가 및 알림을 참조하세요.

PromQL 학습

PromQL 사용에 대한 기본사항을 학습하려면 오픈소스 문서를 참조하는 것이 좋습니다. 다음은 시작하는 데 도움이 되는 리소스입니다.

모니터링 리소스 유형 지정

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

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

  • Google에서 선별한 측정항목의 경우 Google Cloud측정항목 및 Kubernetes 측정항목을 포함한 사용 가능한 측정항목 목록을 참조할 수 있습니다. 문서의 각 항목에는 연결된 모니터링 리소스 유형이 유형 아래의 각 항목의 첫 번째 열에 나열됩니다. 모니터링 리소스 유형이 나열되지 않으면 측정항목을 모든 유형에 연결할 수 있습니다.

  • 측정항목 탐색기에서 다음을 수행할 수 있습니다.

    1. 측정항목 선택 필드에 측정항목 이름을 입력한 후 메뉴를 탐색하여 측정항목을 선택합니다. 리소스 메뉴에는 해당 측정항목에 유효한 리소스 유형이 나열됩니다(예: 'VM 인스턴스').

    2. 쿼리 빌더 창의 툴바에서 이름이 < > PromQL인 버튼을 선택합니다.

      표시된 PromQL 쿼리는 리소스 유형을 monitored_resource 필드의 값으로 보여줍니다. 특히 이 메서드는 많은 모니터링 리소스 유형(예: 로그 기반 측정항목, 커스텀 측정항목, 모든 사용자 정의 측정항목)과 연결할 수 있는 측정항목에 유용합니다.

측정항목이 리소스 유형 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 라벨의 "" 값은 특수하며 Cloud Monitoring 측정항목에 사용되는 기본 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

라벨 충돌 해결

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"}를 사용합니다.

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

Cloud Monitoring 측정항목 이름에는 도메인(예: compute.googleapis.com/)과 경로(예: instance/disk/max_read_ops_count)의 두 가지 구성요소가 있습니다. 기존 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

PromQL 호환성

Cloud Monitoring용 PromQL은 업스트림 PromQL과 약간 다르게 작동할 수 있습니다.

Cloud Monitoring의 PromQL 쿼리는 내부 쿼리 언어를 사용하여 Monarch 백엔드에서 부분적으로 평가되며 쿼리 결과에는 몇 가지 알려진 차이점이 있습니다. 이 섹션에 나열된 차이점 외에도 Cloud Monitoring의 PromQL은 Prometheus 버전 2.44에서 사용 가능한 PromQL과 동일합니다.

Prometheus 버전 2.44 이후에 추가된 PromQL 함수는 지원되지 않을 수 있습니다.

UTF-8 지원

Cloud Monitoring용 PromQL은 UTF-8 쿼리를 지원합니다.

Prometheus 측정항목 이름이 영숫자 문자, _ 또는 : 문자로만 구성되고 라벨 키가 영숫자 문자, _ 문자로만 구성된 경우 기존 PromQL 구문을 사용하여 쿼리할 수 있습니다. 예를 들어 유효한 쿼리는 job:my_metric:sum{label_key="label_value"}와 같습니다.

하지만 Prometheus 측정항목 이름에 _ 또는 : 문자 이외의 특수 문자가 사용되거나 라벨 키에 _ 문자 이외의 특수 문자가 사용되는 경우에는 PromQL의 UTF-8 사양에 따라 쿼리를 구성해야 합니다.

UTF-8 측정항목 이름은 따옴표로 묶고 중괄호 안에 있어야 합니다. 라벨 이름에 기존 버전과 호환되지 않는 문자가 포함된 경우에도 따옴표로 묶어야 합니다. 다음 유효한 쿼리 예시는 모두 동일합니다.

  • {"my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

측정항목 이름 일치

측정항목 이름의 정확한 일치만 지원됩니다. 쿼리에 측정항목 이름의 정확한 일치를 포함해야 합니다.

__name__ 라벨에서 정규 표현식 일치자를 사용하는 일반적인 시나리오에 다음 해결 방법을 사용하는 것이 좋습니다.

  • Prometheus 어댑터 구성은 여러 측정항목 이름에 일치시키기 위해 =~ 연산자를 사용하는 경우가 많습니다. 이 방법을 수정하려면 각 측정항목에 별도의 정책을 사용하도록 구성을 확장하고 각 측정항목의 이름을 명시적으로 지정합니다. 이렇게 하면 예상치 못한 측정항목을 실수로 자동 확장하는 것도 방지할 수 있습니다.
  • 정규 표현식은 동일한 차트에 여러 무차원 측정항목을 그래프로 표시하는 데 자주 사용됩니다. 예를 들어 cpu_servicename_usage와 같은 측정항목이 있는 경우 와일드 카드를 사용하여 모든 서비스를 함께 그래프로 표시할 수 있습니다. 이와 같은 무차원 측정항목을 사용하는 것은 Cloud Monitoring에서 명시적으로 좋지 않은 방법으로, 이로 인해 쿼리 성능이 크게 저하됩니다. 이 방법을 수정하려면 측정항목 이름에 차원을 삽입하는 대신 모든 차원을 측정항목 라벨로 이동합니다.
  • 여러 측정항목을 쿼리하는 것은 쿼리할 수 있는 측정항목을 확인하는 데 자주 사용됩니다. 대신 /labels/__name__/values 호출을 사용하여 측정항목을 검색하는 것이 좋습니다. Cloud Monitoring UI를 사용하여 측정항목을 검색할 수도 있습니다.
  • 여러 측정항목을 일치시키면 측정항목별로 스크래핑 및 수집되고 요금이 청구된 샘플 수를 확인하는 데 유용합니다. Cloud Monitoring은 측정항목 관리 페이지에서 이 정보를 제공합니다. 수집된 샘플 측정항목 또는 기여 분석 ID로 작성된 샘플 측정항목을 사용하여 이 정보에 측정항목 데이터로 액세스할 수도 있습니다.

비활성

비활성은 Monarch 백엔드에서 지원되지 않습니다.

irate 계산

irate 함수의 전환 확인 기간이 단계 크기보다 작으면 기간을 단계 크기로 늘립니다. Monarch에서 이러한 변경은 출력에서 어떠한 입력 데이터도 완전히 무시되지 않도록 보장하기 위해 필요합니다. 이 차이점은 rate 계산에도 적용됩니다.

rate 및 increase 계산

rate 함수의 전환 확인 기간이 단계 크기보다 작으면 기간을 단계 크기로 늘립니다. Monarch에서 이러한 변경은 출력에서 어떠한 입력 데이터도 완전히 무시되지 않도록 보장하기 위해 필요합니다. 이 차이점은 irate 계산에도 적용됩니다.

내삽 및 외삽 계산에 차이점이 있습니다. Monarch는 Prometheus와 다른 내삽 알고리즘을 사용하며, 이러한 차이로 인해 약간 다른 결과로 이어질 수 있습니다. 예를 들어 Monarch 카운터 샘플은 Prometheus에 사용되는 단일 타임스탬프가 아닌 시간 범위로 저장됩니다. 따라서 Monarch의 카운터 샘플은 Prometheus 타임스탬프가 이를 제외하더라도 비율 계산에 포함될 수 있습니다. 특히 기본 시계열의 시작 또는 끝 부분에서 쿼리할 때 일반적으로 더 정확한 비율 결과가 제공됩니다.

histogram_quantile 계산

샘플이 없는 히스토그램의 PromQL histogram_quantile 계산은 NaN 값을 생성합니다. 내부 쿼리 언어의 계산은 값을 생성하지 않습니다. 대신 타임스탬프의 지점이 삭제됩니다.

비율 계산 차이는 histogram_quantile 쿼리에 대한 입력에도 영향을 줄 수 있습니다.

유형이 다른 측정항목에 대한 유형별 함수

업스트림 Prometheus는 약한 유형이지만 Monarch는 강력한 유형입니다. 즉, 이러한 함수가 업스트림 Prometheus에서 작동하더라도 다른 유형의 측정항목(예: GAUGE 측정항목에서 rate() 실행 또는 COUNTER 또는 유형이 지정되지 않은 측정항목에서 histogram_quantile() 실행)에서 단일 유형에 대한 함수 실행은 Cloud Monitoring에서 작동하지 않습니다.