2 监控项值预处理
概述
预处理功能允许为接收到的监控项值定义转换规则。在存入数据库前可执行一个或多个转换操作。
转换操作按照定义顺序依次执行。预处理由Zabbix server或proxy完成（当监控项由proxy监控时）。
请注意传递给预处理的所有值均为string类型，最终在预处理流水线末端会转换为目标值类型（根据监控项配置定义）；但若预处理步骤需要，也可能在过程中进行类型转换。更多技术细节请参阅preprocessing details。
另请参阅：Usage examples
配置
预处理规则在监控项的预处理选项卡中定义 配置 表单
一个监控项将变为 不支持的监控项 如果其中任何 预处理步骤失败，除非启用了Custom on fail错误处理（适用于支持的转换） 配置为丢弃该值或设置为指定值。 （注：用户未提供具体待翻译内容，根据角色定义，助手需等待用户输入Zabbix技术文档内容后进行专业翻译。若需示例，可提供具体段落测试翻译效果。） 对于日志监控项，日志元数据（不含值）将始终重置监控项 不支持的状态并使监控项重新获得支持，即使初始 从agent接收到日志值后发生错误
User macros 和用户宏 在监控项值预处理参数中支持上下文 JavaScript代码
宏替换为其值时忽略上下文。 宏值按原样插入代码中，无法添加 在将值放入JavaScript代码之前进行额外的转义处理。 请注意，这可能导致某些情况下出现JavaScript错误。
| 类型 | ||
|---|---|---|
| 转换 | 描述 | |
| Text | ||
| 正则表达式 | 将值与<pattern>正则表达式匹配，并用<output>替换值。该正则表达式支持使用\N序列提取最多10个捕获组。若未能匹配输入值，将导致监控项变为不支持状态。 参数: pattern - 正则表达式 output - 输出格式化模板。\N（N=1…9）转义序列会被替换为第N个匹配组，\0转义序列会被替换为匹配的文本。 请参阅示例章节查看现有示例。 若勾选失败时自定义复选框，可选择自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。若预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项不会变为不支持状态。 |
|
| 替换 | 查找搜索string并将其替换为另一个（或空值）。所有出现的搜索string都将被替换。 参数: 搜索string - 要查找并替换的string，区分大小写（必需） 替换值 - 用于替换搜索string的string。替换string也可以为空，从而在找到搜索string时允许delete。 可以使用转义序列来搜索或替换换行符、回车符、制表符和空格"\n \r \t \s"；反斜杠可以转义为"\\"，转义序列可以转义为"\\n"。在低级发现期间会自动对换行符、回车符、制表符进行转义处理。 |
|
| Trim | 从值的开头和结尾移除指定字符。 | |
| 右修剪 | 从值的末尾移除指定字符。 | |
| 左修剪 | 从值的开头移除指定字符。 | |
| Structured data | ||
| XML XPath | 使用XPath功能从XML数据中提取值或片段。 要使此选项生效，Zabbix server必须编译支持libxml。 示例： number(/document/item/value)将从<document><item><value>10</value></item></document>中提取10number(/document/item/@attribute)将从<document><item attribute="10"></item></document>中提取10/document/item将从<document><item><value>10</value></item></document>中提取<item><value>10</value></item>注意不支持命名空间。 如果勾选Custom on fail复选框，可以选择自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。如果预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项不会变为不受支持状态。 |
|
| JSON Path | 使用JSONPath functionality从JSON数据中提取值或片段。 如果勾选Custom on fail复选框，可以选择自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。若预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项不会变为不受支持状态。 |
|
| CSV转JSON | 将CSV file数据转换为JSON格式。 更多信息请参阅：5-csv-到-json-预处理。 |
|
| XML 转 JSON | 将 XML 格式的数据转换为 JSON。 更多信息请参阅：序列化规则。 若勾选失败时自定义复选框，可选择自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。若预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项 不会变为不受支持状态。 |
|
| Arithmetic | ||
| 自定义乘数 | 将数值乘以指定的integer或浮点值。 此选项用于将接收到的KB、MBps等单位转换为B、Bps。否则Zabbix无法正确设置prefixes（K、M、G等）。 注意：若监控项的信息类型为无符号数值，则在应用自定义乘数前，带有小数部分的输入值将被截断（例如'0.9'会变为'0'）。 支持：科学计数法（如 1e+70，自version 2.2起）；用户宏和LLD宏（自version 4.0起）；包含宏的字符串（如{#MACRO}e+10、{$MACRO1}e+{$MACRO2}，自version 5.2.3起）宏必须解析为integer或浮点数。 若勾选失败时自定义复选框，可选择自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。若预处理步骤失败，当选择丢弃值或设置指定值时，监控项不会变为"不支持"状态。 |
|
| Change | ||
| 简单变化 | 计算当前值与先前值之间的差值。 计算公式为value-prev_value，其中 value - 当前值；prev_value - 先前接收到的值 此设置可用于测量持续增长的值。如果当前值小于先前值，Zabbix将丢弃该差值（不存储任何内容）并等待下一个值。 每个监控项仅允许一个变化操作。 如果勾选失败时自定义复选框，可以选择自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。如果预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项不会变为不受支持状态。 |
|
| 每秒变化率 | 计算每秒数值变化速度（当前值与前一值的差值）。 计算公式为 (当前值-前一值)/(当前时间戳-前一值时间戳)，其中 当前值 - 最新采集值；前一值 - 上次接收值；当前时间戳 - 最新时间戳；前一值时间戳 - 上次采集时间戳。 该设置适用于计算持续增长数值的每秒变化速率。若当前值小于前一值，Zabbix将丢弃该差值（不存储）并等待新值。此机制可正确处理例如32位SNMP计数器回绕（溢出）的情况。 注意：由于计算结果可能产生浮点数，建议将"信息类型"设为数值（浮点型）(float)，即使原始输入值为整数。这对小数部分有重要意义的小数值尤为重要。若浮点数值过大可能超出'float'字段长度导致整个值丢失，则建议使用数值（无符号型）以仅截断小数部分。 每个监控项仅允许执行一次变化率运算。 若勾选失败时自定义复选框，可选择自定义错误处理方式：丢弃该值、设为指定值或设置错误信息。当预处理步骤失败时，若选择丢弃值或设为指定值的选项，监控项不会变为"不支持"状态。 |
|
| Numeral systems | ||
| boolean转十进制 | 将值从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 scripts | ||
| JavaScript | 在点击参数字段或铅笔图标时出现的代码块中输入JavaScript代码。 注意可用JavaScript长度取决于自定义脚本限制。 更多信息请参阅: Javascript preprocessing。 |
|
| Validation | ||
| 范围内 | 通过指定最小/最大值（包含边界值）来定义一个数值应处的范围。 可接受数值类型（包括任意位数、可选小数部分及可选指数部分，支持负值）。可使用用户宏和低级发现宏。最小值应小于最大值。 必须至少存在一个有效值。 若勾选失败时自定义复选框，可选择自定义错误处理方式：丢弃该值、设置为指定值或设置指定错误消息。当预处理步骤失败时，若选择丢弃值或设置为指定值的选项，则监控项不会变为"不受支持"状态。 |
|
| 匹配正则表达式 | 指定一个值必须匹配的正则表达式。 如果勾选失败时自定义复选框，可以选择自定义错误处理选项：要么丢弃该值，设置指定值，或设置指定的错误消息。如果预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项不会变为不受支持状态。 |
|
| 不匹配正则表达式 | 指定一个值必须不匹配的正则表达式。 如果勾选自定义失败处理复选框，可以选择自定义错误处理选项：丢弃该值、设置指定值或设置指定的错误消息。如果预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项不会变为不受支持状态。 |
|
| 检查JSON中的错误 | 检查位于JSON路径的应用级错误消息。若成功且消息非空则停止处理；否则继续使用预处理步骤前的值进行处理。注意这些外部服务错误将按原样报告给用户，不添加预处理步骤信息。 解析无效JSON时失败不会报告错误。 若勾选自定义失败处理复选框，可选择自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。若预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项不会变为不受支持状态。 |
|
| 检查XML中的错误 | 检查位于XPath路径的应用级错误消息。如果成功且消息非空则停止处理；否则继续使用预处理步骤前的值进行处理。请注意，这些外部服务错误将按原样报告给用户，不会添加预处理步骤信息。 解析无效XML时若失败不会报告错误。 如果勾选自定义失败处理复选框，可选择自定义错误处理选项：丢弃该值、设置指定值或设置指定错误消息。若预处理步骤失败，当选择丢弃值或设置指定值的选项时，监控项不会变为不受支持状态。 |
|
| 使用正则表达式检查错误 | 通过正则表达式检查应用层错误消息。若匹配成功且消息非空则停止处理；否则继续使用预处理前的值进行后续处理。请注意这些外部服务错误将直接原样反馈给用户，不会添加预处理步骤信息。 参数: pattern - 正则表达式 output - 输出格式化模板。转义序列\N（N=1…9）会被替换为第N个匹配组，\0则替换为匹配的文本。 若勾选失败时自定义复选框，可选择自定义错误处理方式：丢弃该值、设定指定值或设置特定错误消息。当预处理步骤失败时，若选择丢弃值或设定指定值的选项，监控项不会变为"不受支持"状态。 |
|
| 检查不支持的数值 | 检查是否无法获取监控项数值。通常这会导致监控项变为不支持状态，但您可以通过指定失败时自定义错误处理选项来修改该行为：丢弃数值、设置指定数值（也可用于触发器）或设置指定错误消息。若预处理步骤失败，当选择丢弃数值或设置指定数值选项时，监控项不会变为不支持状态。请注意，此预处理步骤中失败时自定义复选框呈灰色且始终被勾选。 本预处理步骤仅检查是否无法获取监控项数值。例如，它不会检查获取的数值类型（如string）是否与监控项的信息类型（如数值型）匹配；详情参见检查不支持的值。若存在类型不匹配，在所有预处理步骤执行完毕后，监控项仍可能变为不支持状态。要检查类型不匹配，您可使用例如自定义乘数预处理步骤；参见检查获取值类型。 此步骤始终作为首个预处理步骤执行，并在保存对监控项的更改后置于所有其他步骤之上。该步骤仅能使用一次。 自5.2.0版本起支持。 |
|
| Throttling | ||
| 丢弃未变更值 | 若数值未发生变化则丢弃该值. 若数值被丢弃, 则不会存入数据库且Zabbix server不会感知到该值的接收. 由于不会评估触发器表达式, 相关触发器将不会产生/解决问题. 函数运算仅基于实际存入数据库的数据执行. 由于趋势数据基于数据库中的值生成, 若某小时未存储数值则该时段也不会产生趋势数据. 每个监控项仅能指定一种抑制选项. 需注意当Zabbix proxy监控的监控项数值差异极小(小于0.000001)时, proxy可能无法正确执行丢弃操作, 这些值会作为相同值存入历史记录, 除非Zabbix server数据库已upgraded. |
|
| 心跳周期内丢弃未变更值 | 若数值在定义的时间段（以秒计）内未发生变化，则丢弃该值。 支持正integer值来指定秒数（最小值为1秒）。此字段可使用时间后缀（如30s、1m、2h、1d），并支持用户宏和低级发现宏。 若数值被丢弃，则不会存入数据库，且Zabbix server不会感知到该值的接收。由于不会评估触发器表达式，因此不会创建/解决相关触发器的问题。函数仅基于实际存入数据库的数据运行。由于趋势数据基于数据库中的记录生成，若某小时无数据存入，则该小时也无趋势数据。 每个监控项仅能指定一种节流选项。 注意：当Zabbix proxy监控的监控项数值差异极小（小于0.000001）时，proxy可能无法正确执行丢弃操作，这些值会作为相同值存入历史记录，除非Zabbix server数据库upgraded。 |
|
| Prometheus | ||
| Prometheus模式 | 使用以下query从Prometheus指标中提取所需数据。 更多详情请参阅Prometheus checks。 |
|
| Prometheus转JSON | 将所需的Prometheus指标转换为JSON格式。 详见Prometheus checks获取更多细节。 |
|
针对变更和节流预处理步骤 Zabbix需要记住上一个值以计算/比较新值 根据需要。这些先前的值由预处理步骤处理 如果Zabbix server或proxy重启或发生任何变更 在预处理步骤中，对应监控项的最后一个值被 重置，导致：
对于简单变更、每秒变更步骤 - 下一个值将 由于没有可用于计算变化的前值而被忽略 来自;
对于Discard unchanged（丢弃未变更项）和Discard unchanged with heartbeat（带心跳的丢弃未变更项）步骤 -
the next value will never be discarded, even if it should have been because of discarding rules.
监控项的信息类型参数显示在 当至少定义一个预处理步骤时显示该选项卡。如果需要，可以 可以在不离开的情况下更改信息类型 预处理选项卡。参见Creating an item 有关详细参数说明。
如果您使用自定义乘数或将值存储为Change 每秒，适用于信息类型设置为数值的监控项 (无符号)* 且最终计算得到的值实际上是一个float 数字，计算得出的值仍会被视为正确值 截取小数部分并将值存储为 integer
测试
测试预处理步骤有助于确保复杂的预处理流程能产生预期结果，而无需等待接收并预处理监控项值。
可进行以下测试：
- 针对假设值
- 针对来自一个主机的实际值
每个预处理步骤均可单独测试，也可测试所有步骤组合。当您在操作区块中点击测试或测试所有步骤按钮时，将弹出测试窗口。
测试假设值
| 参数 | 描述 |
|---|---|
| Get value from host | 如需测试假设值，请勿勾选此复选框。 另见：测试实际值。 |
| Value | 输入要测试的输入值。 点击参数字段或查看/编辑按钮将打开文本区域窗口用于输入值或代码块。 |
| Not supported | 勾选此复选框以测试不支持的值。 此选项可用于测试检查不支持的值预处理步骤。 |
| Time | 显示输入值的时间：now（只读）。 |
| Previous value | 输入用于比较的上一个输入值。 仅适用于变更和节流预处理步骤。 |
| Previous time | 输入用于比较的上一个输入值时间。 仅适用于变更和节流预处理步骤。 默认值基于监控项的'更新间隔'字段值（若为'1m'，则此字段填充为 now-1m）。若未指定或用户无权访问主机，则默认为now-30s。 |
| Macros | 若使用宏，将列出宏及其值。测试时可编辑这些值，但更改仅保存在测试上下文中。 |
| End of line sequence | 为多行输入值选择行尾序列： LF - LF（换行）序列 CRLF - CRLF（回车换行）序列。 |
| Preprocessing steps | 列出预处理步骤；点击测试按钮后显示每个步骤的测试结果。 自Zabbix 6.0.31起，发送至前端的测试结果最大截断为512KB。若结果被截断，将显示警告图标。鼠标悬停时显示警告描述。注意超过512KB的数据仍会被Zabbix server完整处理。 若测试步骤失败，将显示错误图标。鼠标悬停时显示错误描述。 若为步骤指定"自定义失败处理"且执行该操作，预处理测试步骤行下方将新增一行，显示执行的操作及其结果（错误或值）。 |
| Result | 当所有步骤一起测试时（点击测试所有步骤按钮），始终显示预处理步骤的最终结果。 同时显示转换为监控项值类型的类型，例如 Result converted to Numeric (unsigned)。自Zabbix 6.0.31起，发送至前端的测试结果最大截断为512KB。若结果被截断，将显示警告图标。鼠标悬停时显示警告描述。注意超过512KB的数据仍会被Zabbix server完整处理。 |
点击测试查看每个预处理步骤后的结果。
测试值会在测试会话间保存（无论是单个步骤还是所有步骤），允许用户更改预处理步骤或监控项配置后返回测试窗口而无需重新输入信息。但页面刷新后值会丢失。
测试由Zabbix server执行。前端向服务器发送对应请求并等待结果。请求包含输入值和预处理步骤（含展开的用户宏）。对于变更和节流步骤，可指定可选的上一个值和时间。服务器返回每个预处理步骤的结果。
所有技术错误或输入验证错误将显示在测试窗口Top的错误框中。
测试实际值
针对实际值测试预处理:
- 勾选从主机获取值复选框
- 输入或验证主机参数(主机地址、端口、proxy名称/无 proxy)及监控项特定细节(如SNMPv2团体名或SNMPv3 安全凭证)。这些字段具有上下文感知能力:
- 可能的情况下会预填充值，例如对于需要agent的 监控项，会从所选主机的agent接口获取信息
- 模板监控项需要手动填写值
- 纯文本宏值会被解析
- 包含机密或Vault宏的字段(或部分值)为空且需要手动输入。如果 任何监控项参数包含机密宏值，将显示以下警告信息: "监控项包含具有机密值的用户定义宏。这些宏的值需要手动输入。"
- 在监控项类型上下文中不需要的字段会被禁用(例如 计算型监控项会禁用主机地址和proxy字段)
- 点击获取值并测试进行预处理测试
如果在监控项配置表单中指定了值映射 ('显示值'字段)，监控项测试对话框将在最终结果后显示另一行， 名为'应用值映射后的结果'。
从一个主机获取实际值特有的参数:
| 参数 | 描述 |
|---|---|
| Get value from host | 勾选此复选框以get从主机获取实际值。 |
| Host address | 输入主机地址。 此字段会自动填充为监控项主机接口的地址。 |
| Port | 输入主机端口。 此字段会自动填充为监控项主机接口的端口。 |
| Additional fields for SNMP interfaces (SNMP version, SNMP community, Context name, etc) |
有关配置SNMP接口(v1、v2和v3)的更多详情，请参阅配置-snmp-监控。 这些字段会自动从监控项主机接口填充。 |
| Proxy | 如果主机由proxy监控，请指定proxy。 此字段会自动填充为主机的proxy(如果有)。 |
其余参数请参阅上文的测试假设值部分。