2 监控项值预处理

概述

在预处理过程中，可以对接收到的监控项值进行转换，然后再将其保存到数据库中。

这种功能有很多用途。例如，您可能想要：

• 将网络流量值乘以“8”以将字节转换为比特；
• 获取逐渐增加值的每秒统计数据；
• 对值应用正则表达式；
• 对值使用自定义脚本；
• 选择丢弃未更改的值。

可以进行一个或多个转换。转换（预处理步骤）按照定义的顺序执行。

如果任何预处理步骤失败，监控项将变为不支持。可以通过失败时自定义错误处理（适用于支持的转换）来避免这种情况，该错误处理可以配置为丢弃值或设置指定值。

为了确保配置的预处理管道正常工作，可以测试它。

对于日志监控项，即使最初的错误是在从代理接收到日志值后发生的，日志元数据（没有值）也将始终重置监控项不支持状态并使监控项重新变为支持状态。

预处理由 Zabbix 服务器或代理完成（如果监控项由代理监控）。

请注意，传递到预处理的所有值都是字符串类型；预处理管道结束时会将其转换为所需的值类型（如监控项配置中定义的）。然而，如果相应的预处理步骤需要，也可能发生转换。有关更多技术信息，请参阅预处理详情。

另见：正则表达式预处理示例。

配置

预处理步骤在监控项配置表单的预处理选项卡中定义。

点击添加以选择支持的转换。

当定义了至少一个预处理步骤时，信息类型字段显示在选项卡底部。如果需要，可以在不离开预处理选项卡的情况下更改信息类型。有关详细的参数描述，请参阅创建监控项。

支持的转换

以下列出了所有支持的转换。点击转换名称以查看详细信息。

请注意，对于变化和节流预处理步骤，Zabbix需要记住最后一个值以按要求计算/比较新值。这些先前的值由预处理管理器处理。如果Zabbix服务器或代理重启或对预处理步骤进行了任何更改，对应监控项的最后一个值将被重置，导致：

• 对于简单变化、每秒变化步骤 - 下一个值将被忽略，因为没有前一个值来计算变化；
• 对于丢弃未更改的值、带心跳的丢弃未更改的值步骤 - 下一个值将永远不会被丢弃，即使应该根据丢弃规则被丢弃。

正则表达式

将值与正则表达式匹配并替换为所需的输出。

参数：

• pattern - 正则表达式；

• output - 输出格式模板。一个 \N（N=1…9）转义序列替换为第N个匹配组。一个 \0 转义序列替换为匹配的文本。

备注：

• 无法匹配输入值将使监控项不受支持；

• 正则表达式支持提取最多10个用 \N 序列表示的捕获组；

• 如果勾选自定义失败复选框，可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择了丢弃值或设置指定值选项，监控项将不会变得不受支持。

• 请参考正则表达式部分的一些现有示例。

替换

查找搜索字符串并将其替换为另一个字符串（或不替换）。

参数：

• 搜索字符串 - 要查找和替换的字符串，区分大小写（必需）；

• 替换 - 用来替换搜索字符串的字符串。替换字符串也可以为空，从而有效地在找到时删除搜索字符串。

备注：

• 搜索字符串的所有出现都将被替换；
• 可以使用转义序列查找或替换换行符、回车符、制表符和空格 “\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></document> 提取 '<item><value>10</value></item>'

JSON Path

使用 JSONPath 功能 从 JSON 数据中提取值或片段。

如果勾选 自定义错误处理 选项，可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。如果预处理步骤失败，选择丢弃值或设置指定值选项时，监控项不会变为不支持状态。

CSV to JSON

将 CSV 文件数据转换为 JSON 格式。

更多信息，请参见：CSV to JSON 预处理。

XML to JSON

将 XML 格式的数据转换为 JSON。

更多信息，请参见：序列化规则。

如果选中 Custom on fail 复选框，可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，监控项将不会变为不受支持。

SNMP walk值

通过指定的OID/MIB名称提取值并应用格式化选项：

