このページでは、通知によってインシデント対応者にリソースやインシデント解決のための追加情報が提供されるように、アラート ポリシーのドキュメントを構成する方法について説明します。
ドキュメントの構造
アラート ポリシーのドキュメントは、件名、コンテンツ、リンクで構成されます。ドキュメントは、Google Cloud コンソール、Cloud Monitoring API、Google Cloud CLI で構成できます。
サブジェクト
ドキュメントの件名は、アラート ポリシーに関連するインシデントの通知の件名に表示されます。通知の受信者は、通知を管理し、件名で並べ替えることができます。
件名は 255 文字に制限されています。ドキュメントで件名を定義しない場合、Cloud Monitoring によって件名が決定されます。件名では書式なしテキストと変数を使用できます。
Cloud Monitoring API
アラート ポリシー documentation
の subject
フィールドを使用して、通知の件名を構成します。
Google Cloud コンソール
[アラート ポリシーを作成] の [通知と名前] セクションの [通知の件名] フィールドを使用して、通知の件名を構成します。
コンテンツ
ドキュメントのコンテンツは、次の通知タイプで表示されます。
- メール([ポリシー ドキュメント] ヘッダーの下)
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
インシデント対応者がアラート ポリシーに関連する通知で修復手順とインシデント情報を表示できるように、コンテンツを構成することをおすすめします。たとえば、インシデントの概要と関連リソースに関する情報を含めるようにドキュメントを構成できます。
ドキュメントのコンテンツは、書式なしテキスト、マークダウン、変数、チャンネル固有のコントロールをサポートしています。
Cloud Monitoring API
アラート ポリシー documentation
の content
フィールドを使用して、ドキュメント コンテンツを構成します。
Google Cloud コンソール
[アラート ポリシーを作成] ページの [通知と名前] セクションにある [ドキュメント] フィールドを使用して、ドキュメントのコンテンツを構成します。
リンク
インシデント対応者が通知からハンドブック、リポジトリ、Google Cloud ダッシュボードなどのリソースにアクセスできるように、ドキュメントにリンクを追加できます。
Cloud Monitoring API
Cloud Monitoring API で構成されたドキュメント リンクは、次の通知タイプに表示されます。
- メール([クイックリンク] ヘッダーの下)
- PagerDuty
- Pub/Sub
- Webhooks
リンクを構成するには、アラート ポリシーの documentation
に Link
を追加します。各リンクは、display_name
と url
で表されます。ドキュメントには最大 3 つのリンクを含めることができます。
次の構成では、1 つの URL で links
を使用して、インシデント ハンドブックへのリンクを作成します。この URL には、インシデントが発生したモニタリング対象リソースに基づいて、通知の受信者が正しいハンドブックにアクセスできるように、変数含まれています。
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Google Cloud コンソール
Google Cloud コンソールで構成されたドキュメント リンクは、残りのドキュメント コンテンツとともに次の通知タイプで表示されます。
- メール([ポリシー ドキュメント] ヘッダーの下)
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
アラート ポリシーの [ドキュメント] フィールドにドキュメント コンテンツへのリンクを追加できます。たとえば、次のドキュメントには、カスタマー ハンドブックの URL が記載されています。
### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
ドキュメント コンテンツ内のマークダウン
マークダウンを使用して、ドキュメント コンテンツをフォーマットできます。ドキュメント コンテンツは、マークダウン タグ付けの次のサブセットをサポートします。
- ヘッダー。最初のハッシュ文字で示されます。
- 順序付けられていないリスト。最初のプラス、マイナス、またはアスタリスク文字で示されます。
- 順序付きリスト。最初の番号とそれに続くピリオドで示されます。
- フレーズの前後に単一の下線またはアスタリスクで示される斜体のテキスト。
- フレーズの前後に二重下線またはアスタリスクで示される太字のテキスト。
- リンク。
[link text](url)
構文で示されます。 ただし、Link
オブジェクトを使用してコンテンツのリンクを構成することをおすすめします。
このタグ付けの詳細については、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 。1 |
metadata.user_label.KEY |
ユーザー定義のリソース メタデータ ラベルの値 KEY 。1,3 |
metric.type |
指数タイプ(例: compute.googleapis.com/instance/cpu/utilization ) |
metric.display_name |
指数タイプの表示名(例: CPU utilization ) |
metric.label.KEY |
指標ラベル 変数 Prometheus アラートルールを移行すると、アラート ポリシーのドキュメント構成で、Prometheus アラートのフィールド テンプレート Google Cloud で PromQL クエリを作成するときに、 |
metric_or_resource.labels |
この変数は、すべての指標とリソースラベルの値を並べ替えられた Prometheus アラートルールを移行すると、アラート ポリシーのドキュメント構成で、Prometheus アラートのフィールド テンプレート |
metric_or_resource.label.KEY |
Prometheus アラートルールを移行すると、アラート ポリシーのドキュメント構成で、Prometheus アラートのフィールド テンプレート |
policy.name |
ポリシーの REST リソース名(例: projects/foo/alertPolicies/1234 ) |
policy.display_name |
ポリシーの表示名(例: High CPU rate of change ) |
policy.user_label.KEY |
ユーザーラベル KEY の値 1キーは小文字で始める必要があります。キーと値には、小文字、数値、アンダースコア、ダッシュのみを使用できます。 |
project |
指標スコープのスコープ対象プロジェクトの ID(a-gcp-project など)。 |
resource.type |
モニタリング対象リソースタイプ(例: gce_instance )。 |
resource.project |
アラート ポリシーのモニタリング対象リソースのプロジェクト ID |
resource.label.KEY |
リソースラベルKEY の値。1,2,3モニタリング対象リソースタイプに関連付けられたラベルを確認するには、リソースリストをご覧ください。 |
1 たとえば、${resource.label.zone}
は zone
ラベルの値に置き換えられます。これらの変数の値はグループ化されます。詳細については、null
の値をご覧ください。
2 アラート ポリシーでモニタリング対象リソース上の project_id
ラベルの値を取得するには、${resource.project}
を使用します。
3 resource.label.KEY.
を使用して、ユーザー定義のリソース メタデータ ラベルにアクセスすることはできません。代わりに metadata.user_label.KEY
を使用してください。
使用上の注意
- 表に記載している変数のみがサポートされています。
${varname1 + varname2}
のような、より複雑な式とそれらを組み合わせることはできません。 - リテラル文字列
${
をドキュメントに含めるには、$
記号を 2 つ目の$
記号でエスケープします。$${
はドキュメントでは${
としてレンダリングされます。 - これらの変数は、通知チャネルを介して送信される通知でのみ、値に置き換えられます。Google Cloud Console では、ドキュメントが表示されるときに、値ではなく変数が表示されます。コンソールの例には、インシデントの説明や、アラート ポリシー作成時のドキュメントのプレビューなどがあります。
- 条件の集計設定によってラベルが削除されないようにしてください。ラベルが削除されると、通知のラベルの値は
null
になります。詳細については、指標ラベルの変数が null ですをご覧ください。
null
個の値
metric.*
、resource.*
、metadata.*
変数の値は時系列から派生します。時系列クエリから返される値がない場合、値は null
になる可能性があります。
アラート ポリシーでクロス系列集約(縮約)が使用されている場合は、
resource.label.KEY
変数とmetric.label.KEY
変数でnull
値を使用できます(たとえば、フィルタに一致する各時系列全体で SUM を計算する場合など)。クロス系列集約を使用する場合、グループ化に使用されていないラベルはドロップされ、変数がその値で置き換えられるとnull
としてレンダリングされます。クロス系列集計がない場合、すべてのラベルは保持されます。 詳細については、指標ラベルの変数が null ですをご覧ください。metadata.*
変数の値は、クロス系列集計の条件のフィルタまたはグループにラベルが明示的に含まれている場合にのみ、使用できます。つまり、フィルタまたはグループでメタデータ ラベルを参照して、テンプレートの値を取得する必要があります。
変数の解決
ドキュメント テンプレートの変数は、次の通知チャネルを使用して送信される通知でのみ解決されます。
- メール
- Google Chat
- Slack
- Pub/Sub、JSON スキーマ バージョン 1.2
- Webhooks、JSON スキーマ バージョン 1.2
- PagerDuty、JSON スキーマ バージョン 1.2
チャネル コントロール
ドキュメント フィールド内のテキストには、通知チャネル自体がフォーマットや通知を制御するために使用する特殊文字を含めることもできます。
たとえば、Slack では @
が使用されます。@
を使用すると、通知を特定のユーザー ID にリンクできます。名前リンクには名前を含めることはできません。
ドキュメント フィールドに次のような文字列を含めているとします。
<@backendoncall> Incident created based on policy ${policy.display_name}
ドキュメント フィールドが、関連する Slack チャンネルによって通知の一部として受信されると、上記の文字列により、Slack からユーザー ID backendoncall
に追加のメッセージが送信されます。Slack からユーザーに送信されるメッセージには、通知の関連情報(「ポリシーの CPU 変更率に基づいてインシデントが作成されました」など)が含まれる場合があります。
これらの追加オプションはチャネルに固有です。利用可能な追加オプションの詳細については、チャネル ベンダーが提供しているドキュメントをご覧ください。
例
次の例は、CPU 使用率アラート ポリシーのテンプレート ドキュメントの Google Cloud コンソールと Cloud Monitoring API バージョンを示しています。これらの例では、通知チャネルタイプにメールを使用します。ドキュメント テンプレートには、インシデントを要約し、アラート ポリシーと条件 REST リソースを参照するためのいくつかの変数が含まれています。
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 5% for over 60 seconds.\n\n#### Additional resource information\n\nCondition resource name: ${condition.name} \nAlerting policy resource name: ${policy.name}",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded",
"links": [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
},
{
"displayName": "Repository with debug scripts",
"url": "https://altostrat.com"
},
{
"displayName": "Google Cloud dashboard",
"url": "https://example.com"
}
]
}
次の図は、このテンプレートがメール通知でどのように表示されるかを示しています。
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 5% for over 60 seconds. #### Additional resource information Condition resource name: ${condition.name} Alerting policy resource name: ${policy.name} #### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type} Repository with debug scripts: https://altostrat.com ${resource.type} dashboard: https://example.com
次の図は、このテンプレートがメール通知でどのように表示されるかを示しています。