このページは Cloud Translation API によって翻訳されました。

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

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

ドキュメントの構造

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

サブジェクト

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

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

Cloud Monitoring API

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

Google Cloud コンソール

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

コンテンツ

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

メール（[ポリシーに関するドキュメント] の下）
PagerDuty
Pub/Sub
Slack
Webhook

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

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

書式なしテキスト
変数
チャンネル固有のコントロール
Slack 以外の通知チャネルでのMarkdown

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

メール（[ポリシーに関するドキュメント] の下）
PagerDuty
Pub/Sub
Slack
Webhook

ドキュメントコンテンツへのリンクを追加するには、アラートポリシーの [Documentation] フィールドにリンクを追加します。たとえば、次のドキュメントには、お客様向けプレイブックの URL が記載されています。

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

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

Markdown を使用してドキュメントの内容をフォーマットできます。ドキュメントコンテンツは、マークダウンタグ付けの次のサブセットをサポートします。

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

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

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

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

ドキュメントの構造

サブジェクト

Cloud Monitoring API

Google Cloud コンソール

コンテンツ

Cloud Monitoring API

Google Cloud コンソール

リンク

Cloud Monitoring API

Google Cloud コンソール

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

ドキュメントの変数

使用上の注意

null 個の値

変数の解決

チャネル コントロール

例

Cloud Monitoring API

Google Cloud コンソール

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

`null` 個の値

チャネルコントロール