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

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

ドキュメントの構造

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

サブジェクト

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

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

Cloud Monitoring API

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

Google Cloud コンソール

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

コンテンツ

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

  • メール([Policy Documentation] ヘッダーの下)
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhook

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

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

Cloud Monitoring API

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

Google Cloud コンソール

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

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

Cloud Monitoring API

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

  • メール([クイックリンク] ヘッダーの下)
  • PagerDuty
  • Pub/Sub
  • Webhook

リンクを構成するには、アラート ポリシーの documentationLink を追加します。各リンクは display_nameurl で表されます。ドキュメントには最大 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 システム提供のリソース メタデータ ラベルの値 KEY1
metadata.user_label.KEY ユーザー定義のリソース メタデータ ラベルの値 KEY1、3
metric.type 指数タイプ。例:
compute.googleapis.com/instance/cpu/utilization
metric.display_name 指数タイプの表示名。例: CPU utilization
metric.label.KEY

指標ラベル KEY の値。1
指標タイプに関連付けられたラベルを確認するには、指標リストをご覧ください。

変数 ${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 は特定のラベル名(regionversion など)です。

使用例: ${metric.label.metadata_system_version}

metric.label.metadata_user_VALUE

PromQL メタデータ ユーザーラベルを参照します。ここで、VALUE は特定のラベル名(regionname など)です。

使用例: ${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 の値 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 コンソールでドキュメントが表示されている場合、値ではなく変数が表示されます。コンソールの例には、インシデントの説明や、アラート ポリシー作成時のドキュメントのプレビューなどがあります。
  • 条件の集計設定でラベルが除外されないようにします。ラベルが削除されている場合、通知のラベルの値は 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

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

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