カスタムイベント通知テンプレート¶
テンプレート構文を使用して、イベント通知内容をカスタマイズできます:
-
動的レンダリング:
{{ フィールド名 }}を使用してアラートフィールドを直接挿入します(例:{{ 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 の冗長フィールドです。取り得る値は次のとおりです:okfault |
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) | モニターの実行モード。取り得る値は次のとおりです:crontabmanual |
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 が設定されており、イベント内容のテンプレートが次のとおりであるとします:
イベント名:
イベント内容:
- リージョン:{{ region }}
- ホスト:{{ host }}
- レベル:{{ df_status }}
- 検出値:{{ Result }}
- モニター:{{ df_monitor_checker_name }}(アラートポリシー:{{ df_monitor_name }})
この場合、error イベントが発生すると、レンダリング後のイベント出力は次のようになります:
出力イベント名:
出力イベント内容:
特殊シナリオ変数¶
ユーザーアクセスメトリクスの検出¶
ユーザーアクセスメトリクスの検出では、上記の汎用テンプレート変数に加えて、次のテンプレート変数を追加でサポートします:
| テンプレート変数 | 型 | 説明 |
|---|---|---|
app_id |
String | アプリケーション ID |
app_name |
String | アプリケーション名 |
app_type |
String | アプリケーションタイプ |
特殊文字を含むフィールドの処理¶
検出設定の ディメンション フィールドに特殊文字(-、@ など)が含まれる場合、例えば host-name、@level などは、通常の変数名として直接使用できず、テンプレートのレンダリングに失敗します。
解決策として、次の形式で参照します:
-
{{ host-name }}の代わりに{{ df_event['host-name'] }}を使用する -
{{ @level }}の代わりに{{ df_event['@level'] }}を使用する
テンプレート関数¶
イベント内のフィールド値を直接表示できるほか、テンプレート関数を使用してフィールド値をさらに処理し、出力を最適化できます。
基本構文は次のとおりです:
具体例は次のとおりです:
テンプレート関数に引数を渡す必要がある場合、構文は次のとおりです:
Warning
テンプレート関数を使用する前にテンプレート変数を演算する場合は、括弧を追加することを忘れないでください。例:
使用可能なテンプレート関数の一覧は次のとおりです:
| テンプレート関数 | 引数 | 説明 |
|---|---|---|
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_dimension_tags | to_pretty_tags }}
- 時刻:{{ date | to_datetime }}
- レベル:{{ df_status | to_status_human }}
- 検出値:{{ (Result * 100) | to_round(2) }}
この場合、error イベントが発生すると、レンダリング後のイベント出力は次のようになります:
出力イベント名:
出力イベント内容:
テンプレート分岐¶
テンプレートでは、条件に応じて異なる内容をレンダリングする分岐構文も使用できます。
テンプレート分岐の例¶
次の例では 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 ステートメントを実行できます。通常、クエリで取得した最初のデータはテンプレート内でテンプレート変数として使用できます。使用方法は次のとおりです:
埋め込み 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 クエリ関数の呼び出し形式は次のとおりです:
- 第 1 引数は DQL ステートメントで、パラメータプレースホルダー
?を含めることができます - 後続の引数は DQL ステートメントのパラメータ値または変数です
パラメータプレースホルダー ? を具体的な値に置き換える際、システムは自動的にエスケープします。
変数 host の値が "my_server" であるとすると、埋め込み DQL 関数と実行される最終的な DQL ステートメントは次のとおりです:
Warning
- 埋め込み DQL クエリはテンプレートの先頭に配置してください
- クエリ結果名(ここでは
dql_data)は一般的なプログラミング言語の命名要件に従い、任意の英字で始まり、英字、数字、アンダースコアのみを含む文字列にできます。emoji の使用は推奨しません。 - クエリ結果名は既存のテンプレート変数やテンプレート関数と名前が重複しないようにしてください。重複すると予期しない問題が発生します
- DQL でフィールドに関数を使用する場合は、後で使いやすいように
ASを使用してフィールドに別名を付けることを推奨します(例:O::HOST:( last(host) AS last_host ))。 - DQL のフィールド名に特殊文字が含まれる場合、テンプレート変数と同様に、
{{ dql_data['host-name'] }}、{{ dql_data['@level'] }}を使用してレンダリングしてください。