2 アイテムの値の保存前処理

概要

保存前処理を行うことで、受け取った項目の値の変換ルールを定義することができます。
データベースに保存する前に、1つまたは複数の変換を行うことができます。

変換は定義された順番に実行されます。
保存前処理はZabbixサーバまたはプロキシ(プロキシでアイテムを監視している場合)で実行されます。

保存前処理に渡される値はすべて文字列型であり、(アイテムの設定で定義された)目的の値の型への変換は、
保存前処理パイプラインの最後に実行されることに注意してください。
ただし、変換は対応する保存前処理工程で必要とされる場合に行われることもあります。
詳細は保存前処理の詳細をご参照ください。

使用例も併せてご参照ください。

設定

保存前処理のルールは、アイテム設定の保存前処理タブで定義します。

ユーザーマクロおよびユーザーマクロのコンテキストは、アイテム保存前処理のパラメータやJavaScriptのコード内でサポートされています。

アイテムのデータ型パラメータは、少なくとも1つの保存前処理工程が定義されている場合、タブの下部に表示されます。
必要であれば、保存前処理タブを開いたまま情報の種類を変更することができます。
アイテムの作成 を参照してください。

Supported transformations

All supported transformations are listed below. Click on the transformation name to see full details about it.

Note that for Change and Throttling preprocessing steps, Zabbix has to remember the last value to calculate/compare the new value as required. These previous values are handled by the preprocessing manager. If Zabbix server or proxy is restarted or there is any change made to preprocessing steps, the last value of the corresponding item is reset, resulting in:

• for Simple change, Change per second steps - the next value will be ignored because there is no previous value to calculate the change from;
• for Discard unchanged, Discard unchanged with heartbeat steps - the next value will never be discarded, even if it should have been because of discarding rules.

Regular expression

Match the value to the regular expression and replace with the required output.

Parameters:

• pattern - the regular expression;
  
• output - the output formatting template. An \N (where N=1…9) escape sequence is replaced with the Nth matched group. A \0 escape sequence is replaced with the matched text.

Comments:

• A failure to match the input value will make the item unsupported;
  
• The regular expression supports extraction of maximum 10 captured groups with the \N sequence;
  
• 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.
  
• Please refer to regular expressions section for some existing examples.

Replace

検索文字列を検索し、別の文字列（または何もない文字列）に置換します。

パラメータ:

• 検索文字列 - 検索および置換する文字列。大文字と小文字が区別されます（必須）
  
• 置換文字列 - 検索文字列を置換する文字列。置換文字列は空でも構いません。空の場合は、検索文字列が見つかった時点で削除できます。

コメント:

• 検索文字列のすべての出現箇所が置換されます。
• エスケープシーケンスを使用して、改行、復帰、タブ、スペースを検索または置換できます（"\n \r \t \s"）。バックスラッシュは "\\" のようにエスケープでき、エスケープシーケンスは "\\n" のようにエスケープできます。
• 改行、復帰、タブのエスケープは、低レベル検出時に自動的に行われます。

トリム

値の先頭と末尾から指定した文字列を削除

右トリム

値の末尾から指定した文字列を削除

左トリム

値の先頭から指定した文字列を削除

XML XPath

XPath機能を使用してXMLデータから値またはフラグメントを抽出します。

コメント:

• このオプションが機能するには、Zabbixサーバー（または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>' を抽出します。

JSON パス

JSONPath 機能 を使用して、JSON データから値またはフラグメントを抽出します。

失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。カスタムエラー処理オプションには、値を破棄する、指定値を設定する、または指定エラーメッセージを設定する、のいずれかがあります。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

CSV から JSON へ変換

CSV ファイルのデータを JSON 形式に変換します。

詳細については、CSV から JSON への前処理 を参照してください。

XML から JSON へ変換

XML 形式のデータを JSON に変換します。

詳細については、シリアル化ルール を参照してください。

失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値は破棄されるか、指定された値が設定され、指定されたエラーメッセージが表示されるかを選択できます。前処理ステップが失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

SNMP walk value

Extract value by the specified OID/MIB name and apply formatting options:

• Unchanged - return hex-string as unescaped hex string;
  
• UTF-8 from hex-STRING - convert hex-string to UTF-8 string;
  
• MAC from hex-STRING - validate hex-string as MAC address and return a proper MAC address string (where ' ' are replaced by ':');
  
• Integer from BITS - convert the first 8 bytes of a bit string expressed as a sequence of hex characters (e.g., "1A 2B 3C 4D") into a 64-bit unsigned integer. In bit strings longer than 8 bytes, consequent bytes will be ignored.

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.

SNMP walk to JSON

