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

このページでは、アラート ポリシーのドキュメント フィールドに含めることができるコンテンツについて説明します。このフィールドは、書式なしテキスト、Markdown、変数、チャンネル固有のコントロールをサポートします。

Markdown を使用する

ドキュメント フィールドは、Markdown タグ付けの次のサブセットをサポートします。

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

このタグ付けの詳細については、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。1
metadata.user_label.KEY ユーザー定義のリソース メタデータ ラベルの値 KEY。1,3
metric.type 指数タイプ（例:
compute.googleapis.com/instance/cpu/utilization）
metric.display_name 指数タイプの表示名（例: CPU utilization）
metric.label.KEY

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

変数 ${metric.label.KEY} の値が数字、文字、スラッシュ（/）、または等号（=）で始まっていない場合、Monitoring は通知のラベルを 省略します。

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 を使用してください。

null 個の値

metric.*、resource.*、metadata.* 変数の値は時系列から派生します。時系列クエリから返される値がない場合、値は null になる可能性があります。

  • アラート ポリシーでクロス系列集約（縮約）が使用されている場合は、resource.label.KEY 変数と metric.label.KEY 変数で null 値を使用できます（たとえば、フィルタに一致する各時系列全体で SUM を計算する場合など）。クロス系列集約を使用する場合、グループ化に使用されていないラベルはドロップされ、変数がその値で置き換えられると null としてレンダリングされます。クロス系列集計がない場合、すべてのラベルは保持されます。
  • metadata.* 変数の値は、クロス系列集計の条件のフィルタまたはグループにラベルが明示的に含まれている場合にのみ、使用できます。つまり、フィルタまたはグループでメタデータ ラベルを参照して、テンプレートの値を取得する必要があります。

その他の使用上の注意

  • 表に記載している変数のみがサポートされています。${varname1 + varname2} のような、より複雑な式とそれらを組み合わせることはできません。
  • リテラル文字列 ${ をドキュメントに含めるには、$ 記号を 2 つ目の $ 記号でエスケープします。$${ はドキュメントでは ${ としてレンダリングされます。
  • これらの変数は、通知チャネルを介して送信される通知でのみ、値に置き換えられます。Google Cloud Console では、ドキュメントが表示されるときに、値ではなく変数が表示されます。コンソールの例には、インシデントの説明や、アラート ポリシー作成時のドキュメントのプレビューなどがあります。

チャネル コントロールの使用

ドキュメント フィールド内のテキストには、通知チャネル自体がフォーマットや通知を制御するために使用する特殊文字を含めることもできます。

たとえば、Slack では @ が使用されます。これを使用して、通知を特定のユーザーにリンクできます。ドキュメント フィールドに次のような文字列を含めているとします。

<@backendoncall> policy ${policy.display_name} triggered an incident

ドキュメント フィールドが、関連する Slack チャンネルによって通知の一部として受信されると、この行によってユーザー backendoncall（policy High CPU rate of change triggered an incident など）に対する追加メッセージがトリガーされます。名前リンクは、名前ではなくユーザー ID を参照する必要があります。

これらの追加オプションはチャネルに固有です。利用可能な追加オプションの詳細については、チャネル ベンダーが提供しているドキュメントをご覧ください。