ユーザー定義のドキュメントでアラートにアノテーションを付ける

このページでは、通知の本文と件名をカスタマイズできるようにアラートポリシーのドキュメントを構成する方法について説明します。ドキュメントフィールドでは、書式なしテキスト、Markdown、変数、チャンネル固有のコントロールがサポートされています。

通知に情報を追加する

アラート対応者には、アラートポリシーの作成時にそのコンテンツを指定することで、修復の手順と通知内のインシデントに関する情報を提供できます。たとえば、通知に内部ハンドブックへのリンクを含めるようにアラートポリシーを構成できます。

実装例については、このページの例のセクションをご覧ください。

通知の件名を構成する

通知の件名を指定して、通知の管理や並べ替えを行うことができます。件名は 255 文字以内にしてください。ドキュメントで件名を定義しない場合、Cloud Monitoring によって件名が決定されます。

Cloud Monitoring API、Google Cloud CLI、または Google Cloud コンソールを使用するときに、件名を構成できます。

実装例については、このページの例のセクションをご覧ください。

Markdown を使用する

ドキュメントフィールドは、Markdown タグ付けの次のサブセットをサポートします。

ヘッダー。最初のハッシュ文字で示されます。
順序付けられていないリスト。最初のプラス、マイナス、またはアスタリスク文字で示されます。
順序付きリスト。最初の番号とそれに続くピリオドで示されます。
フレーズの前後に単一の下線またはアスタリスクで示される斜体のテキスト。
フレーズの前後に二重下線またはアスタリスクで示される太字のテキスト。
リンク。[link text](url) 構文で示されます。

このタグ付けの詳細については、Markdown のリファレンス、たとえば Markdown ガイドをご覧ください。

変数の使用

ドキュメント内のテキストをカスタマイズするには、${varname} 形式の変数を使用します。ドキュメントが通知付きで送信されると、次の表に示すように、文字列 ${varname} は、対応する Google Cloud リソースから取得された値に置き換えられます。

変数	値
`condition.name`	条件の REST リソース名（例: `projects/foo/alertPolicies/1234/conditions/5678`）
`condition.display_name`	条件の表示名（例: `CPU usage increasing rapidly`）
`log.extracted_label.KEY`	ログエントリから抽出されたラベル `KEY` の値。ログベースのアラートの場合のみ。詳細については、 Monitoring API を使用してログベースのアラートを作成するをご覧ください。
`metadata.system_label.KEY`	システム提供のリソースメタデータラベルの値 `KEY`。¹
`metadata.user_label.KEY`	ユーザー定義のリソースメタデータラベルの値 `KEY`。^1,3
`metric.type`	指数タイプ（例: `compute.googleapis.com/instance/cpu/utilization`）
`metric.display_name`	指数タイプの表示名（例: `CPU utilization`）
`metric.label.KEY`	指標ラベル`KEY`の値。¹ 指標タイプに関連付けられたラベルを確認するには、指標リストをご覧ください。変数 `${metric.label.KEY}` の値が数字、文字、スラッシュ（`/`）、または等号（`=`）で始まっていない場合、Monitoring は通知のラベルを省略します。 Prometheus アラートルールを移行すると、アラートポリシーのドキュメント構成で、Prometheus アラートのフィールドテンプレート `{{$value}}` と `{{humanize $value}}` が `${metric.label.VALUE}` と表示されます。この場合、`VALUE` は PromQL クエリの値を保持します。 Google Cloud で PromQL クエリを作成するときに、`${metric.label.VALUE}` を使用することもできます。
`metric_or_resource.labels`	この変数は、すべての指標とリソースラベルの値を並べ替えられた `key-value` ペアのリストとして表示します。指標ラベルとリソースラベルの名前が同じ場合、指標ラベルのみが表示されます。 Prometheus アラートルールを移行すると、アラートポリシーのドキュメント構成で、Prometheus アラートのフィールドテンプレート `{{$labels}}` と `{{humanize $labels}}` が `${metric_or_resource.labels}` と表示されます。
`metric_or_resource.label.KEY`	`KEY` が有効なラベルである場合、この変数は `${metric.label.KEY}` の値として通知に表示されます。 `KEY` が有効なリソースの場合、この変数は `${resource.label.KEY}` の値として通知に表示されます。 `KEY` が有効なラベルでも有効なリソースでもない場合、この変数は通知に空の文字列として表示されます。 Prometheus アラートルールを移行すると、アラートポリシーのドキュメント構成で、Prometheus アラートのフィールドテンプレート `{{$labels.KEY}}` と `{{humanize $labels.KEY}}` が `${metric_or_resource.labels.KEY}` と表示されます。
`policy.name`	ポリシーの REST リソース名（例: `projects/foo/alertPolicies/1234`）
`policy.display_name`	ポリシーの表示名（例: `High CPU rate of change`）
`policy.user_label.KEY`	ユーザーラベル `KEY` の値 ¹ キーは小文字で始める必要があります。キーと値には、小文字、数値、アンダースコア、ダッシュのみを使用できます。
`project`	指標スコープのスコーププロジェクトの ID（`a-gcp-project` など）。
`resource.type`	モニタリング対象リソースタイプ（例: `gce_instance`）。
`resource.project`	アラートポリシーのモニタリング対象リソースのプロジェクト ID
`resource.label.KEY`	リソースラベル`KEY`の値。^1,2,3 モニタリング対象リソースタイプに関連付けられたラベルを確認するには、リソースリストをご覧ください。

