2 Item value preprocessing

    Overview

    Transformations are executed in the order in which they are defined. Preprocessing is done by Zabbix server or proxy (if items are monitored by proxy).

    Note that the conversion to desired value type (as defined in item configuration) is performed at the end of the preprocessing pipeline; conversions, however, may also take place if required by the corresponding preprocessing step. See for more technical information.

    See also: Usage examples

    Configuration

    Preprocessing rules are defined in the Preprocessing tab of the item configuration form.

    An item will become if any of the preprocessing steps fails, unless custom error handling has been specified using a Custom on fail option for supported transformations.

    For log items, log metadata (without value) will always reset item unsupported state and make item supported again, even if the initial error occurred after receiving a log value from agent.

    User macros and user macros with context are supported in item value preprocessing parameters, including JavaScript code.

    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 Discard unchanged. Discard unchanged with heartbeat steps - the next value will never be discarded, even if it should have been because of discarding rules.

    Item’s Type of information parameter is displayed at the bottom of the tab when at least one preprocessing step is defined. If required, it is possible to change the type of information without leaving the Preprocessing tab. See for the detailed parameter description.

    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.

    Testing

    Testing preprocessing steps is useful to make sure that complex preprocessing pipelines yield the results that are expected from them, without waiting for the item value to be received and preprocessed.

    2 Item value preprocessing - 图2

    It is possible to test:

    • against a hypothetical value
    • against a real value from a host

    Each preprocessing step can be tested individually as well as all steps can be tested together. When you click on the Test or Test all steps button respectively in the Actions block, a testing window is opened.

    Testing hypothetical value

    Test values are stored between test sessions for either individual steps or all steps, allowing the user to change preprocessing steps or item configuration and then return to the testing window without having to re-enter information. Values are lost on a page refresh though.

    The testing is done by Zabbix server. The frontend sends a corresponding request to the server and waits for the result. The request contains the input value and preprocessing steps (with expanded user macros). For Change and Throttling steps, an optional previous value and time can be specified. The server responds with results for each preprocessing step.

    All technical errors or input validation errors are displayed in the error box at the top of the testing window.

    Testing real value

    To test preprocessing against a real value:

    • Mark the Get value from host checkbox
    • Enter or verify host parameters (host address, port, proxy name/no proxy) and item-specific details (such as SNMPv2 community or SNMPv3 security credentials). These fields are context-aware:
      • The values have to be filled manually for template items
      • Plain-text macro values are resolved
      • Fields where the value (or part of the value) is a secret or Vault macro are empty and have to be entered manually. If any item parameter contains a secret macro value, the following warning message is displayed: “Item contains user-defined macros with secret values. Values of these macros should be entered manually.”
      • The fields are disabled when not needed in the context of the item type (e.g. the host address and the proxy fields are disabled for calculated items)
    • Click on Get value and test to test the preprocessing

    2 Item value preprocessing - 图4

    If you have specified a value mapping in the item configuration form (‘Show value’ field), the item test dialog will show another line after the final result, named ‘Result with value map applied’.

    Parameters that are specific to getting a real value from a host:

    For the rest of the parameters, see above.