• 不变 - 将十六进制字符串以未转义的十六进制字符串返回；

• 从十六进制字符串转换为UTF-8 - 将十六进制字符串转换为UTF-8字符串；

• 从十六进制字符串转换为MAC - 验证十六进制字符串作为MAC地址并返回适当的MAC地址字符串（其中' '被替换为':'）；

• 从位字符串转换为整数 - 将表示为十六进制字符序列的位字符串的前8字节（例如，“1A 2B 3C 4D”）转换为64位无符号整数。在超过8字节的位字符串中，后续字节将被忽略。

如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

SNMP walk转换为JSON

将SNMP值转换为JSON。

在JSON中指定一个字段名称和相应的SNMP OID路径。字段值将由指定SNMP OID路径中的值填充。

注释：

• 与SNMP walk值步骤中的值格式化选项类似；

• 您可以将此预处理步骤用于SNMP OID发现；

• 如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

SNMP 取值

对SNMP 取值应用格式化选项：

• 从十六进制字符串转换为UTF-8 - 将十六进制字符串转换为UTF-8字符串；

• 从十六进制字符串转换为MAC - 验证十六进制字符串作为MAC地址并返回适当的MAC地址字符串（其中' '被替换为':'）；

• 从位字符串转换为整数 - 将表示为十六进制字符序列的位字符串的前8字节（例如，“1A 2B 3C 4D”）转换为64位无符号整数。在超过8字节的位字符串中，后续字节将被忽略。

如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

自定义倍数

将值乘以指定的整数或浮点数。

注释：

• 使用此选项将以KB、MBps等单位接收的值转换为B、Bps。否则，Zabbix无法正确设置前缀（K、M、G等）。

• 请注意，如果信息项的类型是数字（无符号），则在应用自定义乘数之前，带有小数部分的传入值将被截断（即，“0.9”将变为“0”）；

• 如果您使用自定义乘数或将值存储为每秒变化，并且信息项的类型设置为数字（无符号），而计算出的结果实际上是浮点数，则仍然会接受计算值为正确值，通过截断小数部分并将值存储为整数；