¹ たとえば、${resource.label.zone} は zone ラベルの値に置き換えられます。これらの変数の値はグループ化されます。詳細については、null の値をご覧ください。
² アラートポリシーでモニタリング対象リソース上の project_id ラベルの値を取得するには、${resource.project} を使用します。
³ resource.label.KEY. を使用して、ユーザー定義のリソースメタデータラベルにアクセスすることはできません。代わりに metadata.user_label.KEY を使用してください。

使用上の注意:

表に記載している変数のみがサポートされています。${varname1 + varname2} のような、より複雑な式とそれらを組み合わせることはできません。
リテラル文字列 ${ をドキュメントに含めるには、$ 記号を 2 つ目の $ 記号でエスケープします。$${ はドキュメントでは ${ としてレンダリングされます。
これらの変数は、通知チャネルを介して送信される通知でのみ、値に置き換えられます。Google Cloud Console では、ドキュメントが表示されるときに、値ではなく変数が表示されます。コンソールの例には、インシデントの説明や、アラートポリシー作成時のドキュメントのプレビューなどがあります。
条件の集計設定でラベルが削除されていないことを確認します。ラベルが除外されると、通知に含まれるラベルの値は null になります。詳細については、指標ラベルの変数が null であるをご覧ください。

例

次の例は、CPU 使用率アラートポリシーのテンプレートドキュメントの Google Cloud コンソールと Cloud Monitoring API バージョンと、通知本文に表示されるレンダリングされたドキュメントを示しています。この例では、通知チャネルタイプにメールを使用しています。ドキュメントテンプレートには、インシデントを要約し、アラートポリシーと条件 REST リソースを参照するための変数がいくつか含まれています。

Google Cloud コンソール

## CPU utilization exceeded

### Summary

The ${metric.display_name} of the ${resource.type}
${resource.label.instance_id} in the project ${resource.project} has
exceeded 90% for over 15 minutes.

### Additional resource information

Condition resource name: ${condition.name}
Alerting policy resource name: ${policy.name}

### Troubleshooting and Debug References

Repository with debug scripts: example.com
Internal troubleshooting guide: example.com
${resource.type} dashboard: example.com

Cloud Monitoring API

"documentation": {
"content": "## CPU utilization exceeded\n\n### Summary\n\nThe ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

通知の形式

通知でのドキュメントの表示例

`null` 個の値

metric.*、resource.*、metadata.* 変数の値は時系列から派生します。時系列クエリから返される値がない場合、値は null になる可能性があります。

アラートポリシーでクロス系列集約（縮約）が使用されている場合は、resource.label.KEY 変数と metric.label.KEY 変数で null 値を使用できます（たとえば、フィルタに一致する各時系列全体で SUM を計算する場合など）。クロス系列集約を使用する場合、グループ化に使用されていないラベルはドロップされ、変数がその値で置き換えられると null としてレンダリングされます。クロス系列集計がない場合、すべてのラベルは保持されます。詳細については、指標ラベルの変数が null であるをご覧ください。
metadata.* 変数の値は、クロス系列集計の条件のフィルタまたはグループにラベルが明示的に含まれている場合にのみ、使用できます。つまり、フィルタまたはグループでメタデータラベルを参照して、テンプレートの値を取得する必要があります。

変数の解決

ドキュメントテンプレートの変数は、次の通知チャネルを使用して送信される通知でのみ解決されます。

メール
Slack
Pub/Sub、JSON スキーマバージョン 1.2
Webhooks、JSON スキーマバージョン 1.2
PagerDuty、JSON スキーマバージョン 1.2

変数は解決されませんが、以下を含む他のコンテキストでは、${varname} のような文字列として表示されます。

Google Cloud コンソールの [インシデントの詳細] ページ。
他の通知チャネルを使用して送信される通知。

チャネルコントロールの使用

ドキュメントフィールド内のテキストには、通知チャネル自体がフォーマットや通知を制御するために使用する特殊文字を含めることもできます。

たとえば、Slack では @ が使用されます。@ を使用して、通知を特定のユーザーにリンクできます。名前リンクに名前を含めることはできません。ドキュメントフィールドに次のような文字列を含めているとします。

<@backendoncall> Incident created based on policy ${policy.display_name}

ドキュメントフィールドが、関連する Slack チャンネルによって通知の一部として受信されると、上記の文字列によって Slack はユーザー ID backendoncall に追加メッセージを送信します。Slack からユーザーに送信されるメッセージには、通知からの関連情報が含まれる場合があります。例: 「ポリシーに基づいて作成されたインシデントの高い CPU の変更率」。

これらの追加オプションはチャネルに固有です。利用可能な追加オプションの詳細については、チャネルベンダーが提供しているドキュメントをご覧ください。