コンテンツにスキップ

カスタムイベント通知テンプレート


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

  • 動的レンダリング:{{ フィールド名 }} を使用してアラートフィールドを直接挿入します(例:{{ host }}、{{ df_status }})。

  • データ処理:{{ 変数 | 関数() }} を使用してデータをフォーマットします(例:タイムスタンプから日付、数値からパーセントへの変換)。

  • 条件分岐:{% if ... %} を使用して、状態に応じた異なる通知を実現します。

  • リアルタイムクエリ:DQL("クエリステートメント")を埋め込んで関連データ(例:ホスト IP、アプリケーション情報)を取得します。

テンプレートの検証とプレビュー

モニターのイベント内容、データ欠損イベント内容、およびインテリジェントモニターのイベント内容は構文検証をサポートします。編集後に入力フィールドからフォーカスを外すか、モニターを保存すると、システムがテンプレートをチェックし、構文の問題を指摘します。

構文チェックに合格したら、イベント内容エディターのプレビューボタンをクリックし、必要に応じて変数のテスト値を入力してから、プレビューをクリックしてレンダリング結果を確認します。通常のモニターでは現在のタイトルと内容を同時にプレビューし、インテリジェントモニターではイベント内容をプレビューします。df_status などの変数のテスト値を切り替えて、異常や復旧などの条件分岐を確認できます。

プレビューはテンプレートの効果を確認するためのものです。実際のアラートはイベント発生時のデータに基づきます。テンプレートに埋め込み DQL が含まれる場合、プレビューは現在のワークスペースの関連データを読み取ります。

基本テンプレート変数

テンプレート変数の基本構文は {{ フィールド名 }} で、イベント関連の動的情報をレンダリングするために使用できます。以下は一般的なテンプレート変数とその用途です:

テンプレート変数 型 説明
date、timestamp Integer イベント発生時刻。単位は秒
df_date_range Integer 時間範囲。単位は秒
df_check_range_start Integer 検出範囲の開始時刻。Unix タイムスタンプ、単位は秒
df_check_range_end Integer 検出範囲の終了時刻。Unix タイムスタンプ、単位は秒
df_status String(Enum) モニターイベントの一般的なステータス:
致命的 fatal
重大 critical
重要 error
警告 warning
情報 info
正常 ok
データ欠損 nodata。完全な値はイベントフィールドリファレンスを参照してください。レベルの対応関係はイベントレベルを参照してください
df_event_id String イベント一意 ID
df_event_link String イベント詳細ページのリンク URL
df_dimension_tags String イベントディメンション。検出対象を識別するために使用します

例:{"host":"web-001"}
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 検出値。モニターによって検出された値

