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

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

ドキュメントの構造

アラートポリシーのドキュメントは、件名、コンテンツ、リンクで構成されます。ドキュメントは、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`。¹
`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 ですをご覧ください。

`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

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

通知でのドキュメントの表示例リンクは [Troubleshooting and Debug References] ヘッダーの下に表示されます。

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

ドキュメントの構造

サブジェクト

Cloud Monitoring API

Google Cloud コンソール

コンテンツ

Cloud Monitoring API

Google Cloud コンソール

リンク

Cloud Monitoring API

Google Cloud コンソール

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

ドキュメント内の変数

使用上の注意

null 個の値

変数の解決

チャネル コントロール

例

Cloud Monitoring API

Google Cloud コンソール

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

`null` 個の値

チャネルコントロール