アラート ポリシーは、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
に設定します。
作成した条件によっては、他にも使用できるフィールドがある場合があります。
アラート ポリシーに 1 つの条件が含まれている場合、その条件が満たされたときに通知が送信されます。アラート ポリシーに複数の条件が含まれている場合の通知については、複数の条件を持つポリシーとポリシーごとの通知数をご覧ください。
アラート ポリシーを作成または変更すると、name
フィールドなど、他のフィールドも設定されます。name
フィールドの値は、アラート ポリシーのリソース名です。このリソース名でポリシーを識別します。リソース名の形式は次のとおりです。
projects/PROJECT_ID/alertPolicies/POLICY_ID
API での条件タイプ
Cloud Monitoring API は、Condition
構造でさまざまな条件タイプをサポートしています。指標ベースのアラート ポリシーには複数の条件タイプがあり、ログベースのアラート ポリシーには 1 つの条件タイプがあります。以下のセクションでは、使用可能な条件タイプについて説明します。
指標ベースのアラート ポリシーの条件
ログベースの指標など、指標データをモニタリングするアラート ポリシーを作成するには、次の条件タイプを使用します。
フィルタベースの指標の条件
MetricAbsence
条件と MetricThreshold
条件では、Monitoring フィルタを使用して、モニタリングする時系列データを選択します。条件構造体の他のフィールドでは、データのフィルタリング、グループ化、集計の方法を指定します。これらのコンセプトの詳細については、フィルタリングと集計: 時系列の操作をご覧ください。
MetricAbsence
条件タイプを使用する場合は、すべての時系列が不在の場合にのみ満たす条件を作成できます。この条件では、aggregations
パラメータを使用して、複数の時系列を単一の時系列に集計します。詳しくは、API ドキュメントの MetricAbsence
リファレンスをご覧ください。
指標の不在のアラート ポリシーでは、一部のデータがすでに書き込まれている必要があります。詳細については、指標の不在のアラート ポリシーを作成するをご覧ください。
予測値に基づいて通知を受け取る場合は、MetricThreshold
条件タイプを使用するようにアラート ポリシーを構成し、forecastOptions
フィールドを設定します。このフィールドが設定されていない場合、測定データがしきい値と比較されます。ただし、このフィールドが設定されていると、予測データがしきい値と比較されます。詳細については、予測指標値のアラート ポリシーを作成するをご覧ください。
MQL ベースの指標の条件
MonitoringQueryLanguageCondition
条件では、Monitoring Query Language(MQL)を使用して、モニタリングする時系列データを選択して操作します。しきい値と値を比較するアラート ポリシーを作成したり、この条件タイプで値が存在しない場合をテストしたりできます。MonitoringQueryLanguageCondition
条件を使用する場合は、アラート ポリシーの唯一の条件にする必要があります。詳細については、MQL のアラート ポリシーをご覧ください。
PromQL ベースの指標の条件
PrometheusQueryLanguageCondition
条件では、Prometheus Query Language(PromQL)クエリを使用して、モニタリングする時系列データを選択して操作します。条件では、指標の比率を計算したり、指標の比較を評価したりできます。
PrometheusQueryLanguageCondition
条件を使用する場合は、アラート ポリシーの唯一の条件にする必要があります。詳細については、PromQL のアラート ポリシーをご覧ください。
比率に関するアラートの条件
指標しきい値のアラート ポリシーを作成して、2 つの指標の比率をモニタリングできます。これらのポリシーは、MetricThreshold
または MonitoringQueryLanguageCondition
の条件タイプを使用して作成できます。
また、Google Cloud コンソールで MQL を直接使用することもできます。しきい値条件の作成にグラフィカル インターフェースを使用すると、比率ベースの条件を作成または管理することはできません。
MQL を使用して、比率ベースのアラート ポリシーを作成することをおすすめします。MQL では、MetricTheshold
条件タイプと Monitoring フィルタを使用して作成できるよりも強力で柔軟なクエリを構築できます。
たとえば、MonitoringQueryLanguageCondition
条件を使用すると、ゲージ指標とデルタ指標の比率を計算できます。例については、MQL アラート ポリシーの例をご覧ください。
MetricThreshold
条件を使用する場合、比率の分子と分母は同じ MetricKind
である必要があります。指標とそのプロパティのリストについては、指標リストをご覧ください。
一般に、ラベル値を使用して、単一の指標タイプに対して収集された時系列に基づいて比率を計算することが最適です。2 つの異なる指標タイプで計算された比率は、サンプリング期間とアライメント ウィンドウが異なるため、異常が発生する可能性があります。
たとえば、RPC の合計数と RPC のエラー数の 2 つの異なる指標タイプがあり、RPC の合計数に対する RPC のエラー数の割合を計算するとします。失敗した RPC は、両方の指標タイプの時系列にカウントされます。そのため、時系列をアライメントすると、失敗した RPC が両方の時系列の同じアライメント間隔に表示されない場合があります。この差は、次のような原因で発生することがあります。
- 同じイベントを記録する 2 つの異なる時系列があるため、コレクションを実装する 2 つの基になるカウンタ値があり、それらはアトミックに更新されません。
- サンプリング レートは異なる場合があります。時系列が共通の期間にアラインメントされると、単一のイベントのカウントが、異なる指標の時系列の隣接するアラインメント間隔に表示される場合があります。
対応するアライメント間隔の値の数の差は、1/0 や 2/1 などの意味のない error/total
比率値になる場合があります。
大きな数値の比率の場合、意味のない値になる可能性は低くなります。 サンプリング期間よりも長いアライメント ウィンドウを使用するか、特定のラベルのデータをグループ化すれば、集計で大きな数値を取得できます。これらの手法は、特定の間隔でのポイント数のわずかな違いによる影響を最小限に抑えます。つまり、間隔内の予想されるポイント数が 3 の場合、予想される数が 300 の場合よりも、2 ポイントの不一致による影響が大きくなります。
組み込みの指標タイプを使用している場合は、指標タイプ全体の比率を計算して、必要な値を取得せざるを得ない場合があります。
2 つの異なる指標で同じもの(エラー ステータスを返す RPC など)をカウントする可能性のあるカスタム指標を設計している場合は、代わりに、各カウントを 1 回だけ含む単一の指標を検討してください。たとえば、RPC をカウントしていて、すべての RPC に対する失敗した RPC の比率を追跡するとします。RPC をカウントする単一の指標タイプを作成し、ラベルを使用して「OK」ステータスを含む呼び出しのステータスを記録します。次に、その場合の単一のカウンタを更新することにより、各ステータス値、エラーまたは「OK」が記録されます。
ログベースのアラート ポリシーの条件
フィルタに一致するメッセージがログエントリに表示されたときに通知するログベースのアラート ポリシーを作成するには、LogMatch
条件タイプを使用します。LogMatch
条件を使用する場合は、アラート ポリシーの唯一の条件にする必要があります。
LogMatch
条件タイプをログベースの指標と一緒に使用しないでください。ログベースの指標をモニタリングするアラート ポリシーは、指標ベースのポリシーです。ログベースの指標またはログエントリをモニタリングするアラート ポリシーの選択方法について詳しくは、ログのモニタリングをご覧ください。
API によるアラート ポリシーの管理のドキュメントの例で使用されているアラート ポリシーは、指標ベースのアラート ポリシーです。ただし、原則はログベースのアラート ポリシーと同じです。ログベースのアラート ポリシーの詳細については、Cloud Logging ドキュメントの Monitoring API を使用してログベースのアラート ポリシーを作成するをご覧ください。
始める前に
API に対してコードを記述する前に以下が必要です。
- アラート ポリシーで使用される一般的なコンセプトと用語を十分理解する。詳細については、アラートの概要をご覧ください。
- Cloud Monitoring API が使用可能である。詳細については、API の有効化をご覧ください。
- クライアント ライブラリを使用する場合は、使用する言語のライブラリをインストールする。詳しくは、クライアント ライブラリをご覧ください。 現在、アラートの API サポートは、C#、Go、Java、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 を使用してアラート ポリシーを作成および変更するために必要な権限を取得するには、プロジェクトに対する Monitoring AlertPolicy 編集者(
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 のどの例にも、これらのフィールドは含まれていません。ただし、フィールドから作成されたポリシーが作成後に取得された場合、フィールドが表示されます。
指標ベースのアラート ポリシーの繰り返し通知を構成する
デフォルトでは、指標ベースのアラート ポリシーは、インシデントが開かれると、各通知チャンネルに 1 つの通知を送信します。ただし、デフォルトの動作を変更し、アラート ポリシーの通知チャンネルのすべてまたは一部に通知を再送信するようにアラート ポリシーを構成できます。この繰り返し通知は、ステータスが [対応待ち] または [確認済み] のインシデントに送信されます。これらの通知の間隔は 30 分以上 24 時間以内で、秒単位で表されます。
繰り返し通知を構成するには、アラート ポリシーの構成に、少なくとも 1 つの NotificationChannelStrategy
オブジェクトを含む AlertStrategy
オブジェクトを追加します。
NotificationChannelStrategy
オブジェクトには次の 2 つのフィールドがあります。
renotifyInterval
: 繰り返し通知の間隔(秒単位)。アラート ポリシーのインシデントを開いたときに
renotifyInterval
フィールドの値を変更すると、次のようになります。- アラート ポリシーが、インシデントに関する別の通知を送信します。
- アラート ポリシーがその間隔の期間を再開します。
notificationChannelNames
: 通知チャンネルのリソース名の配列。projects/PROJECT_ID/notificationChannels/CHANNEL_ID
形式の文字列で、CHANNEL_ID は数値です。 チャンネル ID を取得する方法については、プロジェクト内の通知チャンネルの一覧取得をご覧ください。
たとえば、次の JSON サンプルは、1,800 秒(30 分)ごとに繰り返し通知を一つの通知チャンネルに送信するように構成されたアラート戦略を示しています。
"alertStrategy": { "notificationChannelStrategy": [ { "notificationChannelNames": [ "projects/PROJECT_ID/notificationChannels/CHANNEL_ID" ], "renotifyInterval": "1800s" } ] }
繰り返しの通知を一時的に停止するには、スヌーズを作成します。繰り返し通知されないようにするには、API を使用してアラート ポリシーを編集し、NotificationChannelStrategy
オブジェクトを削除します。