Webhook カスタム Body テンプレート¶

テンプレート構文を使用して、Webhook 通知の Body 内容をカスタマイズできます。

動的レンダリング：{{ フィールド名 }} を使用してアラートフィールドを直接挿入します（例：{{ host }}、{{ df_status }}）。
データ処理：{{ 変数 | 関数() }} でデータを書式設定します（例：タイムスタンプ→日付、数値→パーセンテージ）。
条件分岐：{% if ... %} を使用して、ステータスに応じた Body の差分出力を実現します。
JSON 出力：to_json_dumps を使用して JSON オブジェクト、配列、数値、真偽値などを出力します。
リアルタイムクエリ：DQL("クエリ文") を埋め込んで関連データ（ホスト IP、システム情報など）を取得します。

基本テンプレート変数¶

テンプレート変数の基本構文は {{ フィールド名 }} で、イベントに関連する動的情報をレンダリングするために使用します。以下は Webhook カスタム Body でよく使われるテンプレート変数とその用途です。

テンプレート変数	型	説明
`date`、`timestamp`	Integer	イベント発生時刻（Unix タイムスタンプ、秒）
`df_status`	String(Enum)	イベントステータス。取りうる値：`critical`（緊急）、`error`（重要）、`warning`（警告）、`ok`（正常）、`nodata`（データ欠落）
`df_event_id`	String	イベントの一意の ID
`df_event_link`	String	イベント詳細ページのリンク
`df_title`	String	イベントタイトル
`df_message`	String	イベント内容
`df_dimension_tags`	String	イベントディメンション。検出対象を識別します（例：`{"host":"web-001"}`）
`df_dimension_tags_obj`	Dict	イベントディメンションオブジェクト。ディメンションフィールドをオブジェクトとして読み取れます
`df_monitor_id`	String	アラートポリシー ID
`df_monitor_name`	String	アラートポリシー名
`df_monitor_checker_id`	String	モニター ID
`df_monitor_checker_name`	String	モニター名
`df_monitor_checker_value`	String	検出値（モニターが検出した値）
`Result`	Integer, Float, String, Dict, List	検出された生の値。`df_monitor_checker_value` と同じく検出時に生成される値ですが、元の型を保持します
`Result_with_unit`	String	単位付きの検出値
`df_related_data`	Dict	関連データ
`df_fault_id`	String	今回の障害 ID。初回障害イベントの `df_event_id` と同じ値
`df_fault_status`	String(Enum)	今回の障害ステータス。取りうる値：`ok`（正常）、`fault`（障害）
`df_fault_start_time`	Integer	今回の障害発生時刻（Unix タイムスタンプ、秒）
`df_fault_duration`	Integer	今回の障害継続時間（秒）
`df_site_name`	String	現在の Guance ノード名
`df_workspace_name`	String	所属ワークスペース名
`df_workspace_uuid`	String	所属ワークスペース ID
`df_label`	List	モニターのラベル一覧
`df_alert_policy_names`	List	ヒットしたアラートポリシー名の一覧
`df_sent_target_types`	List	このイベントで送信済みのアラート通知先タイプの一覧
`df_event`	Dict	完全なイベントデータ
`df_dimension_tags` 内の各フィールド	String	`df_dimension_tags` 内の各フィールドはトップレベルに展開されます（`host`、`region` など）

注意：

df_monitor_checker_value は互換性を確保するため強制的に String 型に変換されます。
検出値の元の型を保持したい場合は、Result を使用することを推奨します。
モニターの種類、イベントソース、通知シナリオによって、利用可能な変数が異なる場合があります。

テンプレート変数の例¶

モニター by に region と host が設定されている場合、Webhook カスタム Body テンプレートは次のようになります。

{
  "title": "モニター {{ df_monitor_checker_name }} が {{ df_dimension_tags }} に障害を検出",
  "region": "{{ region }}",
  "host": "{{ host }}",
  "status": "{{ df_status }}",
  "value": "{{ Result }}",
  "monitor": "{{ df_monitor_checker_name }}",
  "policy": "{{ df_monitor_name }}"
}

