This is a translation of the original English documentation page. Help us make it better.

Sidebar

Zabbix Summit 2022
Register for Zabbix Summit 2022

2 Item値のプリプロセッシング

概要

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

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

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

Usage examplesも併せてご参照ください。

設定

プリプロセッシングのルールは、item configurationPreprocessingタブで定義します。

プリプロセッシングのいずれかに失敗すると、item は unsupported となります。 ただし、サポートされている変換の Custom on fail オプションを使用して、カスタムのエラー処理を指定した場合はこの限りではありません。

ログ item の場合、ログメタデータ(値なし)は常に item の unsupported 状態をリセットし、再びサポートされるようにします。

User macrosおよびユーザーマクロのコンテキストを指定した
JavaScriptを含む、item プリプロセッシングパラメータでサポートされています。

マクロをその値で置き換える場合、コンテキストは無視されます。 マクロの値はそのままコードに挿入されるため、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は最後の値を記憶し、必要に応じて新しい値を計算/比較します。

  • 単純変化(Simple change)1秒あたりの変化(Change per second) ステップの場合、次の値は無視されます。
    次の値は、変化量を計算する前の値がないため、無視されます。
  • 変更なしを破棄する(Discard unchanged)ハートビートで未変更を破棄する*ステップの場合、
    次の値は、たとえ破棄される必要があったとしても、破棄されることはありません。

item のType of informationパラメータは、少なくとも1つのプリプロセス工程が定義されている場合、タブの下部に表示されます。
必要であれば、Preprocessingタブを開いたまま情報の種類を変更することができます。
Creating an item を参照してください。

カスタム倍率を使用する場合、または値を Change per second として保存する場合
情報の種類をNumericに設定した項目に対して、 Change per second として値を格納する場合、
(unsigned)に設定されている項目で、計算結果の値が実際には浮動小数点数(float)であっても、
小数点以下を切り捨てて整数値として格納することで、正しい値として扱われます。

テスト

プリプロセスステップのテストは、item 値の受信と前処理を待たずに、複雑なプリプロセスパイプラインに
期待される結果をもたらすことを確認するのに有効です。

  • 仮想的な値に対してテストすることが可能です。
  • ホストからの実際の値に対してテストすることが可能です。

プリプロセスの各ステップを個別にテストすることも、すべてのステップを一緒にテストすることも可能です。
アクションブロックの Test または Test all steps ボタンをクリックすると、テストウィンドウが表示されます。

仮想的な値のテスト

パラメータ 説明
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).

各プリプロセス後の結果を見るには、Testをクリックしてください。

テストセッションの間に、個々のステップまたは全ステップについてテスト値を保存することが出来るので、
プリプロセスやitemの設定を変更しても、情報を再入力することなくテストウィンドウに戻ることができます。
ただし、ページの更新時に値は失われます。

テストはZabbix server で行われます。フロントエンドは対応するリクエストをサーバに送信し結果を待ちます。
リクエストには入力値とプリプロセス(拡張ユーザマクロを含む)が含まれます。
ChangeおよびThrottlingのステップでは、オプションで前値と時間を指定することができます。
server は、各プリプロセスステップの結果を応答します。

すべての技術的エラーまたは入力検証エラーは、テストウィンドウ上部のエラーボックスに表示されます。

実測値のテスト

プリプロセスを実測値に対してテストするため、

  • Get value from host チェックボックスをマークします。
  • ホストパラメータ(ホストアドレス、ポート、proxy 名 / proxy なし)および項目固有の詳細
    (SNMPv2コミュニティやSNMPv3セキュリティ認証など)を入力または確認します。これらのフィールドは、コンテキストを認識します。
    • agent を必要とする項目については、ホストの選択された agent インターフェースから情報を取得することで、
      可能な限り値は事前に入力されます。
    • テンプレートアイテムの場合は、値を手動で入力する必要があります。
    • プレーンテキストのマクロ値は解決されます。
    • 値(または値の一部)がシークレットまたはVaultマクロであるフィールドは空であるため、手動で入力しなければなりません。
      item のパラメータにシークレットマクロ値が含まれている場合、次のような警告メッセージが表示されます。
      "item にシークレット値を持つユーザー定義マクロが含まれています。これらのマクロの値は手動で入力する必要があります。"
    • item タイプのコンテキストで必要ない場合、フィールドは無効化されます。
      フィールドは、item の種類によって必要ない場合は無効になります
      (たとえば、ホストアドレスと proxy フィールドは、計算された item では無効になります)。
  • プリプロセスをテストするには、Get value and test をクリックします。

item 設定フォームで値のマッピングを指定している場合('Show value' フィールド)、item テストダイアログは 最終結果の後にもう1行表示します。'Result with value map applied'という名前の別の行が表示されます。

ホストから実測値を取得する際に特有のパラメータ:

パラメータ 説明
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).

残りのパラメータについては、上記のTesting hypothetical valueを参照してください。