PromQL 기반 알림 정책 만들기 (API)

이 페이지에서는 Cloud Monitoring API를 사용하여 PromQL 기반 알림 정책을 만드는 방법을 설명합니다. 알림 정책에서 PromQL 쿼리를 사용하여 비율, 동적 기준, 측정항목 평가와 같은 기능이 있는 복잡한 조건을 만들 수 있습니다.

일반적인 정보는 PromQL을 사용한 알림 정책을 참조하세요.

Cloud Monitoring 외부의 Prometheus 환경에서 작업하고 Prometheus 알림 규칙이 있는 경우 Google Cloud CLI를 사용하여 PromQL 쿼리로 Monitoring 알림 정책에 마이그레이션할 수 있습니다. 자세한 내용은 Prometheus에서 알림 규칙 및 수신자 마이그레이션을 참조하세요.

PromQL 쿼리로 알림 정책 만들기

alertPolicies.create 메서드를 사용하여 프로그래매틱 방식으로 알림 정책을 만듭니다.

PromQL 기반 알림 정책과 다른 알림 정책 생성의 유일한 차이점은 Condition 유형이 PrometheusQueryLanguageCondition이어야 한다는 것입니다. 이 조건 유형을 사용하면 PromQL을 사용하여 알림 정책을 정의할 수 있습니다.

다음은 kube-state 내보내기 도구의 측정항목을 사용하여 지난 30분 동안 컨테이너가 다시 시작된 횟수를 찾는 알림 정책 조건에 대한 PromQL 쿼리를 보여줍니다.

rate(kube_pod_container_status_restarts[30m]) * 1800 > 1

알림 정책 구성

PromQL 기반 알림 정책을 빌드하려면 AlertPolicy 조건 유형 PrometheusQueryLanguageCondition을 사용합니다. PrometheusQueryLanguageCondition의 구조는 다음과 같습니다.

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "alertRule": string
}

PrometheusQueryLanguageCondition 필드에는 다음과 같은 정의가 있습니다.

  • query: 평가할 PromQL 표현식입니다. 표준 Prometheus 알림 규칙의 expr 필드와 같습니다.
  • duration: 알림 정책의 조건이 충족되기 전에 쿼리의 각 평가에서 true 값을 생성해야 하는 시간을 지정합니다. 값은 초 단위로 표시되는 분이어야 합니다(예: 10분 동안 600s). 자세한 내용은 측정항목 기반 알림 정책 동작을 참조하세요.
  • evaluationInterval: 쿼리의 PromQL 평가 사이의 시간 간격(초)입니다. 기본값은 30초입니다. Prometheus 알림 규칙을 마이그레이션하여 PrometheusQueryLanguageCondition이 생성된 경우 이 값은 Prometheus 알림 규칙이 포함된 Prometheus 규칙 그룹에서 가져옵니다.

  • labels: PromQL 표현식 결과에서 라벨을 추가하거나 덮어쓰는 선택적 방법입니다.

  • ruleGroup: 알림 정책이 Prometheus 구성 파일에서 마이그레이션된 경우 이 필드에는 Prometheus 구성 파일에 있는 규칙 그룹name 필드 값이 포함됩니다. Cloud Monitoring API에서 PromQL 알림 정책을 만들 때는 이 필드가 필요하지 않습니다.

  • alertRule: 알림 정책이 Prometheus 구성 파일에서 마이그레이션된 경우 이 필드에는 Prometheus 구성 파일에 있는 알림 규칙alert 필드 값이 포함됩니다. Cloud Monitoring API에서 PromQL 알림 정책을 만들 때는 이 필드가 필요하지 않습니다.

예를 들어 다음 조건은 PromQL 쿼리를 사용하여 지난 30분 동안 컨테이너가 다시 시작된 횟수를 찾습니다.

"conditionPrometheusQueryLanguage": {
  "query": "rate(kube_pod_container_status_restarts[30m]) * 1800 > 1",
  "duration": "600s",
  evaluationInterval: "60s",
  "alertRule": "ContainerRestartCount",
  "labels": {
    "action_required":"true",
    "severity":"critical/warning/info"}
}