error イベントが発生した場合、レンダリング後の Body は次のように出力されます。

{
  "title": "モニター モニター001 が {\"region\":\"hangzhou\",\"host\":\"web-001\"} に障害を検出",
  "region": "hangzhou",
  "host": "web-001",
  "status": "error",
  "value": "90.12345",
  "monitor": "モニター001",
  "policy": "チーム001"
}

JSON Body の出力¶

Webhook カスタム Body は最終的に有効な JSON を出力する必要があります。JSON オブジェクトを定義してから to_json_dumps 関数で処理することを推奨します。これにより、文字列のエスケープ、オブジェクトや配列のネスト、カンマの欠落といった JSON 構文エラーを回避できます。

例：

{% set json_data = {
  "event_id": df_event_id,
  "title": df_title,
  "status": df_status,
  "status_text": df_status | to_status_human,
  "event_link": df_event_link,
  "monitor": {
    "id": df_monitor_id,
    "name": df_monitor_name,
    "checker_id": df_monitor_checker_id,
    "checker_name": df_monitor_checker_name
  },
  "dimension": {
    "raw": df_dimension_tags,
    "object": df_dimension_tags_obj,
    "pretty": df_dimension_tags | to_pretty_tags
  },
  "value": {
    "raw": Result,
    "with_unit": Result_with_unit,
    "type": Result | type_name
  }
} %}
{{ json_data | to_json_dumps }}

出力結果は次のとおりです。

{
  "event_id": "event-xxxxx",
  "title": "CPU 使用率が高すぎます",
  "status": "error",
  "status_text": "重要",
  "event_link": "https://console.guance.com/keyevents/monitor/events/event-xxxxx",
  "monitor": {
    "id": "altpl_xxxxx",
    "name": "チーム001",
    "checker_id": "rul_xxxxx",
    "checker_name": "モニター001"
  },
  "dimension": {
    "raw": "{\"region\":\"hangzhou\",\"host\":\"web-001\"}",
    "object": {
      "region": "hangzhou",
      "host": "web-001"
    },
    "pretty": "region:hangzhou, host:web-001"
  },
  "value": {
    "raw": 90.12345,
    "with_unit": "90.12345%",
    "type": "float"
  }
}

フィールドごとに JSON をレンダリング¶

フィールドごとに JSON をレンダリングすることもできます。その場合はフィールドの型に注意してください。

{
  "event_id": "{{ df_event_id }}",
  "status": "{{ df_status }}",
  "status_text": "{{ df_status | to_status_human }}",
  "checker_name": "{{ df_monitor_checker_name }}",
  "dimension": {{ df_dimension_tags_obj | to_json_dumps }},
  "value": {{ Result | to_json_dumps }},
  "related_data": {{ df_related_data | to_json_dumps }}
}

説明：

文字列フィールドはダブルクォーテーションで囲みます（例："{{ df_status }}"）。
オブジェクト、配列、数値、真偽値には to_json_dumps を使用することを推奨します。
オブジェクトや配列を "{{ df_related_data }}" のように記述しないでください。受信側で文字列として扱われ、JSON オブジェクトとして認識されなくなります。

特殊シナリオの変数¶

RUM メトリクス検出¶

RUM メトリクス検出では、上記の汎用テンプレート変数に加えて、次のテンプレート変数が使用できます。

テンプレート変数	型	説明
`app_id`	String	アプリケーション ID
`app_name`	String	アプリケーション名
`app_type`	String	アプリケーションタイプ

特殊文字を含むフィールドの処理¶

検出設定の「ディメンション」フィールドに特殊文字（-、@ など）が含まれている場合（例：host-name、@level）、通常の変数名として使用できず、テンプレートのレンダリングに失敗します。

誤った記述：

