2 监控项值预处理

概述

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

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

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

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

如果某个预处理步骤失败，监控项将变为不支持状态。 这可以通过 Custom on fail 错误处理来避免（大多数转换都支持此功能），它允许您丢弃值或设置自定义值。

对于日志监控项，日志元数据（不含值）将始终重置监控项的不支持状态，使其重新变为受支持状态。 即使初始错误是在从 agent 接收到日志值之后发生的，也会如此。

传递给预处理的所有值最初都会被视为字符串。 在预处理流水线结束时，系统会将其转换为所需的值类型（如监控项配置中所定义）。 但是，如果需要，某些特定的预处理步骤可能会更早触发转换。 有关详细技术信息，请参见预处理详细信息。

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

另请参见：预处理示例

配置

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

单击 添加 以选择受支持的转换方式。

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

支持的转换

以下列出了所有支持的转换。 单击转换名称可查看其完整详细信息。

名称 描述 类型
正则表达式 将值与正则表达式进行匹配，并替换为所需的输出。 文本
替换 查找搜索字符串并将其替换为另一个字符串（或替换为空）。
去除首尾字符 从值的开头和结尾移除指定字符。
去除右侧字符 从值的末尾移除指定字符。
去除左侧字符 从值的开头移除指定字符。
XML XPath 使用 XPath 功能从 XML 数据中提取值或片段。 结构化数据
JSON Path 使用 JSONPath functionality 从 JSON 数据中提取值或片段。
CSV 转 JSON 将 CSV 文件数据转换为 JSON 格式。
XML 转 JSON 将 XML 格式的数据转换为 JSON。
SNMP walk 值 按指定的 OID/MIB 名称提取值并应用格式化选项。 SNMP
SNMP walk 转 JSON 将 SNMP 值转换为 JSON。
SNMP get 值 对 SNMP get 值应用格式化选项。
自定义乘数 将值乘以指定的整数或浮点数。 算术
简单变化 计算当前值与前一个值之间的差值。 变化
每秒变化 计算值每秒的变化速度（当前值与前一个值之间的差值）。
布尔值转十进制 将值从布尔格式转换为十进制。 数字系统
八进制转十进制 将值从八进制格式转换为十进制。
十六进制转十进制 将值从十六进制格式转换为十进制。
JavaScript 输入 JavaScript 代码。 自定义脚本
在范围内 定义值应处于的范围。 验证
匹配正则表达式 指定值必须匹配的正则表达式。
不匹配正则表达式 指定值不得匹配的正则表达式。
检查 JSON 中的错误 检查位于 JSONPath 的应用级错误消息。
检查 XML 中的错误 检查位于 XPath 的应用级错误消息。
使用正则表达式检查错误 使用正则表达式检查应用级错误消息。
检查不支持的值 检查是否无法检索到任何监控项值。
丢弃未更改的值 如果值未发生变化，则丢弃该值。 限流
带心跳的丢弃未更改值 如果值在定义的时间段内未发生变化，则丢弃该值。
Prometheus 模式 使用以下查询从 Prometheus 指标中提取所需数据。 Prometheus
Prometheus 转 JSON 将所需的 Prometheus 指标转换为 JSON。

请注意，对于 变化 和 限流 预处理步骤，Zabbix 必须记住上一个值，才能按要求计算/比较新值。 这些先前的值由预处理管理器处理。 如果 Zabbix 服务器 或 proxy 被重启，或者对预处理步骤进行了任何更改，则相应监控项的上一个值会被重置，从而导致：

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

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

参数：

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

说明：

  • 如果输入值匹配失败，则该监控项将变为不支持；
  • 该正则表达式支持通过 \N 序列提取最多 10 个捕获组；
  • 如果勾选 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值，或设置指定错误消息。 如果预处理步骤失败，在选择丢弃该值或设置指定值选项的情况下，该监控项不会变为不支持。
  • 一些现有示例请参见 正则表达式 部分。
替换

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

参数：

  • 搜索字符串 - 要查找并替换的字符串，区分大小写（必填）；
  • 替换内容 - 用于替换搜索字符串的字符串。
    替换字符串也可以为空，这样在找到搜索字符串时实际上可将其删除。

说明：

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

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

右截取

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

左截取

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

XML XPath

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

说明：

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

示例：

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 数据中提取值或片段。

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

CSV to JSON

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

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

XML 转 JSON

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

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

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

SNMP walk 值

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

  • Unchanged - 将十六进制字符串作为未转义的十六进制字符串返回（注意，仍会应用显示提示）；
  • UTF-8 from hex-STRING - 将十六进制字符串转换为 UTF-8 字符串；
  • MAC from hex-STRING - 将十六进制字符串校验为 MAC 地址，并返回正确格式的 MAC 地址字符串（其中用 ':' 替换 ' '）；
  • Integer from BITS - 将以十六进制字符序列表示的位字符串的前 8 个字节（例如 "1A 2B 3C 4D"）转换为 64 位无符号整数。 对于长度超过 8 字节的位字符串，后续字节将被忽略。

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

SNMP walk 转换为 JSON

将 SNMP 值转换为 JSON。

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

