2 监控项值预处理

概述

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

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

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

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

所有传递给预处理的值最初都会被视为字符串。 在预处理管道的最后，会根据 监控项 配置中定义的期望值类型进行相应的 version。 不过，如有需要，特定的预处理步骤可能会触发更早的转换。 有关详细的技术信息，请参见 Preprocessing details。

为了确保你的预处理配置按预期工作，你可以使用 test it 进行验证。

另请参阅：Preprocessing examples

配置

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

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

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

支持的转换

所有支持的转换方法如下所示。点击转换方法名称可查看其详细信息。

请注意，对于Change和Throttling预处理步骤， Zabbix必须记住上一个值以计算/比较新值 按要求。这些先前的值由预处理处理 管理员。如果 Zabbix server 或 proxy 被重启或有任何更改 预处理步骤完成后，相应监控项的最后一个值是 重置，结果为：

• 对于简单变更、每秒变更数步骤 - 下一个值将 因为没有先前的值来计算变化而被忽略 来自；
• 对于 Discard unchanged、Discard unchanged with heartbeat 步骤 - 下一个值永远不会被丢弃，即使它本应该被丢弃。 由于丢弃规则。

Regular expression

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

参数：

• pattern - 正则表达式；
  
• output - 输出格式模板。\N（其中 N=1…9）转义序列为第 N 个匹配组所替换。\0 转义序列为匹配文本所替换。

注释：

• 如果输入值匹配失败，将导致 监控项 不受支持；
  
• 正则表达式支持通过 \N 序列提取最多 10 个捕获组；
  
• 如果选中 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃值、设置指定值或设置指定的错误消息。如果选择丢弃值或设置指定值选项，则预处理步骤失败时，监控项 将不会变为不受支持。
  
• 有关现有示例，请参阅 示例 章节。

Replace

查找搜索 string 并将其替换为另一个（或无）。

参数：

• 搜索 string - 要查找并替换的 string，区分大小写（必填）；
  
• 替换 - 用于替换搜索 string 的 string。替换 string 也可以为空，从而在找到搜索 string 时有效地 delete 它。

注释：

• 将替换所有出现的搜索 string；
• 可以使用转义序列为换行符、回车符、制表符和空格 "\n \r \t \s" 进行搜索或替换；反斜杠可以用 "\\" 转义，转义序列可以用 "\\n" 转义；
• 在低级别自动发现期间，会自动对换行符、回车符、制表符进行转义。

Trim

从值的开头和结尾删除指定字符。

Right trim

从值的末尾移除指定字符。

Left trim

从值的开头移除指定字符。

XML XPath

使用 XPath 功能从 XML 数据中提取值或片段。

备注：

• 要使此选项生效，Zabbix server（或 Zabbix proxy）必须在支持 libxml 的情况下编译；
• 不支持命名空间；
• 如果选中 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果预处理步骤失败且选择了丢弃该值或设置指定值的选项，则 监控项 不会变为不支持。

示例：

number(/document/监控项/value) # 将从 <document><监控项><value>10</value></监控项></document> 中提取 '10'
       number(/document/监控项/@attribute) # 将从 <document><监控项 attribute="10"></监控项></document> 中提取 '10'
       /document/监控项 # 将从 <document><监控项><value>10</value></监控项></document> 中提取 '<监控项><value>10</value></监控项>'

JSON Path

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

如果选中 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误信息。如果预处理步骤失败，并且选择了丢弃该值或设置指定值的选项，则 监控项 不会变为不支持状态。

CSV to JSON

将CSV file 数据转换为JSON格式。

更多信息请参见：5-csv-到-json-预处理。

XML to JSON

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

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

如果选中 Custom on fail 复选框，则可以指定自定义的错误处理选项：丢弃该值、设置指定值，或设置指定的错误信息。如果预处理步骤失败，并且选择了丢弃该值或设置指定值的选项，则 监控项 不会变为不支持状态。

SNMP walk value

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

• 未更改 - 返回未转义的十六进制 string 值 string（注意：显示提示仍然适用）；
  
• 从十六进制string转换为UTF-8 - 将十六进制string转换为UTF-8 string;
  
• 从十六进制-string转换MAC地址 - 验证十六进制-string为MAC地址，并返回正确的MAC地址string（其中' '被替换为':'）；
  
• integer 来自 BITS - 将以十六进制字符序列（例如，“1A 2B 3C 4D”）表示的位string的前8个字节转换为一个64位无符号的integer。对于超过8字节的位字符串，后续的字节将被忽略。

如果选中 Custom on fail 复选框，则可以指定自定义的错误处理选项：丢弃该值、设置指定的值，或设置指定的错误信息。如果预处理步骤失败，并且选择了丢弃该值或设置指定的值的选项，则监控项将不会变为不支持状态。

SNMP walk to JSON

将 SNMP 值转换为 JSON。

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

注意事项：

• 与SNMP walk 值步骤中类似的值格式化选项可用；
  
• 您可以将此预处理步骤用于 SNMP OID discovery；
  