{{ host-name }}
{{ @level }}

解決策として、次の形式で参照します。

{{ df_event["host-name"] }}
{{ df_event["@level"] }}
{{ df_dimension_tags_obj["host-name"] }}
{{ df_dimension_tags_obj["@level"] }}

テンプレート関数¶

イベントのフィールド値をそのまま表示するだけでなく、テンプレート関数を使用してフィールド値をさらに加工し、出力を最適化することもできます。

基本構文は次のとおりです。

{{ <テンプレート変数> | <テンプレート関数> }}
{{ <テンプレート変数> | <テンプレート関数>(パラメータ) }}

具体例：

イベント発生時刻：{{ date | to_datetime }}

テンプレート関数を使用する前にテンプレート変数に対して演算を行う場合は、括弧を忘れずに追加してください。

CPU 使用率：{{ (Result * 100) | to_round(2) }}

使用可能なテンプレート関数の一覧は次のとおりです。

テンプレート関数	パラメータ	説明
`to_datetime`	`tz="Asia/Shanghai"`	Unix 秒単位のタイムスタンプまたは ISO8601 日付文字列を日時文字列に変換
`to_date_range_human`	`lang="zh"`	秒単位の期間を「1 日 2 時間 3 分 1 秒」のような読みやすい形式に変換
`to_status_human`	`lang="zh"`	`df_status` を読みやすいステータスに変換
`to_fixed`	`ndigits=0`	数値を指定した小数点以下の桁数で固定表示
`to_round`	`ndigits=0`	数値を指定した小数点以下の桁数に丸める
`to_percent`	`ndigits=0`	小数をパーセンテージ形式に変換
`to_pretty_tags`	`separators=(':', ', ')`	dict または JSON 文字列形式のタグを読みやすいタグテキストに変換
`limit_lines`	`lines=3, chars=None`	出力行数を制限。同時に 1 行あたりの文字数も制限可能
`limit_chars` / `limit_text`	`chars=50`	出力文字数を制限。`limit_text` は `limit_chars` のエイリアス
`type_name`	なし	データ型の名前を出力
`to_int`	なし	整数に変換
`to_float`	なし	浮動小数点数に変換
`to_str`	なし	文字列に変換
`to_json_dumps`	`indent=None`	dict、list などのデータを JSON シリアライズ文字列に変換
`is_error`	なし	オブジェクトがエラーかどうかを判定。埋め込み DQL の実行が正常かどうかの判断によく使われる
`length`	なし	文字列、リスト、辞書などのオブジェクトの長さを取得
`replace`	`old, new, count=-1`	文字列の内容を置換。`count=-1` はすべて置換
`abs`	なし	数値の絶対値を取得

テンプレート関数の例¶

{% set body = {
  "object": df_dimension_tags | to_pretty_tags,
  "time": date | to_datetime,
  "status": df_status | to_status_human,
  "value": Result | to_fixed(2),
  "percent": Result | to_percent(1),
  "duration": df_fault_duration | to_date_range_human,
  "message": df_message | limit_lines(3, 80)
} %}
{{ body | to_json_dumps }}

テンプレート分岐¶

条件分岐を使用して、ステータスに応じた Body の差分出力を実現できます。

基本構文は次のとおりです。

{% if 条件 %}
  ...
{% elif 条件 %}
  ...
{% else %}
  ...
{% endif %}

テンプレート分岐の例¶

{% set level = "info" %}
{% if df_status == "critical" %}
  {% set level = "critical" %}
{% elif df_status == "error" %}
  {% set level = "error" %}
{% elif df_status == "warning" %}
  {% set level = "warning" %}
{% elif df_status == "nodata" %}
  {% set level = "nodata" %}
{% endif %}

{% set body = {
  "level": level,
  "status": df_status,
  "status_text": df_status | to_status_human,
  "title": df_title,
  "event_link": df_event_link
} %}
{{ body | to_json_dumps }}