• 支持：科学记数法，例如，1e+70；用户宏和LLD宏；包含宏的字符串，例如，{#MACRO}e+10，{$MACRO1}e+{$MACRO2}。宏必须解析为整数或浮点数。

• 如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

简单更改

计算当前值和前一个值之间的差异。

注释：

• 此步骤可用于测量不断增长的值；

• 计算公式为 value-prev_value，其中 value 是当前值，prev_value 是之前接收到的值；

• 每个项目仅允许进行一个变更操作（“简单变化”或“每秒变化”）；

• 如果当前值小于前一个值，Zabbix将丢弃该差值（不存储任何值）并等待另一个值；

• 如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

每秒更改

计算每秒的值变化（当前值与前一个值之间的差异速度）。

注释：

• 此步骤可用于计算不断增长值的每秒速度；

• 由于此计算可能产生浮点数，建议将“信息类型”设置为数字（浮点型），即使传入的原始值是整数。这对于小数部分重要的小数特别相关。如果浮点值很大并可能超出“浮点”字段长度，在这种情况下可能会丢失整个值，实际上建议使用数字（无符号），从而仅截断小数部分；

• 计算公式为 (value-prev_value)/(time-prev_time)，其中 value 是当前值；prev_value 是之前接收到的值；time 是当前时间戳；prev_time 是前一个值的时间戳；

• 每个项目仅允许进行一个变更操作（“简单更改”或“每秒更改”）；

• 如果当前值小于前一个值，Zabbix将丢弃该差值（不存储任何值）并等待另一个值。这有助于正确处理，例如32位SNMP计数器的溢出（回绕）。

• 如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

布尔值转换为十进制

将值从布尔格式转换为十进制。

注释：

• 文本表示形式将转换为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。

• 如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

八进制转换为十进制

将值从八进制格式转换为十进制。

如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

十六进制转换为十进制

将值从十六进制格式转换为十进制。

如果勾选自定义失败处理复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定错误消息。在预处理步骤失败的情况下，如果选择丢弃值或设置指定值，该项目不会变为不受支持。

JavaScript

在单击参数字段或铅笔图标时显示的块中输入 JavaScript 代码。

备注：

• 可用的 JavaScript 长度取决于所使用的数据库；

• 更多信息，请参见：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”复选框，则可以指定自定义错误处理选项：丢弃值、设置指定的值或设置指定的错误消息。如果预处理步骤失败，则项目不会变为不支持，而是选择丢弃值或设置指定的值选项。

检查不支持的值

检查是否未检索到项目值。根据检查返回的错误消息，指定应如何处理失败。

参数：

• scope - 选择错误处理范围：
  任何错误 - 任何错误；
  错误匹配 - 仅匹配在 pattern 中指定的正则表达式的错误；
  错误不匹配 - 仅匹配未匹配在 pattern 中指定的正则表达式的错误

• pattern - 用于将错误与之匹配的正则表达式。如果在 scope 参数中选择了 任何错误，则不显示此字段。如果显示，此字段为必填字段。

评论：

• 通常，缺少/未能检索到值会导致项目变为不支持。在此预处理步骤中，可以通过选中 Custom on fail 选项来修改此行为。以下自定义错误处理选项可用：Discard value、Set value to（该值可用于触发器）或 Set error to。
• 如果选择了 Discard value 或 Set value to，项目将保持支持；
• 在 Set value to 或 Set error to 字段中支持捕获正则表达式组。\N（其中 N=1…9）转义序列将被替换为第 N 个匹配组。\0 转义序列将被替换为匹配的文本。
• 对于此预处理步骤，Custom on fail 复选框被灰掉并始终标记；
• 这些步骤始终作为第一个预处理步骤执行，并在保存对项目的更改后放置在所有其他步骤之上。
• 支持多个 Check for not supported value 步骤，按指定的顺序。一个 任何错误 步骤将自动放置在此组的最后一步。

丢弃未更改的值

如果值未更改，则丢弃该值。

评论：

• 如果丢弃一个值，它不会被保存在数据库中，Zabbix 服务器不会知道接收到该值。不会评估触发器表达式，因此也不会为相关触发器创建/解决问题。函数将仅基于实际保存在数据库中的数据工作。由于趋势是基于数据库中的数据构建的，如果一个小时内没有保存值，那么该小时的趋势数据也将不存在。

• 每个项目只能指定一个节流选项。

通过心跳丢弃未更改的值

如果值在定义的时间段内未更改（以秒为单位），则丢弃该值。

评论：

• 支持使用正整数值指定秒数（最小为1秒）；

• 可以使用时间后缀（例如，30s，1m，2h，1d）；

• 可以使用用户宏和低级发现宏；

• 如果丢弃一个值，它不会被保存在数据库中，Zabbix 服务器不会知道接收到该值。不会评估触发器表达式，因此也不会为相关触发器创建/解决问题。函数将仅基于实际保存在数据库中的数据工作。由于趋势是基于数据库中的数据构建的，如果一个小时内没有保存值，那么该小时的趋势数据也将不存在。

• 每个项目只能指定一个节流选项。

Prometheus 模式

使用以下查询从 Prometheus 指标中提取所需数据。

有关更多详细信息，请参阅Prometheus 检查。

Prometheus 转 JSON

将所需的 Prometheus 指标转换为 JSON 格式。

有关更多详细信息，请参阅Prometheus 检查。

宏支持

在以下方面支持用户宏和带有上下文的用户宏：

• 预处理步骤参数，包括 JavaScript 代码；
• 自定义错误处理参数（Set value to 和 Set error to 字段）。

当宏被替换为其值时，宏上下文会被忽略。 宏的值会原样插入代码中，无法在放置值到 JavaScript 代码之前添加额外的转义。 请注意，这可能会导致某些情况下发生 JavaScript 错误。

测试

参见预处理测试。