이 구조를 알림 정책 구조에 삽입되는 조건의 conditionPrometheusQueryLanguage 필드 값으로 사용합니다. 이러한 구조에 대한 자세한 내용은 AlertPolicy를 참조하세요.

다음은 JSON 형식의 PrometheusQueryLanguageCondition 조건이 포함된 완전한 정책을 보여줍니다.

{
  "displayName": "Container Restarts",
  "documentation": {
    "content": "Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes.",
    "mimeType": "text/markdown",
    "subject": "Container ${resource.label.container_name} in Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes."
  },
  "userLabels": {},
  "conditions": [
    {
      "displayName": "Container has restarted",
      "conditionPrometheusQueryLanguage": {
        "query": "rate(kubernetes_io:container_restart_count[30m]) * 1800",
        "duration": "600s",
        evaluationInterval: "60s",
        "alertRule": "ContainerRestart",
        "labels": {
          "action_required":"true",
          "severity":"critical/warning/info"}
      }
    }
  ],
  "combiner": "OR",
  "enabled": true
}

알림 정책 만들기

알림 정책을 만들려면 알림 정책 JSON을 POLICY_NAME.json이라는 파일에 넣고 다음 명령어를 실행합니다.

curl -d @POLICY_NAME.json -H "Authorization: Bearer $TOKEN"
-H 'Content-Type: application/json'
-X POST https://monitoring.googleapis.com/v3/projects/${PROJECT}/alertPolicies

알림 정책에 대한 Monitoring API에 대한 자세한 내용은 API를 통한 알림 정책 관리를 참조하세요.

curl 사용에 대한 자세한 내용은 curl 호출을 참조하세요.

Terraform 사용

Terraform을 사용하여 PromQL 기반 알림 정책을 구성하는 방법은 google_monitoring_alert_policy Terraform 레지스트리condition_prometheus_query_language 섹션을 참조하세요.

Terraform과 함께 Google Cloud를 사용하는 방법에 대한 일반적인 내용은 Google Cloud에서 Terraform을 참조하세요.

curl 호출

curl 호출에는 인수 집합과 API 리소스의 URL이 포함됩니다. 일반적인 인수에는 Google Cloud 프로젝트 ID와 인증 토큰이 포함됩니다. 이 값은 여기에서 PROJECT_IDTOKEN 환경 변수로 표시됩니다.

HTTP 요청의 유형을 지정하기 위해 다른 인수를 지정해야 할 수도 있습니다(예: -X DELETE). 기본 요청은 GET이므로 예시에서는 이를 지정하지 않습니다.

curl 호출은 다음과 같은 일반적인 구조를 취합니다.

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

curl을 사용하려면 프로젝트 ID와 액세스 토큰을 지정해야 합니다. 입력 및 오류를 줄이려면 이를 환경 변수에 입력하여 curl에 전달하면 됩니다.

이러한 변수를 설정하려면 다음 안내를 따르세요.

  1. 측정항목 범위의 범위 지정 프로젝트의 ID를 저장할 환경 변수를 만듭니다. 다음 단계는 변수 PROJECT_ID를 호출합니다.

    PROJECT_ID=a-sample-project
    
  2. Google Cloud CLI에 인증합니다.

    gcloud auth login
    
  3. 선택사항. 각 gcloud 명령어로 프로젝트 ID를 지정하지 않으려면 gcloud CLI를 사용하여 프로젝트 ID를 기본값으로 설정합니다.

    gcloud config set project ${PROJECT_ID}
    
  4. 승인 토큰을 만들고 환경 변수에 저장합니다. 다음 단계는 변수 TOKEN을 호출합니다.

    TOKEN=`gcloud auth print-access-token`
    

    정기적으로 액세스 토큰을 새로고침해야 합니다. 작업한 명령어에서 사용자가 인증되지 않았다고 갑자기 보고하면 이 명령어를 다시 실행합니다.

  5. 액세스 토큰을 받았는지 확인하려면 TOKEN 변수를 출력합니다.

    echo ${TOKEN}
    ya29.GluiBj8o....