埋め込み DQL クエリ関数¶

テンプレート変数だけではレンダリング要件を満たせない場合、埋め込み DQL クエリ関数を使用して補足データを取得できます。埋め込み DQL は、現在のワークスペース、今回の検出時間範囲内で DQL を実行し、通常はクエリ結果の最初のデータをテンプレート変数として使用します。

呼び出し形式は次のとおりです。

{% set dql_data = DQL("DQL 文", パラメータ 1, パラメータ 2) %}

埋め込み DQL クエリの例¶

{% set host_info = DQL("O::HOST:(host_ip, os) { region = ?, host = ? }", region, host) %}

{% set body = {
  "host": host,
  "region": region,
  "host_ip": host_info.host_ip,
  "os": host_info.os,
  "status": df_status,
  "event_link": df_event_link
} %}
{{ body | to_json_dumps }}

埋め込み DQL クエリ関数の詳細¶

埋め込み DQL クエリはテンプレートの先頭に記述してください。
DQL 文中のパラメータプレースホルダ ? は、実際の値に置き換える際に自動エスケープされます。
DQL にテンプレート変数を渡す場合、パラメータ部分は直接変数名（例：host）を記述します。{{ host }} の形式は使用しないでください。
クエリ結果の変数名は、既存のテンプレート変数やテンプレート関数と重複しないようにしてください。
DQL で関数を使用してフィールドを処理する場合は、AS でフィールドにエイリアスを指定することを推奨します。テンプレートから読み取りやすくなります。
DQL クエリ結果のフィールド名に特殊文字が含まれている場合は、{{ host_info["host-name"] }} の形式で読み取ってください。
is_error と組み合わせて、DQL の実行が正常かどうかを判断できます。

完全な Body の例¶

次の例は、アラートイベントを外部イベントセンターに送信する場合に適しています。

{% set is_recovery = df_status == "ok" %}
{% set priority = "P0" if df_status == "critical" else ("P1" if df_status in ["error", "nodata"] else ("P2" if df_status == "warning" else "INFO")) %}

{% set body = {
  "source": "guance",
  "event_id": df_event_id,
  "event_link": df_event_link,
  "title": df_title,
  "status": df_status,
  "status_text": df_status | to_status_human,
  "priority": priority,
  "is_recovery": is_recovery,
  "monitor": {
    "policy_id": df_monitor_id,
    "policy_name": df_monitor_name,
    "checker_id": df_monitor_checker_id,
    "checker_name": df_monitor_checker_name
  },
  "object": {
    "tags": df_dimension_tags_obj,
    "text": df_dimension_tags | to_pretty_tags
  },
  "value": {
    "raw": Result,
    "with_unit": Result_with_unit,
    "fixed_2": Result | to_fixed(2)
  },
  "fault": {
    "fault_id": df_fault_id,
    "fault_status": df_fault_status,
    "start_time": df_fault_start_time | to_datetime,
    "duration_seconds": df_fault_duration,
    "duration_text": df_fault_duration | to_date_range_human
  },
  "notify": {
    "alert_policy_names": df_alert_policy_names,
    "sent_target_types": df_sent_target_types
  }
} %}
{{ body | to_json_dumps }}

注意事項¶

Webhook カスタム Body の最終レンダリング結果は、有効な JSON でなければなりません。
フィールド値にダブルクォーテーション、改行、特殊文字が含まれる可能性がある場合は、to_json_dumps を使用して出力することを推奨します。
オブジェクト、配列、数値、真偽値は、無理に文字列としてラップしないでください。
テンプレートをデバッグする際は、まず少数のフィールドでレンダリング結果を確認し、その後徐々に複雑なフィールドや条件分岐を追加することを推奨します。
Webhook カスタム Body テンプレートはリクエスト Body のレンダリングのみを担当します。リクエスト URL、ヘッダーなどの設定は、引き続き Webhook 通知先オブジェクトで管理します。