2 监控项值预处理

概览

预处理允许您在将接收到的监控项值保存到数据库之前应用转换。 这些转换/预处理步骤由Zabbix server或proxy（如果监控项由proxy监控）执行。

此功能支持各种使用场景，例如：

• 将字节转换为比特（例如，将网络流量值乘以“8”）；
• 为递增值计算每秒统计信息；
• 应用正则表达式提取或修改值；
• 在值上执行自定义脚本；
• 丢弃不变的值以优化数据库存储。

可以为一个监控项配置一个或多个预处理步骤。这些步骤按配置的顺序执行。

所有传递给预处理的值最初都被视为字符串处理。 转换为所需的值类型（如监控项配置中定义）在预处理管道的末尾执行。 然而，如果需要，特定的预处理步骤可能会触发更早的转换。 对于详细的技术信息，请参阅预处理详情。

为了确保您的预处理配置按预期工作，您可以测试它。

另请参阅：预处理示例

配置

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

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

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

支持的转换

以下是所有支持的转换列表。请点击转换名称以查看其完整详情。

请注意，对于Change和Throttling预处理步骤， Zabbix需要记住最后一个值以按需计算或比较新值。 这些前一个值由预处理管理器处理。如果Zabbix server或proxy重启或预处理步骤有任何更改， 相应监控项的最后一个值将被重置，导致：

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

正则表达式

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

参数：

• 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 值 {#snmpwalk}

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

• 不变 - 将十六进制字符串作为未转义的十六进制字符串返回（注意 显示提示仍然会应用）；
  
• 从十六进制字符串转换为UTF-8 - 将十六进制字符串转换为UTF-8字符串；
  
• 从十六进制字符串转换为MAC地址 - 验证十六进制字符串是否为MAC地址，并返回正确的MAC地址字符串（其中 ' ' 被替换为 ':'）；
  
• 从BITS转换为整数 - 将表示为一系列十六进制字符的位字符串的前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 复选框（对于此预处理步骤始终标记且禁用），则可以指定自定义错误处理选项：要么丢弃值，设置指定值，或设置指定的错误消息。在预处理步骤失败的情况下，如果选择了丢弃值或设置指定值的选项，监控项将不会变为不支持。
• 此预处理步骤仅检查是否无法检索到监控项值。它不会检查，例如，检索到的值类型（如，字符串）是否与监控项的信息类型（如，数值）匹配；详细信息，请参阅 预处理示例。如果存在类型不匹配，监控项在执行所有预处理步骤后仍可能变为不支持。要检查类型不匹配，您可以使用，例如，自定义乘数 预处理步骤；参阅 预处理示例。
• 支持在 Set value to 或 Set error to 字段中捕获正则表达式组。使用 \N（其中 N=1…9）来检索第 N 个匹配的组；使用 \0 来检索匹配的文本；
• 这些步骤始终作为第一个预处理步骤执行，并在保存监控项更改后置于所有其他步骤之上；
• 支持多个 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 字段）。

测试

参见预处理测试。