알림 정책은 Cloud Monitoring API에서 AlertPolicy
객체로 표현됩니다. 이 객체는 시스템의 비정상 상태를 나타내는 조건 집합을 설명합니다.
이 문서에서는 다음을 설명합니다.
- Monitoring API가 알림 정책을 나타내는 방법
- Monitoring API가 알림 정책에 제공하는 조건 유형
- Google Cloud CLI 또는 클라이언트 라이브러리를 사용하여 알림 정책을 만드는 방법
알림 정책 구조
AlertPolicy
구조는 알림 정책의 구성요소를 정의합니다. 정책을 만들 때 다음 AlertPolicy
필드에 대해 값을 지정합니다.
displayName
: 정책을 설명하는 라벨입니다.documentation
: 이 필드를 사용하여 이슈 응답자에게 도움이 되는 정보를 제공하는 것이 좋습니다. 자세한 내용은 사용자 정의 문서로 알림에 주석 추가를 참조하세요.userLabels
: 정책에 연결된 사용자 정의 라벨입니다. 알림과 함께 라벨 사용에 대한 자세한 내용은 라벨로 이슈에 주석 추가를 참조하세요.conditions[]
:Condition
구조의 배열입니다.combiner
: 여러 조건을 처리하는 방법을 결정하는 논리적 연산자입니다.notificationChannels[]
: 각각NotificationChannel
을 식별하는 리소스 이름의 배열입니다.alertStrategy
: 다음을 지정합니다.- 데이터 수신이 중지될 때 Monitoring이 이슈를 종결하는 속도
- 측정항목 기반 알림 정책의 경우 이슈가 종결될 때 Monitoring이 알림을 전송하는지 여부
- 측정항목 기반 알림 정책의 경우 반복 알림의 사용 설정 여부와 알림 간격 자세한 내용은 측정항목 기반 알림 정책의 반복 알림 구성을 참조하세요.
또한 Cloud Monitoring API 및 Google Cloud 콘솔을 사용할 때 severity
필드를 지정할 수 있습니다. 이 필드를 사용하면 이슈의 심각도 수준을 정의할 수 있습니다. 심각도를 지정하지 않으면 Cloud Monitoring이 알림 정책 심각도를 No Severity
로 설정합니다.
만드는 조건에 따라 다른 필드를 사용할 수 있습니다.
알림 정책에 하나의 조건이 포함된 경우 이 조건이 충족되면 알림이 전송됩니다. 알림 정책에 여러 조건이 포함된 경우의 알림에 대한 자세한 내용은 여러 조건이 포함된 정책 및 정책별 알림 수를 참조하세요.
알림 정책을 만들거나 수정할 때 Monitoring은 name
필드를 포함한 다른 필드도 설정합니다. name
필드의 값은 정책을 식별하는 알림 정책의 리소스 이름입니다. 리소스 이름은 다음 형식을 갖습니다.
projects/PROJECT_ID/alertPolicies/POLICY_ID
API에서 조건의 유형
Cloud Monitoring API는 Condition
구조에서 다양한 조건 유형을 지원합니다. 측정항목 기준 알림 정책에는 여러 조건 유형이 있고 로그 기준 알림 정책에는 하나의 유형이 있습니다. 다음 섹션에서는 사용 가능한 조건 유형을 설명합니다.
측정항목 기준 알림 정책의 조건
로그 기준 측정항목을 포함하여 측정항목 데이터를 모니터링하는 알림 정책을 만들려면 다음 조건 유형을 사용할 수 있습니다.
필터 기준 측정항목 조건
MetricAbsence
및 MetricThreshold
조건은 모니터링 필터를 사용하여 모니터링할 시계열 데이터를 선택합니다. 조건 구조의 다른 필드는 데이터 필터링, 그룹화 및 집계 방법을 지정합니다. 이러한 개념들에 대한 자세한 내용은 필터링 및 집계: 시계열 조작을 참조하세요.
MetricAbsence
조건 유형을 사용하는 경우 모든 시계열이 없을 때만 충족되는 조건을 만들 수 있습니다. 이 조건은 aggregations
매개변수를 사용하여 여러 시계열을 단일 시계열로 집계합니다. 자세한 내용은 API 문서의 MetricAbsence
참조를 확인하세요.
측정항목 부재 알림 정책을 사용하려면 일부 데이터가 이전에 기록되어 있어야 합니다. 자세한 내용은 측정항목 부재 알림 정책 만들기를 참조하세요.
예측된 값을 기반으로 알림을 받으려면 MetricThreshold
조건 유형을 사용하고 forecastOptions
필드를 설정하도록 알림 정책을 구성합니다. 이 필드가 설정되지 않으면 측정된 데이터를 기준점과 비교합니다.
하지만 이 필드가 설정되었으면 예측 데이터를 기준점과 비교합니다. 자세한 내용은 예측된 측정항목 값 알림 정책 만들기를 참조하세요.
MQL 기준 측정항목 조건
MonitoringQueryLanguageCondition
조건은 Monitoring 쿼리 언어(MQL)를 사용하여 모니터링할 시계열 데이터를 선택하고 조작합니다. 값을 기준점과 비교하거나 이 조건 유형의 값 부재를 테스트하는 알림 정책을 만들 수 있습니다.
MonitoringQueryLanguageCondition
조건을 사용할 경우 알림 정책에서 유일한 조건이어야 합니다. 자세한 내용은 MQL을 사용한 알림 정책을 참조하세요.
PromQL 기반 측정항목 조건
PrometheusQueryLanguageCondition
조건은 Prometheus 쿼리 언어(PromQL) 쿼리를 사용하여 모니터링할 시계열 데이터를 선택하고 조작합니다.
조건을 통해 측정항목의 비율을 계산하고, 측정항목 비교를 평가하는 등의 작업을 할 수 있습니다.
PrometheusQueryLanguageCondition
조건을 사용할 경우 알림 정책에서 유일한 조건이어야 합니다. 자세한 내용은 PromQL을 사용한 알림 정책을 참조하세요.
비율 알림 조건
두 가지 측정항목의 비율을 모니터링하도록 측정항목 임곗값 알림 정책을 만들 수 있습니다. MetricThreshold
또는 MonitoringQueryLanguageCondition
조건 유형을 사용하여 이러한 정책을 만들 수 있습니다.
또한 Google Cloud 콘솔에서 직접 MQL을 사용할 수 있습니다. 임곗값 조건을 만들기 위한 그래픽 인터페이스를 사용하여 역할 기준 조건을 만들거나 관리할 수 없습니다.
MQL을 사용하여 비율 기준 알림 정책을 만드는 것이 좋습니다.
MQL을 사용하면 MetricTheshold
조건 유형 및 모니터링 필터를 사용하여 빌드할 수 있는 것보다 더 강력하고 더 유연한 쿼리를 빌드할 수 있습니다.
예를 들어 MonitoringQueryLanguageCondition
조건의 경우 델타 측정항목에 대한 게이지 측정항목의 비율을 계산할 수 있습니다. 예시를 보려면 MQL 알림 정책 예시를 참조하세요.
MetricThreshold
조건을 사용하는 경우 해당 비율의 분자 및 분모가 모두 동일한 MetricKind
를 가져야 합니다.
측정항목 및 해당 속성의 목록은 측정항목 목록을 참조하세요.
일반적으로 라벨 값을 사용하여 단일 측정항목 유형에 대해 수집된 시계열을 기준으로 비율을 계산하는 것이 가장 좋습니다. 서로 다른 두 측정항목 유형에서 계산되는 비율에는 샘플링 기간 및 정렬 기간의 차이로 인한 문제점이 나타날 수 있습니다.
예를 들어 두 가지 측정항목 유형, RPC 총 개수와 RPC 오류 개수가 있고 총 RPC에 대한 오류 개수 RPC의 비율을 계산한다고 가정해 보겠습니다. 실패한 RPC는 두 측정항목 유형 모두의 시계열에 포함됩니다. 따라서 시계열을 정렬할 때 두 시계열 모두 동일한 정렬 간격으로 실패한 RPC가 표시되지 않을 수 있습니다. 이러한 차이는 다음과 같은 여러 이유로 발생할 수 있습니다.
- 동일한 이벤트를 기록하는 서로 다른 시계열이 두 개 있으므로 컬렉션을 구현하는 두 가지 기본 카운터 값이 있게 되고 원자적으로 업데이트되지 않습니다.
- 샘플링 레이트는 다를 수 있습니다. 시계열이 공통 기간으로 정렬되면 단일 이벤트에 대한 이벤트 수가 서로 다른 측정항목의 시계열에 가까운 정렬 간격으로 표시될 수 있습니다.
해당 정렬 간격의 값 수에 차이가 있으면 1/0 또는 2/1과 같은 무의미한 error/total
비율 값이 발생할 수 있습니다.
비율에 사용되는 숫자가 클수록 무의미한 값이 나올 가능성이 낮습니다. 샘플링 기간보다 긴 정렬 기간을 사용하거나 특정 라벨의 데이터를 그룹화하여 집계하면 더 큰 숫자를 사용할 수 있습니다. 이러한 기법은 특정 간격의 포인트 수에 미치는 작은 차이의 영향을 최소화합니다. 즉, 간격의 예상 포인트 수가 300인 경우보다 3일 경우 2점 차이가 더 중요합니다.
기본 제공 측정항목 유형을 사용하는 경우 필요한 값을 얻기 위해 측정항목 유형 전반에서 비율을 계산해야 할 수도 있습니다.
두 개의 서로 다른 측정항목에서 RPC에서 오류 상태를 반환하는 RPC와 같이 같은 항목을 계산할 수 있는 커스텀 측정항목을 설계하는 경우 각 측정항목이 한 번만 포함된 단일 측정항목을 사용하는 것이 좋습니다. 예를 들어 RPC를 계산 중이고 모든 RPC에 대한 실패한 RPC 비율을 추적한다고 가정해보세요. 이 문제를 해결하려면 RPC를 계산하도록 단일 측정항목 유형을 만들고 라벨을 사용해서 'OK' 상태를 포함해서 호출 상태를 기록합니다. 그런 다음 각 상태 값 오류 또는 'OK'가 해당 사례에 대한 단일 카운터를 업데이트하여 기록됩니다.
로그 기준 알림 정책 조건
필터와 일치하는 메시지가 로그 항목에 표시될 때 알림을 제공하는 로그 기준 알림 정책을 만들려면 LogMatch
조건 유형을 사용합니다. LogMatch
조건을 사용할 경우 알림 정책에서 유일한 조건이어야 합니다.
LogMatch
조건 유형을 로그 기준 측정항목과 함께 사용하지 마세요. 로그 기준 측정항목을 모니터링하는 알림 정책은 측정항목 기준 정책입니다. 로그 기준 측정항목 또는 로그 항목을 모니터링하는 알림 정책 선택에 대한 자세한 내용은 로그 모니터링을 참조하세요.
로그 기준 알림 정책에서도 원칙은 동일하지만, API를 통한 알림 정책 관리 문서의 예시에 사용되는 알림 정책은 측정항목 기준 알림 정책입니다. 로그 기준 알림 정책 관련 정보는 Cloud Logging 문서에서 Monitoring API를 사용하여 로그 기반 알림 정책 만들기를 참조하세요.
시작하기 전에
다음은 API를 활용하는 코드 작성 시 사전 요구 사항입니다.
- 알림 정책에 사용되는 일반적인 개념과 용어를 익혀야 합니다. 자세한 내용은 알림 개요를 참조하세요.
- Cloud Monitoring API가 사용 설정되었는지 확인합니다. 자세한 내용은 API 사용 설정을 참조하세요.
- 클라이언트 라이브러리를 사용하려면 사용하려는 언어의 라이브러리를 설치합니다. 자세한 내용은 클라이언트 라이브러리를 참조하세요. 현재 API의 알림 지원은 C#, Go, 자바, Node.js, Python에만 사용할 수 있습니다.
Google Cloud CLI를 사용하려면 이를 설치합니다. 하지만 Cloud Shell을 사용하는 경우 Google Cloud CLI가 이미 설치되어 있습니다.
gcloud
인터페이스의 사용 예도 여기에 나와 있습니다.gcloud
예시에서는 현재 프로젝트가 이미 대상(gcloud config set project [PROJECT_ID]
)으로 설정되어 있다고 가정하므로 호출 시 명시적--project
플래그가 생략됩니다. 예시에서 현재 프로젝트의 ID는a-gcp-project
입니다.
-
Cloud Monitoring API를 사용하여 알림 정책을 만들고 수정하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 모니터링 경고 정책 편집자(
roles/monitoring.alertPolicyEditor
) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
Monitoring의 IAM 역할에 대한 자세한 내용은 Identity and Access Management로 액세스 제어를 참조하세요.
Google Cloud 프로젝트에서 알림 정책 상태를 수정하는 단일 스레드 Cloud Monitoring API 호출로 실행하도록 애플리케이션을 설계합니다. 예를 들어 알림 정책을 만들고, 업데이트, 삭제하는 단일 스레드 API 호출이 있습니다.
알림 정책 만들기
프로젝트에서 알림 정책을 만들려면 alertPolicies.create
메서드를 사용합니다. 이 메서드, 해당 매개변수, 응답 데이터를 호출하는 방법은 참조 페이지 alertPolicies.create
를 확인하세요.
JSON 또는 YAML 파일에서 정책을 만들 수 있습니다.
Google Cloud CLI는 이러한 파일을 인수로 수락합니다. 사용자는 프로그래매틱 방식으로 JSON 파일을 읽고, AlertPolicy
객체로 변환하고, alertPolicies.create
메서드를 사용해서 이로부터 정책을 만들 수 있습니다. 알림 규칙이 포함된 Prometheus JSON 또는 YAML 구성 파일이 있으면 gcloud CLI가 PromQL 조건을 사용하여 Cloud Monitoring 알림 정책으로 마이그레이션할 수 있습니다. 자세한 내용은 Prometheus에서 알림 규칙 및 수신자 마이그레이션을 참조하세요.
각 알림 정책은 측정항목 범위의 범위 지정 프로젝트에 속합니다. 각 프로젝트는 최대 500개까지 정책을 포함할 수 있습니다.
API 호출의 경우 '프로젝트 ID'를 제공하고, 측정항목 범위의 범위 지정 프로젝트의 ID를 값으로 사용해야 합니다. 이 예시에서 측정항목 범위의 범위 지정 프로젝트의 ID는 a-gcp-project
입니다.
다음 샘플에서는 알림 정책 생성을 보여주지만 알림 정책을 설명하는 JSON 또는 YAML 파일을 만드는 방법을 설명하지 않습니다. 대신 샘플에서는 JSON 형식의 파일이 있다고 가정하고 API 호출을 실행하는 방법을 보여줍니다. JSON 파일의 예시는 샘플 정책을 참조하세요. 측정항목 비율 모니터링에 대한 일반적인 내용은 측정항목 비율을 참조하세요.
gcloud
프로젝트에서 알림 정책을 만들려면 gcloud alpha monitoring
policies create
명령어를 실행합니다. 다음 예시에서는 rising-cpu-usage.json
파일로 a-gcp-project
에 알림 정책을 만듭니다.
gcloud alpha monitoring policies create --policy-from-file="rising-cpu-usage.json"
성공할 경우 이 명령어는 다음과 같은 새 정책의 이름을 반환합니다.
Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].
rising-cpu-usage.json
파일에는 표시 이름이 'High CPU rate of change'인 정책의 JSON이 들어 있습니다. 이 정책에 대한 자세한 내용은 변경률 정책을 참조하세요.
자세한 내용은 gcloud alpha monitoring policies create
참조를 확인하세요.
C#
Monitoring에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Go
Monitoring에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Java
Monitoring에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Node.js
Monitoring에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
PHP
Monitoring에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Python
Monitoring에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
생성된 AlertPolicy
객체에는 추가 필드가 있습니다.
정책 자체에는 name
, creationRecord
, mutationRecord
필드가 포함됩니다. 또한 정책의 각 조건에도 name
이 제공됩니다.
이러한 필드는 외부에서 수정할 수 없으므로 정책을 만들 때 필드를 설정할 필요가 없습니다. 정책 만들기에 사용되는 JSON 예에는 이러한 필드가 포함되어 있지 않습니다. 그러나 생성 후 이러한 필드에서 생성된 정책이 검색될 경우 필드가 존재하게 됩니다.
측정항목 기반 알림 정책의 반복 알림 구성
기본적으로 측정항목 기반 알림 정책은 이슈가 열렸을 때 각 알림 채널에 하나의 알림을 전송합니다. 그러나 기본 동작을 변경하고 알림 정책의 알림 채널 전체 또는 일부로 알림을 다시 전송하도록 알림 정책을 구성할 수 있습니다. 이러한 반복 알림은 미해결 또는 확인됨 상태의 이슈에 대해 전송됩니다. 이러한 알림 사이의 간격은 최소 30분에서 24시간 이하여야 합니다(초 단위).
반복되는 알림을 구성하려면 하나 이상의 NotificationChannelStrategy
객체가 포함된 AlertStrategy
객체를 알림 정책의 구성에 추가합니다.
NotificationChannelStrategy
객체에는 두 개의 필드가 있습니다.
renotifyInterval
: 반복되는 알림 사이의 간격(초)입니다.알림 정책의 이슈가 열렸을 때
renotifyInterval
필드 값을 변경하면 다음 결과가 발생합니다.- 알림 정책이 이슈에 대한 또 다른 알림을 전송합니다.
- 알림 정책이 간격 기간을 다시 시작합니다.
notificationChannelNames
:projects/PROJECT_ID/notificationChannels/CHANNEL_ID
형식의 문자열인 알림 채널 리소스 이름의 배열입니다. 여기서 CHANNEL_ID는 숫자 값입니다. 채널 ID를 검색하는 방법은 프로젝트의 알림 채널 나열을 참조하세요.
예를 들어 다음 JSON 샘플은 1800초(30분)마다 반복되는 알림을 하나의 알림 채널로 전송하도록 구성된 알림 전략을 보여줍니다.
"alertStrategy": { "notificationChannelStrategy": [ { "notificationChannelNames": [ "projects/PROJECT_ID/notificationChannels/CHANNEL_ID" ], "renotifyInterval": "1800s" } ] }
반복되는 알림을 일시적으로 중지하려면 일시중지를 만듭니다. 반복 알림을 방지하려면 API를 사용하여 알림 정책을 수정하고 NotificationChannelStrategy
객체를 삭제합니다.