[comment]: # translation:outdated [comment]: # ({cf5ea635-cd1d3c06}) # 2 监控项值预处理 [comment]: # ({/cf5ea635-cd1d3c06}) [comment]: # ({03373208-cb2c0d06}) #### 概述 预处理允许为接收到的监控项值定义转换规则。 在将值保存到数据库之前，可以进行一次或多次转换。 转换按照它们定义的顺序执行。预处理是由Zabbix server或者Zabbix proxy (如果监控项通过proxy进行监控)执行。 请注意，转换成所需要的值类型是在预处理步骤的后期执行的，如果有需要，转换也可以进行相应的预处理步骤。详见 [preprocessing details](/manual/config/items/preprocessing/preprocessing_details)了解更多技术细节。 还可以参考: [Usage examples](/manual/config/items/preprocessing/examples) [comment]: # ({/03373208-cb2c0d06}) [comment]: # ({44dc69df-033c164f}) #### 配置 预处理规则在监控项的 **预处理** 标签中进行[配置](/manual/config/items/item#configuration) 。 ![](../../../../assets/en/manual/config/items/item_c.png){width="600"} ::: noteimportant 任何预处理步骤失败都将导致监控项变成[不支持的](/manual/config/items/item#unsupported_items)，除非使用自定义失败选项（*Custom on fail*）指定自定义错误处理办法。\ \ 对于日志监控项，日志元数据(没有值)将总是重置监控项的不支持的状态，使监控项再次受到支持，即使在从agent接收到日志值后发生了初始错误。 ::: [用户宏](/manual/config/macros/user_macros) 在监控项值预处理参数中支持带有上下文的用户宏，包含JavaScript代码。 ::: noteclassic 当宏被它的值替换时，上下文将被忽略。宏值将直接插入到代码中，在将值放入JavaScript代码之前不能添加额外的转义。请注意，在某些情况下，这可能会导致JavaScript错误。 ::: |类型|<|<| |----|----|----| | |*转换动作*|描述| |文本|<|<| | |*正则表达式*|将值与 正则表达式匹配，并将值替换为 。 正则表达式支持使用 \N 序列提取最多 10 个捕获的组。 输入值不匹配将使该监控项不受支持。
参数:
**pattern** - 正则表达式
**output** - 输出格式模板。 \\N（其中 N=1…9）转义序列将替换为第 N 个匹配组。 \\0 转义序列将替换为匹配的文本。
请参考 [正则表达式](/manual/regular_expressions#example) 部分现有示例。
如果你勾选了 *自定义失败* 复选框, 则在预处理步骤失败时，该监控项将不受支持，并且可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。| |^|*替换*|找到搜索字符串并将其替换为另一个（或没有）。 将替换所有出现的搜索字符串。
参数:
**search string** - 要查找和替换的字符串，区分大小写（必需）
**replacement** - 用于替换搜索字符串的字符串。 替换字符串也可以为空，有效地允许在找到时删除搜索字符串。
可以使用转义序列来搜索或替换换行符、回车符、制表符和空格“\\n \\r \\ t \\s"; 反斜杠可以转义为“\\\\”，转义序列可以转义为“\\\\n”。 在底层自动发现期间自动完成换行符、回车、制表符的转义。| |^|*截取*|从值的开头和结尾删除指定的字符。| |^|*右截取*|从值的末尾删除指定的字符。| |^|*左截取*|从值的开头删除指定的字符。| |结构化数据|<|<| | |*XML XPath*|使用 XPath 功能从 XML 数据中提取值或片段。
要使此选项起作用，必须在编译 Zabbix server 时使用 libxml 参数。
示例:
`number(/document/item/value)` 将从 `10`提取 `10`
`number(/document/item/@attribute)` 将从 `` 提取 `10`
`/document/item` will extract `10` from `10`
注意，不支持命名空间。
如果您勾选了 *自定义失败* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误信息。| |^|*JSON Path*|使用 [JSONPath 功能](/manual/config/items/preprocessing/jsonpath_functionality) 从 JSON 数据中提取值或片段 。
如果您勾选了 *自定义失败* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误信息。| |^|*CSV to JSON*|将CSV文件数据转换为JSON格式。
有关更多信息，请参见: [CSV to JSON 预处理](/manual/config/items/preprocessing/csv_to_json#csv_header_processing).| |^|*XML to JSON*|将 XML 格式的数据转换为 JSON。
有关更多信息，请参见: [序列化规则](/manual/config/items/preprocessing/javascript/javascript_objects#serialization_rules)。
如果您勾选了 *自定义失败* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误信息。| |算术|<|<| | |*自定义乘数*|将该值乘以指定的整数或浮点值。
使用此选项将以 KB、MBps 等形式接收的值转换为 B、Bps。 否则 Zabbix无法正确设置(K, M, G 等) [后缀](/manual/appendix/suffixes) (K, M, G etc).
*注意* 如果监控项类型是 _数字 (无符号)_, 在传入自定义乘法器之前带有小数部分的传入值将被裁剪 ('0.9' 将变成 '0')。
支持: 科学记数法, 例如, `1e+70` (从2.2开始); 用户宏和LLD宏 (从4.0版本开始); 包含宏的字符串, 例如, `{#MACRO}e+10`, `{$MACRO1}e+{$MACRO2}` (从5.2.3版本开始)
宏必须解析为整数或浮点数。
如果你使用 *自定义失败* 复选框, 在预处理步骤失败的情况下，该项不会变得不受支持，并且可以指定自定义错误处理选项:丢弃该值、设置指定值或设置指定的错误消息。| |更改|<|<| |<|*简单更改*|计算当前值与先前值的差值。
计算为**value**-**prev\_value**，其中
*value* - 当前值； *prev\_value* - 以前收到的值
此设置可用于衡量不断增长的值。 如果当前值小于前一个值，Zabbix 会丢弃该差异（不存储任何内容）并等待另一个值。
每个监控项只允许进行一次更改操作。
如果您选中 *Custom on fail* 复选框 ，如果预处理步骤失败，该项目将不会变得不受支持，并且可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。| |^|*每秒更改*|计算每秒速度的值变化（当前值与先前值之间的差异）。
计算为 (**value**-**prev\_value**)/(**time**-**prev\_time **), 其中
*value* - 当前值； *prev\_value* - 先前收到的值； *time* - 当前时间戳； *prev\_time* - 前一个值的时间戳。
此设置对于获取不断增长的值的每秒速度非常有用。如果当前值小于前一个值，Zabbix 会丢弃该差异（不存储任何内容）并等待另一个值。这有助于正确处理，例如，32 位 SNMP 计数器的包装（溢出）。
*注意*：由于此计算可能产生浮点数，建议设置“信息类型”到 *Numeric (浮点型)*，即使传入的原始值是整数。这对于小数部分很重要的小数尤其重要。如果浮点值很大并且可能超过 'float' 字段长度，在这种情况下整个值可能会丢失，实际上建议使用 *Numeric (unsigned)* 并且只修剪小数部分。
每个监控项只允许进行一次更改操作。
如果您选中 *Custom on fail* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：要么丢弃value，设置一个指定的值，或者设置一个指定的错误信息。| |数字系统|<|<| | |*布尔到十进制*|将值从布尔格式转换为十进制。 文本表示被转换为 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。
如果您标记 *Custom on fail* 复选框 ，如果预处理步骤失败，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。| | |*八进制转十进制*|将值从八进制格式转换为十进制。
如果您选中 *Custom on fail* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：要么丢弃 value，设置一个指定的值，或者设置一个指定的错误信息。| | |*十六进制转十进制*|将值从十六进制格式转换为十进制。
如果您选中 *Custom on fail* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：要么丢弃 value，设置一个指定的值，或者设置一个指定的错误信息。| |自定义脚本|<|<| | |*JavaScript*|在单击参数字段或铅笔图标时出现的块中输入JavaScript代码。
注意, 可用的JavaScript长度取决于所使用的 [使用的数据库](#custom_script_limit).
有关更多信息，请参见:[Javascript 预处理](/manual/config/items/preprocessing/javascript).| |验证|<|<| | |*在范围内*|通过指定最小/最大值（包括）来定义值应在的范围。
接受数值（包括任意位数、可选的小数部分和可选的指数部分、负值）。 可以使用用户宏和底层自动发现宏。 最小值应小于最大值。
必须至少存在一个值。
如果您选中 *Custom on fail* 复选框，则在预处理步骤失败的情况下，该监控项不会变得不受支持，并且有可能 指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。| |^|*匹配正则表达式*|指定一个值必须匹配的正则表达式。
如果您选中 *Custom on fail* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：要么丢弃值，设置一个指定的值，或者设置一个指定的错误信息。| |^|*不匹配正则表达式*|指定一个值不能匹配的正则表达式。
如果您选中 *Custom on fail* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：要么 丢弃该值，设置一个指定的值，或设置一个指定的错误消息。| |^|*检查 JSON 中的错误*|检查位于 JSONpath 的应用程序级错误消息。 如果成功并且消息不为空则停止处理； 否则，使用此预处理步骤之前的值继续处理。 请注意，这些外部服务错误会按原样报告给用户，而不添加预处理步骤信息。
如果无法解析无效 JSON，则不会报告错误。
如果您选中 *Custom on fail* 复选框 ，如果预处理步骤失败，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。| |^|*检查 XML 中的错误*|检查位于 XPath 的应用程序级错误消息。 如果成功并且消息不为空则停止处理； 否则，使用此预处理步骤之前的值继续处理。 请注意，这些外部服务错误将按原样报告给用户，而不添加预处理步骤信息。
如果无法解析无效 XML，则不会报告错误。
如果您选中 *Custom on fail* 复选框 ，如果预处理步骤失败，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。| |^|*使用正则表达式检查错误*|使用正则表达式检查应用程序级错误消息。 如果成功并且消息不为空则停止处理； 否则，使用此预处理步骤之前的值继续处理。 请注意，这些外部服务错误按原样报告给用户，无需添加预处理步骤信息。
参数：
**pattern** - 正则表达式
**output** - 输出格式模板。 \\N（其中 N=1…9）转义序列将替换为第 N 个匹配组。 \\0 转义序列将替换为匹配的文本。
如果您选中 *Custom on fail* 复选框，则在预处理步骤失败的情况下，该监控项将不会变得不受支持，并且可以指定自定义错误处理选项： 要么丢弃该值，设置一个指定的值，或者设置一个指定的错误消息。| |^|*检查不支持的值*|检查检索监控项值是否有错误。 通常这会导致监控项变得不受支持，但您可以通过指定 *Custom on fail* 错误处理选项来修改该行为：丢弃值，设置指定值（在这种情况下，监控项将保持支持并且 value 可以在触发器中使用）或设置指定的错误消息。 请注意，对于此预处理步骤，*失败时自定义*复选框灰显并始终标记。
此步骤始终作为第一个预处理步骤执行，并在保存对监控项的更改后置于所有其他步骤之上。 它只能使用一次。
从 5.2.0 开始支持。| |节流|<|<| |<|*丢弃不变*|如果一个值没有改变，则丢弃它。
如果一个值被丢弃，它不会保存在数据库中，并且 Zabbix 服务器不知道该值已被接收。 不会评估触发器表达式，因此不会创建/解决相关触发器的问题。 函数仅基于实际保存在数据库中的数据起作用。 由于趋势是基于数据库中的数据构建的，如果一个小时内没有保存任何值，则该小时也不会有趋势数据。
只能为一个监控项指定一个限制选项。
* 注意* Zabbix 代理监控的监控项有可能非常小的值差异（小于 0.000001）不会被代理正确丢弃，但如果 Zabbix 服务器数据库 [尚未升级](https://www.zabbix.com/documentation/5.0/manual/installation/upgrade_notes_500#enabling_extended_range_of_numeric_float_values)，则作为相同的值存储在历史记录中| |^|*丢弃不变的心跳*|如果值在定义的时间段内（以秒为单位）未更改，则丢弃该值。
支持正整数值来指定秒数（最小值 - 1 秒）。该字段可以使用时间后缀（例如 30s、1m、2h、1d）。在该字段中可以使用用户宏和底层自动发现宏。
如果一个值被丢弃，它不会保存在数据库中，并且 Zabbix 服务器不知道该值已被接收。不会评估触发器表达式，因此不会创建/解决相关触发器的问题。函数仅基于实际保存在数据库中的数据起作用。由于趋势是基于数据库中的数据构建的，如果一个小时内没有保存任何值，则该小时也不会有趋势数据。
只能为一个监控项指定一个限制选项。
*注意* Zabbix 代理监控的监控项有可能非常小的值差异（小于 0.000001）不会被代理正确丢弃，但如果 Zabbix 服务器数据库 [尚未升级](https://www.zabbix.com/documentation/5.0/manual/installation/upgrade_notes_500#enabling_extended_range_of_numeric_float_values)，则作为相同的值存储在历史记录中。| |Prometheus|<|<| | |*Prometheus pattern*|使用以下查询从 Prometheus 指标中提取所需数据。
有关更多信息，请参考：[Prometheus checks](/manual/config/items/itemtypes/prometheus)| |^|*Prometheus to JSON*|将所需的 Prometheus 指标转换为 JSON。
有关更多信息，请参考：[Prometheus checks](/manual/config/items/itemtypes/prometheus)| ::: noteimportant 对于更改和限制预处理步骤，需要使用以前的值来计算/比较新值。以前的值由预处理管理器处理，预处理步骤配置在进行更改或Zabbix server/proxy重新启动时重置。由于先前的值重置: - 对于*简单改变*, *每秒更改* 步骤 - 下一个值将被忽略，因为没有先前的值来计算更改; - 对于 *丢弃没有改变的数据*. *带心跳检查丢弃不变化的数据* 步骤 - 下一个值永远不会被丢弃, 即使它应该因为丢弃规则而被丢弃，也不会丢弃。 ::: 当定义了至少一个预处理步骤时，监控项的*信息类型*参数显示在选项卡的底部。 如果需要，可以在不离开 *Preprocessing* 选项卡的情况下更改信息类型。 详细参数说明见 [创建监控项](/manual/config/items/item) 。 ::: notetip 如果您对信息类型设置为 *Numeric (unsigned)* 的监控项使用自定义乘数或将值存储为 *Change per second* 并且得到的计算值实际上是一个浮点数，通过修剪小数部分并将值存储为整数，计算值仍然被接受为正确的值。 ::: [comment]: # ({/44dc69df-033c164f}) [comment]: # ({ad67af50-ad67af50}) #### Testing 测试预处理步骤有助于确保复杂的预处理管道产生预期的结果，而无需等待接收和预处理监控项值。 ![](../../../../assets/en/manual/config/items/test_item_steps.png){width="600"} 可以测试： - 与假设值相比 - 与主机的实际值相比较 每个预处理步骤都可以单独测试，也可以一起测试所有步骤。 当您分别单击 动作块中的 *Test* 或 *Test all steps* 按钮时，将打开一个测试窗口。 [comment]: # ({/ad67af50-ad67af50}) [comment]: # ({5f142cad-45423233}) ##### 检验假设值 ![](../../../../assets/en/manual/config/items/test_item_p.png){width="600"} |参数|描述| |---------|-----------| |*从主机获取值*|如果您想测试假设值，请不要选中此复选框。
另请参阅：[测试真实值](#testing_real_value).| |*值*|输入要测试的输入值。
单击参数字段或查看/编辑按钮将打开一个文本区域窗口，用于输入值或代码块。| |*不支持的*|选中此复选框可测试不受支持的值。
此选项可用于测试 *检查不受支持的值* 预处理步骤。| |*时间*|显示输入值的时间：`now`（只读）。| |*以前的值*|输入之前的输入值进行比较。
仅适用于 *更改* 和 *节流* 预处理步骤。| |*以前的时间点*|输入之前的输入值时间进行比较。
仅适用于*更改* 和 *节流* 预处理步骤。
默认值基于监控项的“更新间隔”字段值（如果为“1m”， 然后这个字段用`now-1m`填充）。 如果未指定任何内容或用户无权访问主机，则默认为 `now-30s`。| |*宏*|如果使用了任何宏，它们将与它们的值一起列出。 出于测试目的，这些值是可编辑的，但更改只会保存在测试上下文中。| |*行尾序列*|为多行输入值选择行尾序列：
**LF** - LF（换行）序列
**CRLF** - CRLF（回车换行）序列。| |*预处理步骤*|列出了预处理步骤； 单击 *Test* 按钮后，将显示每个步骤的测试结果。
如果该步骤测试失败，则会显示错误图标。 鼠标悬停时会显示错误描述。
如果为步骤指定了“失败时自定义”并执行了该操作，则会在预处理测试步骤行之后立即出现一个新行，显示已执行的操作和结果 产生（错误或值）。| |*结果*|测试预处理步骤的最终结果在所有步骤一起测试时显示在所有情况下（当您单击*测试所有步骤*按钮时）。
还显示转换为监控项的值类型的类型， 例如“结果转换为数字（无符号）”。| 单击 *测试* 以查看每个预处理步骤后的结果。 测试值存储在单个步骤或所有步骤的测试会话之间，允许用户更改预处理步骤或监控项配置，然后返回到测试窗口，而无需重新输入信息。 但是，页面刷新时值会丢失。 测试由 Zabbix server 完成。 前端向服务器发送相应的请求并等待结果。 该请求包含输入值和预处理步骤（带有扩展的用户宏）。 对于 *更改* 和 *节流* 步骤，可以指定可选的先前值和时间。 服务器响应每个预处理步骤的结果。 所有技术错误或输入验证错误都显示在测试窗口顶部的错误框中。 [comment]: # ({/5f142cad-45423233}) [comment]: # ({176c98bb-43637da5}) ##### 测试真实值 根据实际值测试预处理: - 标记 *从主机获取值* 复选框 - 输入或验证主机参数（主机地址、端口、代理名称/无代理）和监控项特定的详细信息（例如 SNMPv2 社区或 SNMPv3 安全凭证）。这些字段是上下文感知的： - 这些值在可能的情况下预先填写，即对于需要agent的监控项，通过从主机的选定agent接口获取信息 - 模板监控项的值必须手动填写 - 解析纯文本宏值 - 值（或部分值）为机密或 Vault 宏的字段为空，必须手动输入。如果任何监控项参数包含秘密宏值，则会显示以下警告消息：“监控项包含具有秘密值的用户定义的宏。应手动输入这些宏的值。” - 在监控项类型的上下文中不需要时禁用这些字段（例如，计算监控项的主机地址和代理字段被禁用） - 点击 *获取值并测试* 来测试预处理 ![](../../../../assets/en/manual/config/items/test_item_p2.png){width="600"} 如果您在监控项配置表单（“显示值”字段）中指定了值映射，监控项测试对话框将在最终结果之后显示另一行，名为“应用了值映射的结果”。 特定于从主机获取实际值的参数: |参数|描述| |---------|-----------| |*从主机获取值*|标记此复选框以从主机获取实际值。| |*主机地址*|输入主机地址。
此字段由监控项主机接口的地址自动填充。| |*端口*|输入主机端口。
此字段由监控项主机接口的端口自动填充。| |*SNMP 接口的附加字段
(SNMP 版本、SNMP 社区、上下文名称等)*|有关配置 SNMP 接口（v1、v2 和 v3）的更多详细信息。请查看[配置 SNMP 监控](/manual/config/items/itemtypes/snmp#step_2)。
这些字段会从监控项主机接口自动填充。| |*代理*|如果主机由代理监控，请指定代理。
此字段由主机的代理（如果有）自动填充。| 有关其余参数，请参考 [Testing hypothetical value](#testing_hypothetical_value) 。 [comment]: # ({/176c98bb-43637da5})