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

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

ドキュメントの構造

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

サブジェクト

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

件名は 255 文字に制限されています。ドキュメントで件名を定義しない場合、Cloud Monitoring によって件名が決定されます。件名では書式なしテキストと変数を使用できます。

Cloud Monitoring API

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

Google Cloud コンソール

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

コンテンツ

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

  • メール([ポリシー ドキュメント] ヘッダーの下)
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhooks

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

ドキュメントのコンテンツは、書式なしテキスト、マークダウン変数チャンネル固有のコントロールをサポートしています。

Cloud Monitoring API

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

Google Cloud コンソール

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

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

Cloud Monitoring API

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

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

リンクを構成するには、アラート ポリシーの documentationLink を追加します。各リンクは、display_nameurl で表されます。ドキュメントには最大 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 システム提供のリソース メタデータ ラベルの値 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} と表示されます。この場合、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 の値 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

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

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