2 监控项值预处理

概述

预处理功能允许您在将接收到的监控项值存入数据库前对其进行转换处理。 这些转换/预处理步骤由Zabbix server或proxy执行（当监控项由proxy监控时）。

该特性支持多种应用场景，例如：

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

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

所有进入预处理流程的数值初始均被视为字符串类型。 在预处理流水线末端，将按监控项配置要求转换为目标数值类型。 但特定预处理步骤可能会根据需要触发提前类型转换。 详细技术说明请参阅Preprocessing details。

为确保预处理配置符合预期，您可以test it。

另请参阅：Preprocessing examples

配置

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

点击添加按钮选择支持的转换类型.

当至少定义一个预处理步骤时，信息类型字段会显示在选项卡底部 如需更改信息类型，可直接在预处理选项卡中操作而无需离开该界面 详细参数说明请参阅Creating an item

支持的转换

以下列出所有支持的转换类型。 点击转换名称查看其完整详情

请注意，对于变更和限流预处理步骤，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并将其替换为另一个（或空值）。

参数：

• search string - 要查找并替换的string，区分大小写（必填）；
  
• replacement - 用于替换搜索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;
  
• 不支持命名空间;
  
• 如果勾选失败时自定义复选框, 可以指定自定义错误处理选项: 丢弃该值, 设置指定值, 或设置指定的错误消息. 如果预处理步骤失败, 当选择丢弃值或设置指定值的选项时, 监控项 不会变为不支持状态.

示例:

number(/document/item/value) #will extract '10' from <document><item><value>10</value></item></document>
number(/document/item/@attribute) #will extract '10' from <document><item attribute="10"></item></document>
/document/item #will extract '<item><value>10</value></item>' from <document><item><value>10</value></item></document>

JSON Path

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

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

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（其中' '被替换为':'）；
  
• 从BITS转为integer - 将表示为十六进制字符序列的比特string的前8个字节（例如"1A 2B 3C 4D"）转换为64位无符号integer。 对于超过8字节的比特串，后续字节将被忽略。

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

SNMP walk to JSON

将SNMP值转换为JSON格式

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

注释说明:

• 提供与SNMP遍历值步骤类似的值格式化选项;
  
• 此预处理步骤可用于SNMP OID discovery;
  
• 若勾选自定义失败处理复选框，可指定自定义错误处理选项：选择丢弃该值、设置指定值或设置指定的错误消息 当预处理步骤失败时，若选择丢弃值或设置指定值的选项，监控项不会变为不受支持状态

SNMP get value

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

• 从十六进制string转为UTF-8 - 将十六进制string转换为UTF-8 string;
  
• 从十六进制string转为MAC地址 - 验证十六进制string作为MAC地址并返回标准MAC地址string（其中' '被替换为':'）;
  
• 从BITS转为integer - 将表示为十六进制字符序列的比特string的前8个字节（例如"1A 2B 3C 4D"）转换为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'字段长度导致整个值丢失，实际上建议使用数值型（无符号）以仅截断小数部分。
  
• 计算公式为(当前值-前次值)/(当前时间戳-前次时间戳)，其中当前值-最新采集值；前次值-上一次接收值；当前时间戳-最新时间戳；前次时间戳-前次值的时间戳；
  
• 每个监控项仅允许执行一种变更操作（"简单变更"或"每秒变更"）；
• 若当前值小于前次值，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

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

若勾选Custom on fail复选框，可指定自定义错误处理选项：可选择丢弃该值、设置指定值或设置指定错误消息. 当预处理步骤失败时，若选择丢弃值或设置指定值的选项，监控项将不会变为不受支持状态.

Hexadecimal to decimal

将十六进制格式的值转换为十进制

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

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

检查位于JSON路径的应用程序级错误消息 如果处理成功且消息不为空则停止处理. 否则继续使用该预处理步骤之前的值进行处理

注释:

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

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代码
• 自定义错误处理参数（设置值为和设置错误为字段）

测试

参见preprocessing testing。