❗️互換性を保つため、検出値は強制的に String 型に変換されます
df_monitor_checker_event_ref String モニターイベントの関連付け。
モニター ID とイベント df_dimension_tags に基づいて計算されます
df_fault_id String 今回の障害 ID。値は最初の障害イベントの df_event_id です
df_fault_status String(Enum) 今回の障害ステータス。df_status の冗長フィールドです。取り得る値は次のとおりです:

  • 正常 ok
  • 障害 fault
  • df_fault_start_time Integer 今回の障害発生時刻。Unix タイムスタンプ、単位は秒
    df_fault_duration Integer 今回の障害継続時間。単位は秒
    df_user_id String 手動復旧時の操作ユーザー ID
    df_user_name String 手動復旧時の操作ユーザー名
    df_user_email String 手動復旧時の操作ユーザーメールアドレス
    df_crontab_exec_mode String(Enum) モニターの実行モード。取り得る値は次のとおりです:

  • 自動トリガー crontab
  • 手動実行 manual
  • df_site_name String 現在の Guance ノード名
    df_workspace_name String 所属ワークスペース名
    df_workspace_uuid String 所属ワークスペース ID
    df_label List モニタータグ一覧
    df_check_condition Dict 満たされた検出条件
    df_check_detail Dict 変化検出に適用され、変化を比較した元の値を表します。3 つのフィールドを含みます:

  • 表示検出値(change_value)
  • 比較値(comparison_value)
  • 変化値(detection_value)
  • df_check_condition.operator String 検出条件を満たす演算子(例:>、>= など)
    df_check_condition.operands List 検出条件を満たすオペランド一覧。
    通常はオペランドが 1 つだけですが、between などの演算子には 2 つのオペランドがあります
    df_check_condition.operands[#] Integer, Float 検出条件を満たすオペランド
    Result Integer, Float 検出された値。df_monitor_checker_value と同じく検出時に生成される値ですが、フィールド型は検出時の元の型であり、String に強制変換されません
    df_dimension_tags 内の各フィールド String df_dimension_tags 内の各フィールドが抽出されます
    df_event Dict 完全なイベントデータ
    df_studio_env_name 現在の環境名
    df_studio_console_base_url 現在の環境のコンソールアドレス
    df_studio_monitor_base_link 現在の環境のモニターアドレス

    テンプレート変数の例

    モニターの by に region と host が設定されており、イベント内容のテンプレートが次のとおりであるとします:

    イベント名:

    モニター {{ df_monitor_checker_name }} が {{ df_dimension_tags }} で障害を検出しました
    

    イベント内容:

    - リージョン:{{ region }}
    - ホスト:{{ host }}
    - レベル:{{ df_status }}
    - 検出値:{{ Result }}
    - モニター:{{ df_monitor_checker_name }}(アラートポリシー:{{ df_monitor_name }})
    

    この場合、error イベントが発生すると、レンダリング後のイベント出力は次のようになります:

    出力イベント名:

    モニター モニター001 が {"region":"hangzhou","host":"web-001"} で障害を検出しました
    

    出力イベント内容:

    - リージョン:hangzhou
    - ホスト:web-001
    - レベル:error
    - 検出値:90.12345
    - モニター:モニター001(アラートポリシー:チーム001)
    

    特殊シナリオ変数

    ユーザーアクセスメトリクスの検出

    ユーザーアクセスメトリクスの検出では、上記の汎用テンプレート変数に加えて、次のテンプレート変数を追加でサポートします:

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

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

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

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

    • {{ host-name }} の代わりに {{ df_event['host-name'] }} を使用する

    • {{ @level }} の代わりに {{ df_event['@level'] }} を使用する

    テンプレート関数

    イベント内のフィールド値を直接表示できるほか、テンプレート関数を使用してフィールド値をさらに処理し、出力を最適化できます。

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

    {{ <テンプレート変数> | <テンプレート関数> }}
    

    具体例は次のとおりです:

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

    テンプレート関数に引数を渡す必要がある場合、構文は次のとおりです:

    イベント発生時刻:{{ date | to_datetime('America/Chicago') }}
    
    Warning

    テンプレート関数を使用する前にテンプレート変数を演算する場合は、括弧を追加することを忘れないでください。例:

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

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

    テンプレート関数 引数 説明
    to_datetime タイムゾーン タイムスタンプを日付に変換します(デフォルトのタイムゾーンは Asia/Shanghai)
    例:{{ date | to_datetime }}
    出力:2022-01-01 01:23:45
    to_date_range_human df_fault_duration を読みやすい形式に変換します
    例:{{ df_fault_duration | to_date_range_human }}
    出力:X日 Y時間 Z分 W秒
    to_status_human df_status を読みやすい形式に変換します
    例:{{ df_status | to_status_human }}
    出力:緊急
    to_fixed 小数桁数 数値を固定小数桁数で出力します(デフォルトは小数点以下 0 桁)
    例:{{ Result | to_fixed(3) }}
    出力:1.230
    to_round 小数桁数 数値を四捨五入します(デフォルトは小数点以下 0 桁)
    例:{{ Result | to_round(2) }}
    出力:1.24
    to_percent 小数桁数 小数をパーセントで出力します(デフォルトは小数点以下 0 桁)
    例:{{ Result | to_percent(1) }}
    出力:12.3%
    to_pretty_tags タグを整形して出力します
    例:{{ df_dimension_tags | to_pretty_tags }}
    出力:region:hanghzou, host:web-001
    limit_lines 行数を制限します
    limit_chars / limit_text 文字数を制限します
    type_name データ型名を出力します
    例:{{ data | type_name }}
    出力:dict
    to_int 整数に変換します
    例:{{ data | to_int }}<br>出力:1`
    to_float 浮動小数点数に変換します
    例:{{ data | to_float }}
    出力:1.234
    to_str 文字列に変換します
    例:{{ data | to_str }}
    出力:1.234
    to_json_dumps JSON シリアライズ文字列に変換します
    例:{{ data | to_json_dumps }}
    出力:{"key1":"value1","key2":"value2"}
    length データの長さを取得します
    例:{{ data | length }}
    出力:10

    テンプレート関数の例

    詳細は、各テンプレート関数の例 を参照してください。

    設定したモニターの by に region と host が設定されており、アラート設定のテンプレートが次のとおりであるとします:

    イベント名:

    モニター {{ df_monitor_checker_name }} が {{ df_dimension_tags | to_pretty_tags }} で障害を検出しました
    

    イベント内容:

    - 対象:{{ df_dimension_tags | to_pretty_tags }}
    - 時刻:{{ date | to_datetime }}
    - レベル:{{ df_status | to_status_human }}
    - 検出値:{{ (Result * 100) | to_round(2) }}
    

    この場合、error イベントが発生すると、レンダリング後のイベント出力は次のようになります:

    出力イベント名:

    モニター マイモニター が region:hangzhou, host:web-001 で障害を検出しました
    

    出力イベント内容:

    - 検出対象:region:hangzhou, host:web-001
    - 検出時刻:2022-01-01 01:23:45
    - 障害レベル:重要
    - 検出値:9012.35
    

    テンプレート分岐

    テンプレートでは、条件に応じて異なる内容をレンダリングする分岐構文も使用できます。

    テンプレート分岐の例

    次の例では fatal の致命的なアラートを個別に処理し、ok の場合にのみ復旧情報を出力します。記載されていないステータスは元の値を表示し、他のイベントを誤って正常と判定しないようにします:

    {% if df_status == 'fatal' %}
    致命的な問題です。直ちに対応してください。
    {% elif df_status == 'critical' %}
    重大な問題です。直ちに対応してください。
    {% elif df_status == 'error' %}
    重要な問題です。対応してください。
    {% elif df_status == 'warning' %}
    警告イベントです。注意してください。
    {% elif df_status == 'nodata' %}
    データ欠損です。データ送信状況を確認してください。
    {% elif df_status == 'info' %}
    情報イベントです。必要に応じて確認してください。
    {% elif df_status == 'ok' %}
    正常に復旧しました。
    {% else %}
    現在のイベントステータス:{{ df_status }}。イベント詳細を確認してください。
    {% endif %}
    

    より典型的な例は次のとおりです:

    {% if  df_status != 'ok' %}
    > レベル:{{ df_status }}
    > ホスト:{{ host }}
    > 内容:Elasticsearch JVM ヒープメモリの使用量は {{ Result }}% です
    > 推奨:現在、JVM ガベージコレクションが JVM ガベージの生成に追いついていません。速やかに業務状況を確認してください。
    
    {% else %}
    > レベル:{{df_status}}
    > ホスト:{{host}}
    > 内容:Elasticsearch JVM ヒープメモリのアラートは復旧しました
    
    {% endif %}
    

    埋め込み DQL クエリ関数

    場合によっては、テンプレート変数だけではレンダリング要件を満たせません。そのような場合は、埋め込み DQL クエリ関数を使用して追加のデータクエリを実行できます。

    埋め込み DQL クエリ関数は、現在のワークスペースで今回の検出時間範囲内に任意の DQL ステートメントを実行できます。通常、クエリで取得した最初のデータはテンプレート内でテンプレート変数として使用できます。使用方法は次のとおりです:

    {% set dql_data = DQL("実行する DQL ステートメント") %}
    
    あるフィールド:{{ dql_data.some_field }}
    

    埋め込み DQL クエリの例

    次の埋め込み DQL ステートメントは、host フィールドが "my_server" のデータをクエリし、最初のデータを dql_data 変数に代入します:

    {% set dql_data = DQL("O::HOST:(host, host_ip, os, datakit_ver) { host = 'my_server' }") %}
    
    ホスト OS:{{ dql_data.os }}
    

    以降のテンプレートでは、{{ dql_data.os }} を使用してクエリ結果の具体的なフィールドを出力できます。

    埋め込み DQL にパラメータを渡す

    場合によっては、DQL ステートメントの実行時にパラメータを渡す必要があります。これらのパラメータは DQL ステートメントに直接埋め込むことができ、by フィルターを追加するかどうかを選択できます。ただし、記述方法が少し異なります。通常、変数を参照するときは {{df_status}} を使用します。しかし DQL ステートメントでは、{{ }} を付けずに変数名を直接使用するため、最終的な記述は status になります。

    モニターの by に region と host が設定されており、イベント内容のテンプレートが次のとおりであるとします:

    {% set dql_data = DQL("O::HOST:(host_ip, os) { region = ?, host = ? }", region, host) %}
    
    ホスト情報:
    IP:{{ dql_data.host_ip }}
    OS: {{ dql_data.os }}
    

    イベントには異なるデータを識別するための region と host テンプレート変数のみが含まれ、IP アドレスや OS などの詳細情報は含まれません。

    その場合、埋め込み DQL で region と host を DQL クエリのパラメータとして使用して対応するデータを取得し、{{ dql_data.host_ip }} などで関連情報を出力できます。

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

    埋め込み DQL クエリ関数の呼び出し形式は次のとおりです:

    DQL(dql, param_1, param_2, ...)
    
    • 第 1 引数は DQL ステートメントで、パラメータプレースホルダー ? を含めることができます
    • 後続の引数は DQL ステートメントのパラメータ値または変数です

    パラメータプレースホルダー ? を具体的な値に置き換える際、システムは自動的にエスケープします。

    変数 host の値が "my_server" であるとすると、埋め込み DQL 関数と実行される最終的な DQL ステートメントは次のとおりです:

    DQL("O::HOST:(host, host_ip, os, datakit_ver) { host = ? }",  host)
    
    O::HOST:(host, host_ip, os, datakit_ver) { host = 'my_server' }
    
    Warning
    • 埋め込み DQL クエリはテンプレートの先頭に配置してください
    • クエリ結果名(ここでは dql_data)は一般的なプログラミング言語の命名要件に従い、任意の英字で始まり、英字、数字、アンダースコアのみを含む文字列にできます。emoji の使用は推奨しません。
    • クエリ結果名は既存のテンプレート変数やテンプレート関数と名前が重複しないようにしてください。重複すると予期しない問題が発生します
    • DQL でフィールドに関数を使用する場合は、後で使いやすいように AS を使用してフィールドに別名を付けることを推奨します(例:O::HOST:( last(host) AS last_host ))。
    • DQL のフィールド名に特殊文字が含まれる場合、テンプレート変数と同様に、{{ dql_data['host-name'] }}、{{ dql_data['@level'] }} を使用してレンダリングしてください。

    その他の DQL ドキュメント

    フィードバック

    このページは役に立ちましたか?