说明：

  • 提供与 SNMP walk 值 步骤类似的值格式化选项；
  • 您可以将此预处理步骤用于 SNMP OID 发现；
  • 如果勾选 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值，或设置指定的错误消息。 如果预处理步骤失败，在选择丢弃该值或设置指定值选项的情况下，监控项不会变为不支持。
SNMP 获取值

将格式化选项应用于 SNMP 获取值：

  • UTF-8 from Hex-STRING - 将十六进制字符串转换为 UTF-8 字符串；
  • MAC from Hex-STRING - 将十六进制字符串校验为 MAC 地址，并返回正确的 MAC 地址字符串（其中用 ':' 替换 ' '）；
  • Integer from BITS - 将表示为十六进制字符序列的位字符串的前 8 个字节（例如 "1A 2B 3C 4D"）转换为 64 位无符号整数。 对于长度超过 8 个字节的位字符串，后续字节将被忽略。

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

自定义乘数

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

说明：

  • 使用此选项可将以 KB、MBps 等单位接收的值转换为 B、Bps。 否则，Zabbix 将无法正确设置prefixes（K、M、G 等）。
  • 请注意，如果监控项的信息类型为 Numeric (unsigned)，则带有小数部分的传入值会在应用自定义乘数之前被截断（即“0.9”会变为“0”）；
  • 如果对于信息类型设置为 Numeric (unsigned) 的监控项使用了自定义乘数，或将“存储值”设为 Change per second，并且最终计算值实际上是浮点数，则该计算值仍会被视为正确值接受，但会截去小数部分并以整数形式存储；
  • 支持：科学计数法，例如 1e+70；用户宏和 LLD 宏；包含宏的字符串，例如 {#MACRO}e+10、{$MACRO1}e+{$MACRO2}。 这些宏必须解析为整数或浮点数。
  • 如果勾选 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值，或设置指定的错误消息。 如果预处理步骤失败，在选择丢弃该值或设置指定值的情况下，监控项不会变为不支持。
简单变化

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

说明：

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

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

说明：

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

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

说明：

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

十六进制转十进制

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

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

JavaScript

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

请勿在预处理 JavaScript 中使用未声明的赋值。 请使用 var 声明局部变量。

注释：

范围内

通过指定最小值/最大值（包含边界）来定义一个值应处于的范围。

说明：

  • 接受数值（包括任意位数、可选的小数部分和可选的指数部分、负值）；
  • 最小值应小于最大值；
  • 至少必须存在一个值；
  • 可以使用用户宏和低级别发现宏；
  • 如果勾选 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值，或设置指定的错误消息。

如果预处理步骤失败，在选择丢弃该值或设置指定值选项的情况下，监控项不会变为不支持。

匹配正则表达式

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

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

不匹配正则表达式

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

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

检查 JSON 中的错误

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

说明：

  • 这些外部服务错误会按原样报告给用户，不会附加预处理步骤信息；
  • 如果因 JSON 无效而解析失败，则不会报告错误；
  • 如果勾选 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值，或设置指定的错误消息。

如果预处理步骤失败，且选择了丢弃该值或设置指定值选项，则监控项不会变为不支持。

检查 XML 中的错误

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

说明：

  • 这些外部服务错误会按原样报告给用户，不会添加预处理步骤信息；
  • 如果因 XML 无效而解析失败，不会报告错误；
  • 如果勾选 Custom on fail 复选框，则可以指定自定义错误处理选项：丢弃该值、设置指定值，或设置指定错误消息。
    如果预处理步骤失败，且选择了丢弃该值或设置指定值选项，则监控项不会变为不支持。
使用正则表达式检查错误

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

参数：

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

说明：

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

检查是否无法获取任何监控项值。
根据对返回错误消息的检查结果，指定应如何处理该失败。

参数：

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

说明：

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

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

说明：

  • 如果某个值被丢弃，则不会将其保存到数据库中，Zabbix 服务器也不会知道已接收到该值。
    不会对任何触发器表达式进行求值，因此也不会为相关触发器创建/恢复任何问题。
    函数将仅基于实际保存到数据库中的数据运行。
    由于趋势数据是基于数据库中的数据构建的，如果某一小时没有保存任何值，则该小时也不会有趋势数据。
  • 每个监控项只能指定一个限流选项。
使用心跳丢弃未变化的值

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

说明：

  • 支持使用正整数值来指定秒数（最小为 1 秒）；
  • 可以使用时间后缀（例如 30s、1m、2h、1d）；
  • 可以使用用户宏和低级别发现宏；
  • 如果某个值被丢弃，则不会保存到数据库中，Zabbix 服务器也不会知道已接收到该值。 不会对任何触发器表达式进行求值，因此也不会为相关触发器创建/恢复问题。 函数将仅基于实际保存到数据库中的数据运行。 由于趋势数据是基于数据库中的数据构建的，如果某一小时内没有保存任何值，则该小时也不会有趋势数据。
  • 每个监控项只能指定一个限流选项。
Prometheus 模式

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

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

Prometheus 转 JSON

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

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

宏支持

用户宏 和带上下文的用户宏支持用于：

  • 预处理步骤参数，包括 JavaScript 代码；
  • 自定义错误处理参数（设置值为 和 设置错误为 字段）。

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

测试

参见预处理测试。