Documentation
2 アイテムの値の保存前処理
概要
保存前処理を行うことで、受け取った項目の値の変換ルールを定義することができます。
データベースに保存する前に、1つまたは複数の変換を行うことができます。
変換は定義された順番に実行されます。
保存前処理はZabbixサーバまたはプロキシ(プロキシでアイテムを監視している場合)で実行されます。
保存前処理に渡される値はすべて文字列型であり、(アイテムの設定で定義された)目的の値の型への変換は、
保存前処理パイプラインの最後に実行されることに注意してください。
ただし、変換は対応する保存前処理工程で必要とされる場合に行われることもあります。
詳細は保存前処理の詳細をご参照ください。
使用例も併せてご参照ください。
設定
保存前処理のルールは、アイテム設定の保存前処理タブで定義します。
保存前処理のいずれかに失敗すると、アイテムは取得不可 となります。 ただし、サポートされている変換の 失敗時のカスタマイズ オプションを使用して、カスタムのエラー処理を指定した場合はこの限りではありません。
ログアイテムの場合、ログメタデータ（値なし）は常にアイテムの取得不可状態をリセットし、再びサポートされるようにします。
ユーザーマクロおよびユーザーマクロのコンテキストは、アイテム保存前処理のパラメータやJavaScriptのコード内でサポートされています。
マクロをその値で置き換える場合、コンテキストは無視されます。 マクロの値はそのままコードに挿入されるため、JavaScriptのコードに値を配置する前に追加のエスケープを行うことはできません。 このため、場合によってはJavaScriptエラーが発生する可能性があります。
| タイプ | ||
|---|---|---|
| 変換 | 説明 | |
| テキスト | ||
| 正規表現 | 値を<パターン>正規表現と照合し、値を<出力>に置き換えます。正規表現は、\N シーケンスを使用して最大 10 個のキャプチャされたグループの抽出をサポートします。入力値と一致しない場合、アイテムはサポートされません。 パラメーター: パターン - 正規表現 出力 - 出力フォーマットテンプレート。\N (N=1…9) エスケープシーケンスはN番目に一致したグループに置き換えられます。\0 エスケープシーケンスは、一致したテキストに置き換えられます。 既存の例については、正規表現のセクションを参照してください。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 置換 | 検索文字列を検索し、別の文字列(または何もない文字列)に置き換えます。検索文字列のすべての出現箇所が置き換えられます。 パラメータ: 検索文字列 - 検索して置換する文字列。大文字と小文字が区別されます(必須) 置換文字列 - 検索文字列を置換する文字列。置換文字列は空にすることもでき、検索文字列が見つかったときに削除することができます。 エスケープ シーケンスを使用して、改行、復帰、タブ、およびスペースを"\n \r \t \s"で検索または置換することができます。バックスラッシュは"\\"としてエスケープでき、エスケープ シーケンスは"\\n"としてエスケープできます。改行、復帰、タブのエスケープは、ローレベルディスカバリ中に自動的に行われます。 |
|
| 前後文字列削除 | 値の先頭と末尾から指定された文字を削除します。 | |
| 末尾文字列削除 trim | 値の末尾から指定された文字を削除します。 | |
| 先頭文字列削除 | 値の先頭から指定された文字を削除します。 | |
| 構造化データ | ||
| XML XPath | XPath 機能を使用して、XML データから値またはフラグメントを抽出します。 このオプションが機能するには、Zabbix サーバーが libxml サポート付きでコンパイルされている必要があります。 例: number(/document/item/value)は<document><item><value>10</value></item></document>から10を抽出します。number(/document/item/@attribute)は、<document><item attribute="10"></item></document>から10を抽出します。/document/itemは、<document><item><value>10</value></item>から<item><value>10</value></item></document> を抽出します。名前空間はサポートされていないことに注意してください。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| JSON Path | JSONPath 機能を使用して、JSONデータから値またはフラグメントを抽出します。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| CSVからJSON | CSVファイルのデータをJSON形式に変換します。 詳細については、CSV から JSON への前処理 を参照してください。 |
|
| XMLからJSON | XML形式のデータをJSONに変換します。 詳細についてはシリアライズ規則を参照してください。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 計算 | ||
| 乗数 | 指定された整数または浮動小数点値で値を乗算します。 KB、MBps などで受信した値を B、Bpsに変換するには、このオプションを使用します。そうしないと、Zabbixはプレフィックス(K、M、G など)を正しく設定できません。 注意 情報の項目タイプが 数値(整数)の場合、小数部分のある受信値は、カスタム乗数が適用される前に切り捨てられます(つまり、'0.9'は'0'になります)。 サポート対象: 科学的記数法、たとえば 1e+70(バージョン 2.2 以降)、ユーザーマクロおよびLLDマクロ(バージョン 4.0 以降)。 マクロを含む文字列、たとえば {#MACRO}e+10、{$MACRO1}e+{$MACRO2}(バージョン 5.2.3 以降)マクロは整数または浮動小数点数に解決される必要があります。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 変化 | ||
| 差分 | 現在の値と前回の値の差を計算します。 値-前の値として評価されます。ここで、 値 - 現在の値、前の値 - 前回受信した値 この設定は、継続的に増加する値を測定する場合に便利です。現在の値が前回の値よりも小さい場合、Zabbixはその差を破棄し(何も保存しない)、別の値を待機します。 アイテムごとに 1 つの変更操作のみが許可されます。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 1秒あたりの差分 | 1秒あたりの値の変化速度(現在の値と前の値の差)を計算します。 (値-前の値)/(時間-前の時間)として評価されます。ここで、 値 - 現在の値、前の値 - 前回受信した値、時間 - 現在のタイムスタンプ、前の時間 - 前回の値のタイムスタンプ。 この設定は、常に増加する値の1秒あたりの速度を計算する場合に便利です。現在の値が前回の値よりも小さい場合、Zabbixはその差を破棄し(何も保存せず)、別の値を待機します。これは、たとえば32ビットSNMPカウンターのラップ(オーバーフロー)を正しく処理するのに役立ちます。 注: この計算では浮動小数点数が生成される可能性があるため、受信した生の値が整数であっても、'データ型'を数値(浮動小数点)に設定することをお勧めします。これは、小数部分が重要な小さい数値に特に関係します。浮動小数点値が大きく、'float'フィールドの長さを超える可能性がある場合、値全体が失われる可能性があるため、実際には数値(整数)を使用して小数部分のみを切り取ることをお勧めします。 アイテムごとに1つの変更操作のみが許可されます。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 数値変換 | ||
| 論理値から10進数 | 値をブール形式から10進数に変換します。テキスト表現は0または1に変換されます。したがって、「TRUE」は1として保存され、「FALSE」は0として保存されます。すべての値は、大文字と小文字を区別せずに一致します。現在認識される値は次のとおりです。 TRUE - true、t、yes、y、on、up、running、enabled、available、ok、master FALSE - false、f、no、n、off、down、unused、disabled、unavailable、err、slave さらに、ゼロ以外の数値はすべてTRUEと見なされ、ゼロはFALSEと見なされます。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 8進数から10進数 | 値を8進形式から10進形式に変換します。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 16進数から10進数 | 値を16進形式から10進形式に変換します。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| カスタムスクリプト | ||
| JavaScript | パラメータ フィールドまたは鉛筆アイコンをクリックすると表示されるブロックに JavaScript コードを入力します。 使用可能な JavaScript の長さは、使用されているデータベースによって異なることに注意してください。 詳細については、Javascript の前処理 を参照してください。 |
|
| バリデーション | ||
| 値の範囲 | Define a range that a value should be in by specifying minimum/maximum values (inclusive). Numeric values are accepted (including any number of digits, optional decimal part and optional exponential part, negative values). User macros and low-level discovery macros can be used. The minimum value should be less than the maximum. At least one value must exist. If you mark the Custom on fail checkbox, it is possible to select custom error-handling options: either to discard the value, set a specified value, or set a specified error message. In case of a failed preprocessing step, the item will not become unsupported if the option to discard the value or set a specified value is selected. |
|
| 正規表現と一致する | 値が一致する必要がある正規表現を指定します。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 正規表現と一致しない | 値と一致させない正規表現を指定します。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| JSON内のエラーチェック | JSONPathにあるアプリケーションレベルのエラーメッセージを確認します。成功しメッセージが空でない場合は処理を停止します。それ以外の場合は、この保存前処理手順の前の値を使用して処理を続行します。これらの外部サービスエラーは、保存前処理手順の情報を追加せずに、そのままユーザーに報告されることに注意してください。 無効な JSON の解析に失敗した場合は、エラーは報告されません。失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| XML内のエラーチェック | XPathにあるアプリケーションレベルのエラー メッセージを確認します。成功しメッセージが空でない場合は処理を停止します。それ以外の場合は、この保存前処理手順の前の値を使用して処理を続行します。これらの外部サービス エラーは、保存前処理手順の情報を追加せずに、そのままユーザーに報告されることに注意してください。 無効な XML の解析に失敗した場合は、エラーは報告されません。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| 正規表現使用時のエラーチェック | 正規表現を使用して、アプリケーションレベルのエラーメッセージを確認します。成功しメッセージが空でない場合は処理を停止します。それ以外の場合は、この保存前処理手順の前の値を使用して処理を続行します。これらの外部サービス エラーは、保存前処理手順の情報を追加せずに、そのままユーザーに報告されることに注意してください。 無効な XML の解析に失敗した場合は、エラーは報告されません。 失敗時のカスタマイズチェックボックスをオンにすると、カスタムエラー処理オプションを選択できます:値を破棄するか、指定された値を設定するか、指定されたエラーメッセージを設定するかのいずれか。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムは取得不可になりません。 |
|
| サポートしていない値のチェック | アイテム値の取得中にエラーがあったかどうかを確認します。通常、アイテムは取得不可になりますが、失敗時のカスタマイズエラー処理オプションを指定して、値を破棄するか、指定された値を設定するか(トリガーでも使用可能)、指定されたエラー メッセージを設定することで、その動作を変更できます。保存前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていれば、アイテムはサポートされなくなります。この保存前処理ステップでは、失敗時のカスタマイズチェックボックスがグレー表示され、常にマークされていることに注意してください。 このステップは常に最初の保存前処理ステップとして実行され、アイテムへの変更を保存した後、他のすべてのステップよりも上に配置されます。使用できるのは1回だけです。 5.2.0 以降でサポートされています。 |
|
| 絞り込み | ||
| 変化がなければ破棄 | 変更されていない場合は値を破棄します。 値が破棄されると、その値はデータベースに保存されず、Zabbixサーバーはこの値が受信されたことを認識しません。トリガー式は評価されず、結果として関連するトリガーの問題は作成/解決されません。関数はデータベースに実際に保存されているデータに基づいてのみ動作します。トレンドはデータベースのデータに基づいて構築されるため、1時間にわたって値が保存されていない場合、その時間のトレンド データも存在しません。 アイテムに対して指定できるスロットルオプションは1つだけです。 Zabbixサーバのデータベースをアップグレードしていない状況で、Zabbixプロキシで監視しているアイテムの値の差が(0.000001未満と)非常に小さい場合、プロキシで取得された監視データが、Zabbixサーバの保存前処理で同じ値として破棄される可能性があることに注意してください。 |
|
| 指定秒内に変化がなければ破棄 | 定義された期間(秒単位)内に値が変更されていない場合は、その値を破棄します。 秒数を指定するために正の整数値がサポートされています(最小 - 1 秒)。このフィールドでは、時間接尾辞を使用できます (例: 30s、1m、2h、1d)。このフィールドでは、ユーザーマクロとローレベルディスカバリマクロを使用できます。 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはこの値が受信されたことを認識しません。トリガー式は評価されないため、関連するトリガーの問題は作成/解決されません。関数は、実際にデータベースに保存されているデータに基づいてのみ機能します。トレンドはデータベースのデータに基づいて構築されるため、1時間にわたって値が保存されていない場合は、その時間のトレンドデータも存在しません。 アイテムに対して指定できるスロットリング オプションは1つだけです。 Zabbixサーバのデータベースをアップグレードしていない状況で、Zabbixプロキシで監視しているアイテムの値の差が(0.000001未満と)非常に小さい場合、プロキシで取得された監視データが、Zabbixサーバの保存前処理で同じ値として破棄される可能性があることに注意してください。 |
|
| Prometheus | ||
| Prometheusパターン | Prometheusメトリックから必要なデータを抽出するには、次のクエリを使用します。 詳細については、Prometheusを参照してください。 |
|
| PrometheusからJSON | 必要な Prometheus メトリックを JSON に変換します。 詳細については、Prometheusを参照してください。 |
|
変化および絞り込みの保存前処理手順 Zabbix は、必要に応じて新しい値を計算/比較するために、最後の値を記憶する必要があります。これらの以前の値は、プリプロセッシングマネージャーによって処理されます。Zabbixサーバーまたはプロキシが再起動されるか、保存前処理手順に変更が加えられると、対応する項目の最後の値がリセットされ、次のようになります。
- 差分, 1秒あたりの差分の手順 - 計算される変更前の値がないため、次の値は無視されます。
- 変化がなければ破棄. 指定秒内に変化がなければ破棄の手順 - 破棄ルールにより破棄されるはずであったとしても、次の値は破棄されることはありません。
少なくとも1つの前処理ステップが定義されている場合、アイテムのデータ型パラメータはタブの下部に表示されます。必要に応じて、保存前処理タブを離れずに情報の種類を変更することができます。詳細なパラメータの説明については、アイテムの作成を参照してください。
データ型が数値(整数)に設定されている項目に対して乗数を使用したり、値を1秒あたりの差分として保存したりして、計算結果の値が実際には浮動小数点数である場合でも、小数点部分を切り捨てて値を整数として保存することで、計算値は正しい値として受け入れられます。
保存前処理のテスト
保存前処理ステップのテストは、アイテムの値の受信と保存前処理を待たずに、複雑なプリプロセスパイプラインが期待される結果をもたらすことを確認するのに有効です。
- 仮想的な値に対してテストすることが可能です。
- ホストからの実際の値に対してテストすることが可能です。
保存前処理の各ステップを個別にテストすることも、すべてのステップを一緒にテストすることも可能です。アクションブロックの テスト または すべてのテスト ボタンをクリックすると、テストウィンドウが表示されます。
仮想的な値のテスト
| パラメータ | 説明 |
|---|---|
| ホストから値を取得 | 仮想値をテストする場合は、このチェックボックスをオフのままにします。 参照: 実際の値のテスト。 |
| 値 | テストする入力値を入力します。 パラメータ フィールドまたは表示/編集ボタンをクリックすると、値またはコード ブロックを入力するためのテキスト領域ウィンドウが開きます。 |
| 取得不可 | 取得不可になる値をテストするには、このチェックボックスをオンにします。 このオプションは、取得不可になる値で保存前処理のテストするのに役立ちます。 |
| 時間 | 入力値の時刻が表示されます: now (読み取り専用)。 |
| 前の値 | 比較する前の入力値を入力します。 変化および絞り込みの保存前処理手順のみ。 |
| 前の時間 | 比較する前の入力値の時間を入力します。 変化および絞り込み保存前処理手順の場合のみ。 デフォルト値は、アイテムの「更新間隔」フィールドの値に基づきます (「1m」の場合、このフィールドには「now-1m」が入力されます)。何も指定されていない場合、またはユーザーがホストにアクセスできない場合、デフォルトは「now-30s」です。 |
| マクロ | マクロが使用されている場合は、その値とともにリストされます。値はテスト目的で編集可能ですが、変更はテスト コンテキスト内でのみ保存されます。 |
| 改行コード | 複数行の入力値の行末シーケンスを選択します: LF - LF (改行) シーケンス CRLF - CRLF (復帰改行) シーケンス。 |
| 保存前処理の設定 | 保存前処理の手順が一覧表示され、テストボタンをクリックすると、各手順のテスト結果が表示されます。 手順がテストに失敗した場合は、エラーアイコンが表示されます。マウスを移動すると、エラーの説明が表示されます。 手順に「失敗時のカスタマイズ」が指定され、そのアクションが実行された場合は、前処理のテスト手順の行の直後に新しい行が表示され、実行されたアクションと生成された結果 (エラーまたは値) が表示されます。 |
| 結果 | すべてのステップが一緒にテストされた場合 (すべてのテストボタンをクリックした場合)、前処理ステップのテストの最終結果が常に表示されます。 項目の値の型への変換の種類も表示されます(例: 結果は数値(整数)に変換されました) |
各保存前処理後の結果を見るには、テストをクリックしてください。
テストセッションの間に、個々のステップまたは全ステップについてテスト値を保存することが出来るので、保存前処理やアイテムの設定を変更しても、情報を再入力することなくテストウィンドウに戻ることができます。ただし、ページの更新時に値は失われます。
テストはZabbixサーバーで行われます。フロントエンドは対応するリクエストをサーバに送信し結果を待ちます。リクエストには入力値と保存前処理のステップ(拡張ユーザマクロを含む)が含まれます。変化および絞り込みのステップでは、オプションで前値と時間を指定することができます。サーバーは、各保存前処理ステップの結果を応答します。
すべての技術的エラーまたは入力検証エラーは、テストウィンドウ上部のエラーボックスに表示されます。
実測値のテスト
保存前処理を実測値に対してテストするため、
- ホストから値を取得 チェックボックスをマークします。
- ホストパラメータ（ホストアドレス、ポート、プロキシ名 / プロキシなし）および項目固有の詳細
（SNMPv2コミュニティやSNMPv3セキュリティ認証など）を入力または確認します。これらのフィールドは、コンテキストを認識します。
- エージェントを必要とする項目については、ホストの選択されたエージェントインターフェースから情報を取得することで、
可能な限り値は事前に入力されます。 - テンプレートアイテムの場合は、値を手動で入力する必要があります。
- プレーンテキストのマクロ値は解決されます。
- 値(または値の一部)がシークレットまたはVaultマクロであるフィールドは空であるため、手動で入力しなければなりません。
アイテムのパラメータにシークレットマクロ値が含まれている場合、次のような警告メッセージが表示されます。
"アイテムは秘密な値を持つユーザー定義マクロを含んでいます。これらのマクロの値は手動で入力する必要があります。" - アイテムタイプのコンテキストで必要ない場合、フィールドは無効化されます。
フィールドは、アイテムの種類によって必要ない場合は無効になります
(たとえば、ホストアドレスとプロキシフィールドは、計算されたアイテムでは無効になります)。
- エージェントを必要とする項目については、ホストの選択されたエージェントインターフェースから情報を取得することで、
- 保存前処理をテストするには、値の取得とテスト をクリックします。
アイテム設定画面で値のマッピングを指定している場合('値のマッピング' フィールド)、アイテムテストダイアログは最終結果の後にもう1行表示します。'値のマッピングを適用した結果'という名前の別の行が表示されます。
ホストから実測値を取得する際に特有のパラメータ:
| パラメータ | 説明 |
|---|---|
| ホストから値を取得 | Mark this checkbox to get a real value from the host. |
| ホストのアドレス | Enter the host address. This field is automatically filled by the address of the item host interface. |
| ポート | Enter the host port. This field is automatically filled by the port of item host interface. |
| SNMPインターフェースの追加フィールド (SNMPバージョン, SNMPコミュニティ、コンテキスト名、etc) |
SNMP インターフェイス (v1、v2、v3) の設定の詳細については、SNMP 監視の設定 を参照してください。 これらのフィールドは、アイテム・ホスト・インターフェイスから自動的に入力されます。 |
| プロキシ | ホストがプロキシによって監視されている場合は、プロキシを指定します。 このフィールドは、ホストのプロキシ (存在する場合) によって自動的に入力されます。 |
残りのパラメータについては、上記の仮説値のテストを参照してください。