SNMP値をJSONに変換します。

JSON内のフィールド名と対応するSNMP OIDパスを指定します。フィールド値には、指定されたSNMP OIDパスの値が入力されます。

コメント:

• SNMP walk value ステップと同様の値のフォーマットオプションが利用可能です。
  
• この前処理ステップは、SNMP OID検出にも使用できます。
  
• Custom on fail チェックボックスをオンにすると、カスタムエラー処理オプション（値を破棄する、指定値を設定する、または指定エラーメッセージを設定する）を指定できます。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていると、その項目はサポート対象外になりません。

SNMP get 値

SNMP get 値にフォーマットオプションを適用します。

• UTF-8 from Hex-STRING - 16進文字列をUTF-8文字列に変換します。
  
• MAC from Hex-STRING - 16進文字列がMACアドレスであることを検証し、正しいMACアドレス文字列を返します（' 'は':'に置き換えられます）。
  
• Integer from BITS - 16進文字のシーケンス（例："1A 2B 3C 4D"）で表されるビット文字列の最初の8バイトを64ビットの符号なし整数に変換します。8バイトを超えるビット文字列の場合、後続のバイトは無視されます。

失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定することができます。前処理手順が失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていると、項目はサポートされなくなります。

Custom multiplier

Multiply the value by the specified integer or floating-point value.

Comments:

• Use this option to convert values received in KB, MBps, etc., into B, Bps. Otherwise, Zabbix cannot correctly set prefixes (K, M, G, etc.).
  
• Note that if the item type of information is Numeric (unsigned), incoming values with a fractional part will be trimmed (i.e., '0.9' will become '0') before the custom multiplier is applied;
  
• If you use a custom multiplier or store value as Change per second for items with the type of information set to Numeric (unsigned) and the resulting calculated value is actually a float number, the calculated value is still accepted as a correct one by trimming the decimal part and storing the value as an integer;
  
