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

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

ドキュメントの構造

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

サブジェクト

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

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

コンテンツ

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

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

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

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

リンク

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

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

### Troubleshooting and Debug References

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

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

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

• ヘッダー。最初のハッシュ文字で示されます。
• 順序付けられていないリスト。最初のプラス、マイナス、またはアスタリスク文字で示されます。
• 順序付きリスト。最初の番号とそれに続くピリオドで示されます。
• フレーズの前後に単一の下線またはアスタリスクで示される斜体のテキスト。
• フレーズの前後に二重下線またはアスタリスクで示される太字のテキスト。
• リンク。[link text](url) 構文で示されます。 ただし、Link オブジェクトを使用してコンテンツのリンクを構成することをおすすめします。

このタグ付けの詳細については、Markdown のリファレンス、たとえば Markdown ガイドをご覧ください。

ドキュメント内の変数

ドキュメント内のテキストをカスタマイズするには、${varname} 形式の変数を使用します。ドキュメントが通知付きで送信されると、次の表に示すように、文字列 ${varname} は、対応する Google Cloud リソースから取得された値に置き換えられます。

¹ たとえば、${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 リソースを参照するためのいくつかの変数が含まれています。

  "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"
      }
    ]
  }

### 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