• 如果勾选了自定义失败处理复选框，则可以指定自定义的错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果预处理步骤失败，并且选择了丢弃该值或设置指定值的选项，则监控项不会变为不支持状态。

SNMP get value

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

• 从十六进制-string转换为 UTF-8 - 将十六进制-string转换为 UTF-8 string；
  
• 从十六进制-string获取 MAC 地址 - 验证十六进制-string是否为有效的 MAC 地址，并返回正确的 MAC 地址 string（其中 ' ' 将被替换为 ':'）；
  
• 从 BITS 获取 integer - 将以十六进制字符序列（例如 "1A 2B 3C 4D"）表示的位 string 的前 8 个字节转换为一个 64 位无符号 integer。对于超过 8 字节的位字符串，后续字节将被忽略。

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

Custom multiplier

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

评论：

• 使用此选项可将接收到的 KB、MBps 等值转换为 B、Bps。否则，Zabbix 无法正确设置 prefixes（K、M、G 等）。
  
• 请注意，如果监控项信息类型为数值（无符号），则带有小数部分的传入值将在应用自定义乘数之前被截断（即，'0.9' 将变为 '0')；
  
• 如果你使用自定义乘数或以每秒变化值形式存储数值，则对于 监控项 将信息类型设置为 数值（无符号） 并将结果计算 值实际上是一个 float 数字，计算值仍将被接受为一个 通过去掉小数部分并将值存储为integer来修正它；
• 支持：科学计数法，例如 1e+70；用户宏和LLD宏；包含宏的字符串，例如 {#MACRO}e+10、{$MACRO1}e+{$MACRO2}。宏必须解析为integer或浮点数。
• 如果勾选自定义失败处理复选框，则可以指定自定义的错误处理选项：丢弃该值、设置指定值，或设置指定的错误信息。如果某个预处理步骤失败，且选择了丢弃该值或设置指定值的选项，则监控项不会变为不支持状态。

Simple change

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

说明：

• 此步骤可用于测量持续增长的值；
  
• 计算公式为 value - prev_value，其中 value 表示当前值，prev_value 表示之前接收到的值；
  
• 每个 监控项 只允许进行一次变化操作（“简单变化”或“每秒变化”）；
• 如果当前值小于前一个值，Zabbix 将丢弃该差值（不存储任何内容）并等待下一个值；
  
• 如果勾选了 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果预处理步骤失败，并且选择了丢弃该值或设置指定值的选项，则 监控项 不会变为不支持状态。

Change per second

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

备注：

• 此步骤适用于计算持续增长值的每秒速度；
• 由于该计算可能会产生浮点数，建议将“信息类型”设置为数值（float），即使传入的原始值是整数。这对于小数值尤其重要，因为小数部分会影响结果。如果浮点数值较大，并且可能超过float字段长度，从而导致整个值丢失，则建议使用数值（无符号）类型，仅截断小数部分；
• 计算公式为：(value - prev_value) / (time - prev_time)，其中 value 表示当前值，prev_value 表示前一个值，time 表示当前时间戳，prev_time 表示前一个值的时间戳；
• 每个监控项（“简单变化”或“每秒变化”）只允许执行一次变化操作；
• 如果当前值小于前一个值，Zabbix 将丢弃该差值（不存储任何内容）并等待下一个值。这有助于正确处理例如32位 SNMP 计数器的溢出情况；
• 如果选中自定义失败处理复选框，则可以指定自定义的错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果预处理步骤失败，并且选择了丢弃该值或设置指定值的选项，则监控项不会变为“不支持”。

Boolean to decimal

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

说明：

• 文本表示形式将被转换为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 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果在预处理步骤失败的情况下选择丢弃该值或设置指定值的选项，则监控项不会变为不支持状态。

Octal to decimal

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

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

Hexadecimal to decimal

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

如果选中 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果预处理步骤失败，并且选择了丢弃该值或设置指定值的选项，则监控项不会变为不支持状态。

JavaScript

点击参数字段或其旁边的铅笔图标时，在打开的模态编辑器中输入 JavaScript 代码。

注意事项：

• 可用的 JavaScript 长度取决于 自定义脚本限制；
  
• 更多信息，请参阅：Javascript preprocessing。

In range

通过指定最小/最大值（包含）来定义值应所处的范围。

备注：

• 接受数字值（包括任意位数的数字、可选的小数部分和可选的指数部分、负值）；
  
• 最小值应小于最大值；
  
• 必须至少存在一个值；
  
• 可以使用用户宏和低级别自动发现宏；
  
• 如果勾选了 自定义失败处理 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果选择丢弃该值或设置指定值的选项，则在预处理步骤失败的情况下，监控项 不会变为不支持状态。

Matches regular expression

指定一个值必须匹配的正则表达式。

如果选中 Custom on fail 复选框，则可以指定自定义的错误处理选项：丢弃该值、设置指定的值，或设置指定的错误信息。如果某个预处理步骤失败，且选择了丢弃该值或设置指定的值选项，则监控项将不会变为不支持状态。

Does not match regular expression

指定一个值必须不匹配的正则表达式。

如果选中Custom on fail复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果预处理步骤失败，并且选择了丢弃该值或设置指定值的选项，则监控项不会变为不支持状态。

Check for error in JSON

检查位于 JSONPath 的应用级别错误消息。如果检查成功且消息非空，则停止处理；否则，继续使用此预处理步骤之前的值进行处理。

备注：

• 此类外部服务错误将原样报告给用户，不会添加预处理步骤信息；
  
• 如果解析无效 JSON 失败，则不会报告错误；
  
• 如果勾选 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。如果预处理步骤失败，并且选择了丢弃该值或设置指定值的选项，监控项 将不会变为不支持状态。

Check for error in XML

检查位于 XPath 的应用级错误消息。如果检查成功且消息非空，则停止处理；否则，继续使用此预处理步骤之前的值进行处理。

备注：

• 此类外部服务错误将原样报告给用户，不会添加预处理步骤信息；
  
• 如果解析无效 XML 失败，则不会报告错误；
  
• 如果选中 自定义失败处理 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。如果在预处理步骤失败时选择丢弃该值或设置指定值的选项，监控项 将不会变为不支持状态。

Check for error using a regular expression

使用正则表达式检查应用程序级别的错误消息。如果匹配成功且消息非空，则停止处理；否则，继续使用此预处理步骤之前的值进行处理。

参数：

• pattern - 正则表达式；
  
• output - 输出格式模板。其中的 \N（其中 N=1…9）转义序列表示替换为第 N 个匹配组；\0 转义序列表示替换为匹配的文本。

备注：

• 这些外部服务错误将直接报告给用户，不会添加预处理步骤的信息；
  
• 如果勾选 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果预处理步骤失败并选择丢弃该值或设置指定值的选项，监控项 将不会变为不支持状态。

Check for not supported value

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

参数：

• scope - 选择错误处理的范围：
  any error - 任何错误；
  error matches - 仅匹配在 pattern 中指定的正则表达式的错误；
  error does not match - 仅不匹配在 pattern 中指定的正则表达式的错误
  
• pattern - 用于匹配错误的正则表达式。如果在 scope 参数中选择了 any error，则此字段不显示。如果显示，此字段为必填项。
  

备注：

• 通常情况下，如果无法检索到值，会导致 监控项 变为不支持状态。此预处理步骤允许您修改此行为。如果选中 Custom on fail 复选框（在此预处理步骤中始终选中且为灰色），则可以指定自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果选择了丢弃值或设置指定值的选项，则在预处理步骤失败的情况下，监控项 不会变为不支持状态。
• 此预处理步骤仅检查是否无法检索到 监控项 值。它不会检查例如检索到的值的类型（例如 string）是否与 监控项 的信息类型（例如数字）匹配；详细信息请参见 检查不支持的值。如果类型不匹配，在所有预处理步骤执行完毕后，监控项 仍可能变为不支持状态。要检查类型不匹配，您可以使用例如 Custom multiplier 预处理步骤；请参见 检查获取值类型。
• 在 Set value to 或 Set error to 字段中支持捕获正则表达式组。使用 \N（其中 N=1…9）来检索第 N 个匹配的组；使用 \0 来检索匹配的文本；
• 这些步骤始终作为第一个预处理步骤执行，并且在保存对 监控项 的更改后会放置在所有其他步骤之上；
• 支持多个 Check for not supported value 步骤，按指定顺序执行。any error 的步骤将自动放置在此组中的最后一步。

Discard unchanged

如果值未发生变化，则将其丢弃。

评论：

• 如果某个值被丢弃，则该值不会保存在数据库中，且Zabbix server并不知晓该值已被接收。不会评估任何触发器表达式，因此，相关触发器的问题也不会被创建或解决。函数仅基于实际保存在数据库中的数据进行运算。由于趋势数据是基于数据库中的数据生成的，如果某个小时没有保存任何值，则该小时也将没有趋势数据。
• 每个 监控项 只能指定一个限流选项。

Discard unchanged with heartbeat

如果值在定义的时间段（以秒为单位）内未发生变化，则将其丢弃。

评论：

• 支持使用正数 integer 值来指定秒数（最小值为 1 秒）；
  
• 时间后缀可以被使用（例如，30s，1m，2h，1d）;
• 可以使用用户宏和低级别自动发现宏；
• 如果某个值被丢弃，则该值不会保存在数据库中，且 Zabbix server 并不知道该值已被接收。不会评估任何触发器表达式，因此，相关触发器的问题也不会被创建或解决。函数仅根据实际保存在数据库中的数据进行工作。由于趋势是基于数据库中的数据构建的，如果某个小时没有保存任何值，则该小时也将没有趋势数据。
• 每个 监控项 只能指定一个限流选项。

Prometheus pattern

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

详细信息，请参见 Prometheus checks。

Prometheus 转 JSON

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

详细信息，请参见Prometheus checks。

宏支持

User macros 和带有上下文的用户宏支持在以下位置使用：

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

测试

参见preprocessing testing。