• Supported: scientific notation, for example, 1e+70; user macros and LLD macros; strings that include macros, for example, {#MACRO}e+10, {$MACRO1}e+{$MACRO2}. The macros must resolve to an integer or a floating-point number.
• 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.

単純な変更

現在の値と前回の値の差を計算します。

コメント:

• このステップは、常に増加する値を測定する場合に便利です。
  
• value-prev_value として評価されます。ここで、value は現在の値、prev_value は前回受信した値です。
  
• アイテムごとに変更操作（"単純な変更"または"1秒あたりの変更"）は1回のみ許可されます。
• 現在の値が前回の値より小さい場合、Zabbixはその差を破棄（何も保存せず）し、次の値を待機します。
  
• 失敗時のカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、特定の値を設定する、または特定のエラーメッセージを設定するオプションです。前処理ステップが失敗した場合、値を破棄するか特定の値を設定するオプションが選択されていれば、アイテムはサポート対象外になりません。

Change per second

Calculate the value change (difference between the current and previous value) speed per second.

Comments:

• This step is extremely useful to get the speed per second of a constantly growing value;
  
• As this calculation may produce floating-point numbers, it is recommended to set the 'Type of information' to Numeric (float), even if the incoming raw values are integers. This is especially relevant for small numbers where the decimal part matters. If the floating-point values are large and may exceed the 'float' field length in which case the entire value may be lost, it is actually suggested to use Numeric (unsigned) and thus trim only the decimal part.
  
• Evaluated as (value-prev_value)/(time-prev_time), where value - the current value; prev_value - the previously received value; time - the current timestamp; prev_time - the timestamp of the previous value;
  
• Only one change operation per item ("Simple change" or "Change per second") is allowed;
• If the current value is smaller than the previous value, Zabbix discards that difference (stores nothing) and waits for another value. This helps to work correctly with, for instance, a wrapping (overflow) of 32-bit SNMP counters.
  
• 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.

ブール値を小数点に変換

値をブール値形式から小数点形式に変換します。

コメント:

• テキスト表現は 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、available、err、slave です。さらに、0 以外の数値はすべて TRUE とみなされ、0 は FALSE とみなされます。
  
• 失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定することができます。前処理手順が失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていると、項目はサポート対象外になりません。

8進数から10進数へ

値を8進数形式から10進数形式に変換します。

失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定値を設定する、または指定エラーメッセージを設定する、のいずれかを選択できます。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

16進数から10進数へ

値を16進数形式から10進数形式に変換します。

失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定値を設定する、または指定エラーメッセージを設定するのいずれかを選択できます。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

JavaScript

パラメータフィールドまたはその横にある鉛筆アイコンをクリックすると開くモーダルエディタに、JavaScript コードを入力します。

コメント:

• 使用可能な JavaScript の長さは、使用するデータベース; によって異なります。
  
• 詳細については、Javascript の前処理 を参照してください。

範囲内

最小値/最大値（両端を含む）を指定して、値の範囲を定義します。

コメント:

• 数値（任意の桁数、小数部と指数部（オプション）、負の値を含む）が使用できます。
  
• 最小値は最大値より小さくする必要があります。
  
• 少なくとも1つの値が存在する必要があります。
  
• ユーザーマクロと低レベル検出マクロを使用できます。
  
• 失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定値を設定する、または指定エラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

正規表現に一致

値が一致する必要がある正規表現を指定します。

失敗時にカスタムチェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定値を設定する、または指定エラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

正規表現に一致しません

値が一致してはならない正規表現を指定します。

失敗時にカスタムチェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定値を設定する、または指定エラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

JSON のエラーをチェック

JSONPath にあるアプリケーションレベルのエラーメッセージをチェックします。成功し、メッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップ前の値を使用して処理を続行します。

コメント:

• これらの外部サービスエラーは、前処理ステップの情報を追加せずに、そのままユーザーに報告されます。
  
• 無効な JSON の解析に失敗した場合、エラーは報告されません。
  
• 失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定した値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

XML のエラーをチェック

XPath にあるアプリケーションレベルのエラーメッセージをチェックします。成功し、メッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップ前の値を使用して処理を続行します。

コメント:

• これらの外部サービスエラーは、前処理ステップの情報を追加せずに、そのままユーザーに報告されます。
  
• 無効な XML の解析に失敗した場合、エラーは報告されません。
  
• 失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定した値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

正規表現を使用してエラーをチェック

正規表現を使用して、アプリケーションレベルのエラーメッセージをチェックします。成功し、メッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップ前の値を使用して処理を続行します。

パラメーター:

• pattern - 正規表現
  
• output - 出力フォーマットテンプレート。\N (N=1…9) エスケープシーケンスは、N番目に一致したグループに置き換えられます。\0 エスケープシーケンスは、一致したテキストに置き換えられます。

コメント:

• これらの外部サービスエラーは、前処理ステップの情報を追加せずに、そのままユーザーに報告されます。
  
• 失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定することができます。前処理手順が失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていると、項目はサポートされなくなります。

Check for not supported value

Check if there was an error in retrieving item value.

Comments:

• Normally that would lead to the item becoming unsupported, but you may modify that behavior by specifying the Custom on fail error-handling options: to discard the value, to set a specified value (that can also be used in triggers) 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. Note that for this preprocessing step, the Custom on fail checkbox is grayed out and always marked.
• This step is always executed as the first preprocessing step and is placed above all others after saving changes to the item. It can be used only once.

変更されていない値を破棄

変更されていない値を破棄します。

コメント:

• 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはこの値が受信されたことを認識しません。トリガー式は評価されず、結果として、関連するトリガーに関する問題は発生/解決されません。関数は、データベースに実際に保存されたデータに基づいてのみ動作します。トレンドはデータベースのデータに基づいて構築されるため、1時間にわたって値が保存されていない場合、その時間のトレンドデータも存在しません。
  
• アイテムごとに指定できるスロットリングオプションは1つだけです。

ハートビート付きで変更なし破棄

定義された時間（秒）内に値が変更されなかった場合、その値を破棄します。

コメント:

• 秒数を指定するために正の整数値がサポートされています（最小値は1秒）
  
• 時間の接尾辞を使用できます（例：30s、1m、2h、1d）
  
• ユーザーマクロと低レベル検出マクロを使用できます。
  
• 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはその値が受信されたことを認識しません。トリガー式は評価されないため、関連するトリガーに問題が発生/解決されることはありません。関数は、データベースに実際に保存されたデータに基づいてのみ動作します。トレンドはデータベース内のデータに基づいて構築されるため、1 時間にわたって値が保存されていない場合は、その時間のトレンドデータも存在しません。
  
• アイテムごとに指定できるスロットルオプションは 1 つだけです。

Prometheus パターン

以下のクエリを使用して、Prometheus メトリックから必要なデータを抽出します。

詳細については、Prometheus チェック を参照してください。

Prometheus から JSON へ変換

必要な Prometheus メトリクスを JSON に変換します。

詳細については、Prometheus チェック を参照してください。

マクロのサポート

ユーザーマクロ およびコンテキスト付きユーザーマクロは、以下の環境でサポートされています。

• JavaScript コードを含む、前処理ステップのパラメータ
• カスタムエラー処理パラメータ (値の設定先 および エラーの設定先 フィールド)

Testing

前処理テストを参照してください。