Documentation
2 アイテムの値の保存前処理
概要
保存前処理を行うことで、受け取った項目の値の変換ルールを定義することができます。
データベースに保存する前に、1つまたは複数の変換を行うことができます。
変換は定義された順番に実行されます。
保存前処理はZabbixサーバまたはプロキシ(プロキシでアイテムを監視している場合)で実行されます。
保存前処理に渡される値はすべて文字列型であり、(アイテムの設定で定義された)目的の値の型への変換は、
保存前処理パイプラインの最後に実行されることに注意してください。
ただし、変換は対応する保存前処理工程で必要とされる場合に行われることもあります。
詳細は保存前処理の詳細をご参照ください。
使用例も併せてご参照ください。
設定
保存前処理のルールは、アイテム設定の保存前処理タブで定義します。
保存前処理のいずれかに失敗すると、アイテムは取得不可 となります。 ただし、サポートされている変換の 失敗時のカスタマイズ オプションを使用して、カスタムのエラー処理を指定した場合はこの限りではありません。
ログアイテムの場合、ログメタデータ（値なし）は常にアイテムの取得不可状態をリセットし、再びサポートされるようにします。
ユーザーマクロおよびユーザーマクロのコンテキストは、アイテム保存前処理のパラメータやJavaScriptのコード内でサポートされています。
マクロをその値で置き換える場合、コンテキストは無視されます。 マクロの値はそのままコードに挿入されるため、JavaScriptのコードに値を配置する前に追加のエスケープを行うことはできません。 このため、場合によってはJavaScriptエラーが発生する可能性があります。
| Type | ||
|---|---|---|
| Transformation | Description | |
| Text | ||
| Regular expression | Match the value to the <pattern> regular expression and replace value with <output>. The regular expression supports extraction of maximum 10 captured groups with the \N sequence. Failure to match the input value will make the item unsupported. Parameters: pattern - regular expression output - 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. Please refer to regular expressions section for some existing examples. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value or set a specified error message. |
|
| Replace | Find the search string and replace it with another (or nothing). All occurrences of the search string will be replaced. Parameters: search string - the string to find and replace, case-sensitive (required) replacement - the string to replace the search string with. The replacement string may also be empty effectively allowing to delete the search string when found. It is possible to use escape sequences to search for or replace line breaks, carriage return, tabs and spaces "\n \r \t \s"; backslash can be escaped as "\\" and escape sequences can be escaped as "\\n". Escaping of line breaks, carriage return, tabs is automatically done during low-level discovery. |
|
| Trim | Remove specified characters from the beginning and end of the value. | |
| Right trim | Remove specified characters from the end of the value. | |
| Left trim | Remove specified characters from the beginning of the value. | |
| Structured data | ||
| XML XPath | Extract value or fragment from XML data using XPath functionality. For this option to work, Zabbix server must be compiled with libxml support. Examples: number(/document/item/value) will extract 10 from <document><item><value>10</value></item></document>number(/document/item/@attribute) will extract 10 from <document><item attribute="10"></item></document>/document/item will extract <item><value>10</value></item> from <document><item><value>10</value></item></document>Note that namespaces are not supported. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error-handling options: either to discard the value, set a specified value or set a specified error message. |
|
| JSON Path | Extract value or fragment from JSON data using JSONPath functionality. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error-handling options: either to discard the value, set a specified value or set a specified error message. |
|
| CSV to JSON | Convert CSV file data into JSON format. For more information, see: CSV to JSON preprocessing. |
|
| XML to JSON | Convert data in XML format to JSON. For more information, see: Serialization rules. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error-handling options: either to discard the value, set a specified value or set a specified error message. |
|
| Arithmetic | ||
| Custom multiplier | Multiply the value by the specified integer or floating-point value. 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. Supported: scientific notation, for example, 1e+70 (since version 2.2); user macros and LLD macros (since version 4.0); strings that include macros, for example, {#MACRO}e+10, {$MACRO1}e+{$MACRO2}(since version 5.2.3)The macros must resolve to an integer or a floating-point number. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Change | ||
| Simple change | Calculate the difference between the current and previous value. Evaluated as value-prev_value, where value - current value; prev_value - previously received value This setting can be useful to measure a constantly growing value. If the current value is smaller than the previous value, Zabbix discards that difference (stores nothing) and waits for another value. Only one change operation per item is allowed. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Change per second | Calculate the value change (difference between the current and previous value) speed per second. Evaluated as (value-prev_value)/(time-prev_time), where value - current value; prev_value - previously received value; time - current timestamp; prev_time - timestamp of previous value. This setting is extremely useful to get speed per second for a constantly growing value. 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. Note: 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. Only one change operation per item is allowed. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Numeral systems | ||
| Boolean to decimal | Convert the value from boolean format to decimal. The textual representation is translated into either 0 or 1. Thus, 'TRUE' is stored as 1 and 'FALSE' is stored as 0. All values are matched in a case-insensitive way. Currently recognized values are, for: TRUE - true, t, yes, y, on, up, running, enabled, available, ok, master FALSE - false, f, no, n, off, down, unused, disabled, unavailable, err, slave Additionally, any non-zero numeric value is considered to be TRUE and zero is considered to be FALSE. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Octal to decimal | Convert the value from octal format to decimal. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Hexadecimal to decimal | Convert the value from hexadecimal format to decimal. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Custom scripts | ||
| JavaScript | Enter JavaScript code in the block that appears when clicking in the parameter field or on a pencil icon. Note that available JavaScript length depends on the database used. For more information, see: Javascript preprocessing. |
|
| Validation | ||
| In range | 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, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Matches regular expression | Specify a regular expression that a value must match. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Does not match regular expression | Specify a regular expression that a value must not match. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Check for error in JSON | Check for an application-level error message located at JSONpath. Stop processing if succeeded and the message is not empty; otherwise, continue processing with the value that was before this preprocessing step. Note that these external service errors are reported to the user as is, without adding preprocessing step information. No error will be reported in case of failing to parse invalid JSON. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Check for error in XML | Check for an application-level error message located at XPath. Stop processing if succeeded and the message is not empty; otherwise, continue processing with the value that was before this preprocessing step. Note that these external service errors are reported to the user as is, without adding preprocessing step information. No error will be reported in case of failing to parse invalid XML. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Check for error using a regular expression | Check for an application-level error message using a regular expression. Stop processing if succeeded and the message is not empty; otherwise, continue processing with the value that was before this preprocessing step. Note that these external service errors are reported to the user as is, without adding preprocessing step information. Parameters: pattern - regular expression output - 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. If you mark the Custom on fail checkbox, the item will not become unsupported in case of failed preprocessing step and it is possible to specify custom error handling options: either to discard the value, set a specified value, or set a specified error message. |
|
| Check for not supported value | Check if there was an error in retrieving item value. Normally that would lead to the item turning 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 (in this case the item will stay supported and the value can be used in triggers) or set a specified error message. 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. Supported since 5.2.0. |
|
| Throttling | ||
| Discard unchanged | Discard a value if it has not changed. If a value is discarded, it is not saved in the database and Zabbix server has no knowledge that this value was received. No trigger expressions will be evaluated, as a result, no problems for related triggers will be created/resolved. Functions will work only based on data that is actually saved in the database. As trends are built based on data in the database, if there is no value saved for an hour then there will also be no trends data for that hour. Only one throttling option can be specified for an item. Note that it is possible for items monitored by Zabbix proxy that very small value differences (less than 0.000001) are correctly not discarded by proxy, but are stored in the history as the same value if the Zabbix server database has not been upgraded. |
|
| Discard unchanged with heartbeat | Discard a value if it has not changed within the defined time period (in seconds). Positive integer values are supported to specify the seconds (minimum - 1 second). Time suffixes can be used in this field (e.g. 30s, 1m, 2h, 1d). User macros and low-level discovery macros can be used in this field. If a value is discarded, it is not saved in the database and Zabbix server has no knowledge that this value was received. No trigger expressions will be evaluated, as a result, no problems for related triggers will be created/resolved. Functions will work only based on data that is actually saved in the database. As trends are built based on data in the database, if there is no value saved for an hour then there will also be no trends data for that hour. Only one throttling option can be specified for an item. Note that it is possible for items monitored by Zabbix proxy that very small value differences (less than 0.000001) are correctly not discarded by proxy, but are stored in the history as the same value if the Zabbix server database has not been upgraded. |
|
| Prometheus | ||
| Prometheus pattern | Use the following query to extract required data from Prometheus metrics. See Prometheus checks for more details. |
|
| Prometheus to JSON | Convert required Prometheus metrics to JSON. See Prometheus checks for more details. |
|
保存前処理のステップの変更と調整のために、Zabbixは必要に応じて新しい値を計算/比較するために、最後の値を覚えておく必要があります。これらの以前の値は保存前処理マネージャによって処理されます。Zabbixサーバまたはプロキシを再起動した場合、または保存前処理ステップを変更した場合、Zabbixは最後の値を記憶し、必要に応じて新しい値を計算/比較します。
- 差分、1秒あたりの差分 ステップの場合、次の値は無視されます。
次の値は、変化量を計算する前の値がないため、無視されます。 - 変更がなければ破棄、指定病内に変化がなければ破棄ステップの場合、
次の値は、たとえ破棄される必要があったとしても、破棄されることはありません。
アイテムのデータ型パラメータは、少なくとも1つの保存前処理工程が定義されている場合、タブの下部に表示されます。
必要であれば、保存前処理タブを開いたまま情報の種類を変更することができます。
アイテムの作成 を参照してください。
カスタム倍率を使用する場合、または値を 1秒当たりの差分 として保存する場合、数値(整数)に設定されている項目で、計算結果の値が実際には浮動小数点数であっても、小数点以下を切り捨てて整数値として格納することで、正しい値として扱われます。
保存前処理のテスト
保存前処理ステップのテストは、アイテムの値の受信と保存前処理を待たずに、複雑なプリプロセスパイプラインが期待される結果をもたらすことを確認するのに有効です。
- 仮想的な値に対してテストすることが可能です。
- ホストからの実際の値に対してテストすることが可能です。
保存前処理の各ステップを個別にテストすることも、すべてのステップを一緒にテストすることも可能です。アクションブロックの テスト または すべてのテスト ボタンをクリックすると、テストウィンドウが表示されます。
仮想的な値のテスト
| パラメータ | 説明 |
|---|---|
| Get value from host | If you want to test a hypothetical value, leave this checkbox unmarked. See also: Testing real value. |
| Value | Enter the input value to test. Clicking in the parameter field or on the view/edit button will open a text area window for entering the value or code block. |
| Not supported | Mark this checkbox to test an unsupported value. This option is useful to test the Check for not supported value preprocessing step. |
| Time | Time of the input value is displayed: now (read-only). |
| Previous value | Enter a previous input value to compare to. Only for Change and Throttling preprocessing steps. |
| Previous time | Enter the previous input value time to compare to. Only for Change and Throttling preprocessing steps. The default value is based on the 'Update interval' field value of the item (if '1m', then this field is filled with now-1m). If nothing is specified or the user has no access to the host, the default is now-30s. |
| Macros | If any macros are used, they are listed along with their values. The values are editable for testing purposes, but the changes will only be saved within the testing context. |
| End of line sequence | Select the end of line sequence for multiline input values: LF - LF (line feed) sequence CRLF - CRLF (carriage-return line-feed) sequence. |
| Preprocessing steps | Preprocessing steps are listed; the testing result is displayed for each step after the Test button is clicked. If the step failed in testing, an error icon is displayed. The error description is displayed on mouseover. In case "Custom on fail" is specified for the step and that action is performed, a new line appears right after the preprocessing test step row, showing what action was done and what outcome it produced (error or value). |
| Result | The final result of testing preprocessing steps is displayed in all cases when all steps are tested together (when you click on the Test all steps button). The type of conversion to the value type of the item is also displayed, for example Result converted to Numeric (unsigned). |
各保存前処理後の結果を見るには、テストをクリックしてください。
テストセッションの間に、個々のステップまたは全ステップについてテスト値を保存することが出来るので、保存前処理やアイテムの設定を変更しても、情報を再入力することなくテストウィンドウに戻ることができます。ただし、ページの更新時に値は失われます。
テストはZabbixサーバーで行われます。フロントエンドは対応するリクエストをサーバに送信し結果を待ちます。リクエストには入力値と保存前処理のステップ(拡張ユーザマクロを含む)が含まれます。変化および絞り込みのステップでは、オプションで前値と時間を指定することができます。サーバーは、各保存前処理ステップの結果を応答します。
すべての技術的エラーまたは入力検証エラーは、テストウィンドウ上部のエラーボックスに表示されます。
実測値のテスト
保存前処理を実測値に対してテストするため、
- ホストから値を取得 チェックボックスをマークします。
- ホストパラメータ（ホストアドレス、ポート、プロキシ名 / プロキシなし）および項目固有の詳細
（SNMPv2コミュニティやSNMPv3セキュリティ認証など）を入力または確認します。これらのフィールドは、コンテキストを認識します。
- エージェントを必要とする項目については、ホストの選択されたエージェントインターフェースから情報を取得することで、
可能な限り値は事前に入力されます。 - テンプレートアイテムの場合は、値を手動で入力する必要があります。
- プレーンテキストのマクロ値は解決されます。
- 値(または値の一部)がシークレットまたはVaultマクロであるフィールドは空であるため、手動で入力しなければなりません。
アイテムのパラメータにシークレットマクロ値が含まれている場合、次のような警告メッセージが表示されます。
"アイテムは秘密な値を持つユーザー定義マクロを含んでいます。これらのマクロの値は手動で入力する必要があります。" - アイテムタイプのコンテキストで必要ない場合、フィールドは無効化されます。
フィールドは、アイテムの種類によって必要ない場合は無効になります
(たとえば、ホストアドレスとプロキシフィールドは、計算されたアイテムでは無効になります)。
- エージェントを必要とする項目については、ホストの選択されたエージェントインターフェースから情報を取得することで、
- 保存前処理をテストするには、値の取得とテスト をクリックします。
アイテム設定画面で値のマッピングを指定している場合('値のマッピング' フィールド)、アイテムテストダイアログは最終結果の後にもう1行表示します。'値のマッピングを適用した結果'という名前の別の行が表示されます。
ホストから実測値を取得する際に特有のパラメータ:
| パラメータ | 説明 |
|---|---|
| Get value from host | Mark this checkbox to get a real value from the host. |
| Host address | Enter the host address. This field is automatically filled by the address of the item host interface. |
| Port | Enter the host port. This field is automatically filled by the port of item host interface. |
| Additional fields for SNMP interfaces (SNMP version, SNMP community, Context name, etc) |
See Configuring SNMP monitoring for additional details on configuring an SNMP interface (v1, v2 and v3). These fields are automatically filled from the item host interface. |
| Proxy | Specify the proxy if the host is monitored by a proxy. This field is automatically filled by the proxy of the host (if any). |
残りのパラメータについては、上記の仮説値のテストを参照してください。