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

このページでは、通知でインシデント対応者にリソースとインシデント解決のための追加情報を提供できるように、アラートポリシーのドキュメントを構成する方法について説明します。

ドキュメントの構造

アラートポリシーのドキュメントは、サブジェクト、コンテンツ、リンクで構成されています。ドキュメントは、 Google Cloud コンソール、Cloud Monitoring API、Google Cloud CLI で構成できます。

サブジェクト

ドキュメントの件名は、アラートポリシーに関連するインシデントの通知の件名に表示されます。通知の受信者は、通知を管理し、件名で並べ替えることができます。

件名は 255 文字以内にする必要があります。ドキュメントで件名を定義しない場合、Cloud Monitoring によって件名が決定されます。件名は、書式なしテキストと変数をサポートしています。

Cloud Monitoring API

アラートポリシー documentation の subject フィールドを使用して、通知の件名を構成します。

Google Cloud コンソール

[アラートポリシーを作成] の [通知と名前] セクションの [通知の件名] フィールドを使用して、通知の件名を構成します。

コンテンツ

ドキュメントのコンテンツは、次の通知タイプに表示されます。

メール（[Policy Documentation] ヘッダーの下）
PagerDuty
Pub/Sub
Slack
Webhook

インシデント対応者がアラートポリシーに関連する通知で修正手順とインシデント情報を確認できるように、コンテンツを構成することをおすすめします。たとえば、インシデントの概要と関連リソースに関する情報をドキュメントに含めるように構成できます。

ドキュメントコンテンツは、以下をサポートしています。

Cloud Monitoring API

アラートポリシー documentation の content フィールドを使用して、ドキュメントのコンテンツを構成します。

Google Cloud コンソール

[アラートポリシーを作成] ページの [通知と名前] セクションにある [ドキュメント] フィールドを使用して、ドキュメントのコンテンツを構成します。

リンク

ドキュメントにリンクを追加すると、インシデント対応車が通知からハンドブック、リポジトリ、 Google Cloud ダッシュボードなどのリソースにアクセスできるようになります。

Cloud Monitoring API

Cloud Monitoring API で構成されたドキュメントリンクは、次の通知タイプに表示されます。

メール（[クイックリンク] ヘッダーの下）
PagerDuty
Pub/Sub
Webhook

リンクを構成するには、アラートポリシーの 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 コンソールで構成されたドキュメントリンクは、次の通知タイプで他のドキュメントコンテンツとともに表示されます。

メール（[Policy Documentation] ヘッダーの下）
PagerDuty
Pub/Sub
Slack
Webhook

ドキュメントコンテンツへのリンクを追加するには、アラートポリシーの [ドキュメント] フィールドにリンクを追加します。たとえば、次のドキュメントには、顧客向けハンドブックの 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`。¹
`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}` と表示されます。この場合、`${metric.label.value}` は Prometheus アラートルールのトリガー値を保持します。 Google Cloudで PromQL クエリを作成するときに `${metric.label.value}` を使用することもできます。
`metric.label.metadata_system_VALUE`	PromQL メタデータシステムラベルを参照します。ここで、`VALUE` は特定のラベル名（`region` や `version` など）です。使用例: `${metric.label.metadata_system_version}`
`metric.label.metadata_user_VALUE`	PromQL メタデータユーザーラベルを参照します。ここで、`VALUE` は特定のラベル名（`region` や `name` など）です。使用例: `${metric.label.metadata_user_name}`
`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 コンソールでドキュメントが表示されている場合、値ではなく変数が表示されます。コンソールの例には、インシデントの説明や、アラートポリシー作成時のドキュメントのプレビューなどがあります。
条件の集計設定でラベルが除外されないようにします。ラベルが削除されている場合、通知のラベルの値は 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 変化率が高いこと警告するポリシーに基づいて作成されたインシデント」など）。

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

例

次の例は、 Google Cloud コンソールと Cloud Monitoring API での CPU 使用率アラートポリシーのテンプレートドキュメントを示しています。これらの例では、通知チャンネルにメールを使用しています。ドキュメントテンプレートには、インシデントを要約し、アラートポリシーと条件 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

次の図は、このテンプレートがメール通知でどのように表示されるかを示しています。

通知でのドキュメントの表示例リンクは「トラブルシューティングとデバッグに関するリファレンス」ヘッダーの下に表示されます。

ユーザー定義のドキュメントで通知にアノテーションを付ける コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ドキュメントの構造

サブジェクト

Cloud Monitoring API

Google Cloud コンソール

コンテンツ

Cloud Monitoring API

Google Cloud コンソール

リンク

Cloud Monitoring API

Google Cloud コンソール

ドキュメント コンテンツのマークダウン

ドキュメントの変数

使用上の注意

null の値

変数の解決

チャンネル制御

例

Cloud Monitoring API

Google Cloud コンソール

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

ドキュメントコンテンツのマークダウン

`null` の値