4 历史函数

此处列出的所有函数均支持用于：

• 触发器表达式
• 计算型监控项
• 表达式宏

以下仅列出函数，不含附加信息。
点击函数可查看完整详情。

通用参数

• /host/key 是引用主机监控项历史记录的函数中常见的必填第一个参数
• (sec|#num)<:time shift> 是引用主机监控项历史记录的函数中常见的第二个参数，其中：
  • sec - 以秒为单位的最大评估周期（可使用时间后缀），或
  • #num - 最新采集值中的最大评估范围（如果前面带有井号）
  • time shift（可选）允许将评估点回移到过去的时间。 有关指定 time shift 的更多详细信息，请参见更多详情。

函数详情

有关函数参数的一些通用说明：

• 函数参数之间使用逗号分隔
• 可选函数参数（或参数部分）用 < > 表示
• 每个函数的特定参数会在对应函数中说明
• /host/key 和 (sec|#num)<:time shift> 参数绝不能加引号

change(/host/key)

前一个值与最新值之间的差值。
支持的值类型：Float、Integer、String、Text、Log。
对于字符串，返回值为：0 - 值相同；1 - 值不同。

参数：请参见通用参数。

说明：

• 将计算数值差值，如以下传入值示例所示（“前一个”值和“最新”值 = 差值）：
  '1' 和 '5' = +4
  '3' 和 '1' = -2
  '0' 和 '-2.5' = -2.5。
  
• 在触发器中，可用于捕获突发峰值（或下降）、计数器重置、数值状态转换。
  
• 另请参见：abs 以进行比较。

示例：

change(/host/system.uptime)<0 #system uptime change has been negative since the last value (indicating a reboot)
change(/host/system.cpu.load[all,avg1])>2 #CPU load (for one minute) has jumped by more than 2 since the last value
change(/host/vfs.fs.size[/,free])<-1G #free disk space has dropped by more than 1 GB between checks

changecount(/host/key,(sec|#num)<:time shift>,<mode>)

在定义的评估周期内，相邻值之间发生变化的次数。
支持的值类型：Float、Integer、String、Text、Log。

参数：

• 参见通用参数
  
• mode（必须用双引号括起来）- 可选值：all - 统计所有变化（默认）；dec - 统计减少次数；inc - 统计增加次数

注释：

• 对于非数值类型，mode 参数将被忽略。
  
• 在触发器中，可用于捕获频繁的状态变化（表明系统不稳定）。

示例：

changecount(/host/icmpping,10m)>5 #10 分钟内 ping 状态变化超过 5 次
changecount(/host/vfs.file.contents["/sys/class/net/eth0/operstate"],1h)>5 #1 小时内 eth0 的运行状态变化超过 5 次
changecount(/host/proc.num[httpd],15m)>10 #15 分钟内 httpd 进程数量变化超过 10 次
changecount(/host/key,#10,"inc") #最近 10 个值中，值增加（相对于相邻值）的次数
changecount(/host/key,24h,"dec") #截至当前，最近 24 小时内值减少（相对于相邻值）的次数

count(/host/key,(sec|#num)<:time shift>,<operator>,<pattern>)

定义的评估周期内的值数量。
支持的值类型：Float、Integer、String、Text、Log。

参数：

• 参见通用参数
  
• operator（必须用双引号括起来） 支持的 operators：
  eq - 等于（integer、float 的默认值）
  ne - 不等于
  gt - 大于
  ge - 大于或等于
  lt - 小于
  le - 小于或等于
  like（string、text、log 的默认值）- 包含 pattern 时匹配（区分大小写）
  bitand - 按位与
  regexp - 匹配 pattern 中给定的正则表达式（区分大小写）
  iregexp - 匹配 pattern 中给定的正则表达式（不区分大小写）
  
• pattern - 所需的模式（字符串参数必须用双引号括起来）

说明：

• Float 监控项按 2.22e-16 的精度进行匹配。
• 对于 integer 值，不支持使用 like 作为 operator。
• 对于 float 值，不支持使用 like 和 bitand 作为 operator。
• 对于 string、text 和 log 值，仅支持 eq、ne、like、regexp 和 iregexp operator。
• 当使用 bitand 作为 operator 时，第 4 个 pattern 参数可指定为两个数字，并用 '/' 分隔：number_to_compare_with/mask。 count() 对该值和 mask 执行“按位与”计算，并将结果与 number_to_compare_with 进行比较。 如果“按位与”的结果等于 number_to_compare_with，则对该值进行计数。
  如果 number_to_compare_with 和 mask 相等，则只需指定 mask（不带 '/'）。
• 当使用 regexp 或 iregexp 作为 operator 时，第 4 个 pattern 参数可以是普通正则表达式或全局（以 '@' 开头）正则表达式。 对于全局正则表达式，大小写敏感性继承自全局正则表达式设置。 为进行 regexp 匹配，float 值始终会以 '.' 后保留 4 位小数的形式表示。 另请注意，对于大数字，十进制（存储在数据库中）与二进制（由 Zabbix 服务器使用）表示之间的差异可能会影响第 4 位小数。

示例：

count(/host/icmpping,30m,,"0")>5 #30 分钟内 ping 失败超过 5 次
count(/host/key,10m,"like","error") #截至当前，最近 10 分钟内包含 'error' 的值的数量
count(/host/key,10m,,12) #截至当前，最近 10 分钟内等于 '12' 的值的数量
count(/host/key,10m,"gt",12) #截至当前，最近 10 分钟内大于 '12' 的值的数量
count(/host/key,#10,"gt",12) #截至当前，最近 10 个值中大于 '12' 的值的数量
count(/host/key,10m:now-1d,"gt",12) #从当前时间往前 24 小时到往前 24 小时零 10 分钟之间，大于 '12' 的值的数量
count(/host/key,10m,"bitand","6/7") #截至当前，最近 10 分钟内在最低 3 位中包含 '110'（二进制）的值的数量
count(/host/key,10m:now-1d) #从当前时间往前 24 小时到往前 24 小时零 10 分钟之间的值的数量

countunique(/host/key,(sec|#num)<:time shift>,<operator>,<pattern>)

定义的评估周期内唯一值的数量。
支持的值类型：Float、Integer、String、Text、Log。

参数：

• 参见通用参数
  
• operator（必须用双引号括起来）。 支持的 operators：
  eq - 等于（integer、float 的默认值）
  ne - 不等于
  gt - 大于
  ge - 大于或等于
  lt - 小于
  le - 小于或等于
  like（string、text、log 的默认值）- 如果包含模式则匹配（区分大小写）
  bitand - 按位与
  regexp - 匹配 pattern 中给定的正则表达式（区分大小写）
  iregexp - 匹配 pattern 中给定的正则表达式（不区分大小写）
  
• pattern - 所需的模式（字符串参数必须用双引号括起来）

注释：

• Float 类型的监控项以 2.22e-16 的精度进行匹配。
• like 不支持作为 integer 值的操作符。
• like 和 bitand 不支持作为 float 值的操作符。
• 对于 string、text 和 log 值，仅支持 eq、ne、like、regexp 和 iregexp 操作符。
• 当使用 bitand 作为操作符时，第四个 pattern 参数可以指定为两个数字，并用 '/' 分隔：number_to_compare_with/mask。countunique() 会对该值和 mask 执行“按位与”计算，并将结果与 number_to_compare_with 进行比较。 如果“按位与”的结果等于 number_to_compare_with，则对该值进行计数。
  如果 number_to_compare_with 和 mask 相等，则只需指定 mask（不带 '/'）。
• 当使用 regexp 或 iregexp 作为操作符时，第四个 pattern 参数可以是普通正则表达式或全局（以 '@' 开头）正则表达式。 对于全局正则表达式，大小写敏感性继承自全局正则表达式设置。 为了进行正则表达式匹配，float 值始终会表示为小数点后 4 位。 另请注意，对于大数字，十进制（存储在数据库中）和二进制（由 Zabbix 服务器使用）表示形式之间的差异可能会影响第 4 位小数。

示例：

countunique(/host/key,10m) #截至当前，最近 10 分钟内唯一值的数量
countunique(/host/key,10m,"like","error") #截至当前，最近 10 分钟内包含 'error' 的唯一值数量
countunique(/host/key,10m,,12) #截至当前，最近 10 分钟内等于 '12' 的唯一值数量
countunique(/host/key,10m,"gt",12) #截至当前，最近 10 分钟内大于 '12' 的唯一值数量
countunique(/host/key,#10,"gt",12) #截至当前，最近 10 个值中大于 '12' 的唯一值数量
countunique(/host/key,10m:now-1d,"gt",12) #从当前时间往前 24 小时到 24 小时前再往后 10 分钟这一时间段内，大于 '12' 的唯一值数量
countunique(/host/key,10m,"bitand","6/7") #截至当前，最近 10 分钟内在最低 3 位有效位中具有 '110'（二进制）的唯一值数量
countunique(/host/key,10m:now-1d) #从当前时间往前 24 小时到 24 小时前再往后 10 分钟这一时间段内唯一值的数量

find(/host/key,(sec|#num)<:time shift>,<operator>,<pattern>)

在定义的求值周期内查找匹配的值。
支持的值类型：Float、Integer、String、Text、Log。
返回值：1 - 找到；0 - 未找到。

参数：

• 参见通用参数
  
• sec 或 #num（可选）- 如果未指定，则默认为最新值
• operator（必须使用双引号） 支持的 operators：
  eq - 等于（integer、float 的默认值）
  ne - 不等于
  gt - 大于
  ge - 大于或等于
  lt - 小于
  le - 小于或等于
  like（string、text、log 的默认值）- 如果包含 pattern 中给定的字符串则匹配（区分大小写）
  bitand - 按位与
  regexp - 匹配 pattern 中给定的正则表达式（区分大小写）
  iregexp - 匹配 pattern 中给定的正则表达式（不区分大小写）
  
• pattern - 所需的模式（字符串参数必须使用双引号）；如果 operator 为 regexp、iregexp，则为 Perl Compatible Regular Expression (PCRE) 正则表达式

说明：

• 如果处理多个值，只要至少有一个值匹配，就返回“1”。
• 对于 integer 值，不支持将 like 用作运算符。
• 对于 float 值，不支持将 like 和 bitand 用作运算符。
• 对于 string、text 和 log 值，仅支持 eq、ne、like、regexp 和 iregexp 运算符。
• 当运算符为 regexp 或 iregexp 时，第 4 个 pattern 参数可以是普通正则表达式或全局正则表达式（以“@”开头）。 对于全局正则表达式，大小写敏感性继承自全局正则表达式设置。

示例：

find(/host/key,10m,"like","error") #在截至当前的最近 10 分钟内查找包含 'error' 的值
find(/host/agent.version,,"like","beta")=1 #Zabbix agent 为 beta 版本，必须升级
find(/host/log[/var/log/nginx/access.log],,"regexp"," 500 ")=1 #已发现内部 web 服务器错误

first(/host/key,sec<:time shift>)

定义的评估周期内的第一个（最旧的）值。
支持的值类型：Float、Integer、String、Text、Log。

参数：

• 参见通用参数

另请参见 last()。

示例：

first(/host/key,1h) #retrieve the oldest value within the last hour until now

firstclock(/host/key,sec<:time shift>)

定义的评估周期内最早值的时间戳。
支持的值类型：Float、Integer、String、Text、Log。

参数：

• 参见通用参数。

如果在给定周期内未收集到任何数据，该函数将因错误而失败。

另请参见 lastclock()。

示例：

firstclock(/host/key,1h) #获取最近一小时内最早值的时间戳
firstclock(/host/key,1h:now-24h) #获取一天前的最近一小时内最早值的时间戳

fuzzytime(/host/key,sec)

检查被动 agent 时间与 Zabbix 服务器/proxy 时间相差多少。
支持的值类型：Float、Integer。
返回值：1 - 被动监控项值（作为时间戳）与 Zabbix 服务器/proxy 时间戳（采集该值时的时钟）之间的差值小于或等于 sec 秒；0 - 否则。

参数：

• 参见通用参数。

注释：

• 通常与 'system.localtime' 监控项一起使用，以检查本地时间是否与 Zabbix 服务器的本地时间同步。 请注意，对于 Zabbix agent，'system.localtime' 必须配置为被动检查；在 Zabbix agent 2 上，它也可以配置为主动检查。
• 也可与 vfs.file.time[/path/file,modify] 键一起使用，以检查文件是否长时间未更新。
• 不建议在复杂的触发器表达式中使用此函数（涉及多个监控项时），因为这可能导致意外结果（时间差将使用最新的指标来衡量），例如在 fuzzytime(/Host/system.localtime,60s)=0 or last(/Host/trap)<>0 中。

示例：

fuzzytime(/host/system.localtime,5m)=0 #客户端本地时间与 Zabbix 服务器/proxy 时间相差超过 5 分钟
fuzzytime(/host/system.localtime,5m)=0 and nodata(/host/system.localtime,10m)=0 #客户端本地时间与 Zabbix 服务器/proxy 时间相差超过 5 分钟（同时确保该监控项未停止上报数据）

last(/host/key,<#num<:time shift>>)

最新的值。
支持的值类型：Float、Integer、String、Text、Log。

参数：

• 参见通用参数
  
• #num（可选）- 倒数第 N 个最新值

说明：

• 请注意，带井号的时间周期（#N）在这里与许多其他函数中的用法不同。
  例如：last(/host/key) 始终等同于 last(/host/key,#1)；last(/host/key,#3) 表示倒数第三个最新值（而不是最近三个值）。
• 如果在历史记录中同一秒内存在两个以上的值，Zabbix 不保证这些值的精确顺序。
• 另请参见 first()。

示例：

last(/host/key) #retrieve the last value
last(/host/key,#2) #retrieve the previous value
last(/host/key,#1)<>last(/host/key,#2) #last two values differ

lastclock(/host/key,<#num<:time shift>>)

定义的评估周期内第 N 个最近值的时间戳。
支持的值类型：Float、Integer、String、Text、Log。

参数：

• 参见通用参数；
  
• #num（可选）- 第 N 个最近值。

如果在给定周期内未收集到任何数据，或者未收集到第 N 个值，则该函数将失败并报错。

另请参见 firstclock()。

示例：

lastclock(/host/key) #获取最新值的时间戳
lastclock(/host/key,#2) #获取倒数第 2 个最新值的时间戳
now()-lastclock(/host/heartbeat.item)>300 #自心跳监控项更新以来已超过 5 分钟
lastclock(/host/system.cpu.load[all,avg1])-lastclock(/host/system.cpu.load[all,avg1],#2)>300 #最近两个值之间的更新时间间隔超过 5 分钟
((now()-lastclock(/host/system.cpu.load[all,avg1])<120 and last(/host/system.cpu.load[all,avg1])>5)) #CPU 值较高且该值是最新的（少于 2 分钟）

logeventid(/host/key,<#num<:time shift>>,<pattern>)

检查最新日志条目的事件 ID 是否匹配正则表达式。
支持的值类型：Log。
返回值：0 - 不匹配；1 - 匹配。

参数：

• 参见通用参数
  
• #num（可选）- 倒数第 N 个值
  
• pattern（可选）- 描述所需模式的正则表达式，Perl Compatible Regular Expression (PCRE) 风格（字符串参数必须用双引号括起来）

示例：

logeventid(/host/eventlog[Security],,"4625")=1 #找到 ID 匹配 "4625"（认证失败）的日志条目
logeventid(/host/eventlog[System],,"6008|41")=1 #找到 ID 匹配 "6008" 或 "41" 的日志条目

logseverity(/host/key,<#num<:time shift>>)

最后一条日志条目的日志严重性。
支持的值类型：Log。
返回值：0 - 默认严重性；N - 严重性（整数，对 Windows 事件日志很有用：1 - 信息，2 - 警告，4 - 错误，7 - 失败审核，8 - 成功审核，9 - 严重，10 - 详细）。

参数：

• 参见通用参数
  
• #num（可选）- 倒数第 N 个最新值

Zabbix 从 Windows 事件日志的 Information 字段获取日志严重性。

示例：

logseverity(/host/log[/var/log/syslog],10m)>3 #a log entry with severity above "3" found
logseverity(/host/eventlog[System],10m)=4 #a log entry with severity equaling "Error" found

logsource(/host/key,<#num<:time shift>>,<pattern>)

检查最后一条日志记录的日志源是否匹配正则表达式。
支持的值类型：Log。
返回值：0 - 不匹配；1 - 匹配。

参数：

• 参见通用参数
  
• #num（可选）- 倒数第 N 个值
  
• pattern（可选）- 描述所需模式的正则表达式，Perl Compatible Regular Expression (PCRE) 风格（字符串参数必须用双引号括起来）

通常用于 Windows 事件日志。

示例：

logsource(/host/eventlog[Application],,"MSSQLSERVER")=1 #找到源匹配 "MSSQLSERVER" 的日志记录
logsource(/host/eventlog[System],,"Service Control Manager")=1 #找到源匹配 "Service Control Manager" 的日志记录
logsource(/host/eventlog[System],,"Service Control Manager")=1 and logeventid(/host/eventlog[System],,"7031")=1 #找到源匹配 "Service Control Manager" 且事件 ID 匹配 "7031" 的日志记录

logtimestamp(/host/key,<#num<:time shift>>)

第 N 个最近的日志监控项值中的日志消息时间戳。
支持的值类型：Log。

参数：

• 参见通用参数；
  
• #num（可选）- 第 N 个最近的值。

说明：

• 时间偏移的计算基于监控项值的时钟，而不是日志消息时间戳；
• 在以下情况下，该函数会返回错误：
  • 接收到的不是日志类型的监控项；
  • 在给定时间段内未收集到数据；
  • 未收集到第 N 个值；
  • 日志消息不包含时间戳值。

示例：

logtimestamp(/host/key) #获取最新日志消息的时间戳
logtimestamp(/host/key,#2) #获取倒数第 2 条日志消息的时间戳
logtimestamp(/host/key,#3:now-1d) #获取一天前倒数第 3 条日志消息的时间戳

monodec(/host/key,(sec|#num)<:time shift>,<mode>)

检查值是否持续单调减少。
支持的值类型：整数。
返回值：1 - 如果时间段内所有元素都持续减少；0 - 否则。

参数：

• 参见通用参数
  
• mode（必须用双引号括起来）- weak（每个值都小于或等于前一个值；默认）或 strict（每个值都已减少）

示例：

monodec(/host/system.swap.size[all,free],60s) + monodec(/host2/system.swap.size[all,free],60s) + monodec(/host3/system.swap.size[all,free],60s) #计算有多少台主机的可用 swap 大小出现了减少
monodec(/host/proc.num[nginx],10m,"strict")=1 #nginx 进程数在 10 分钟内持续单调减少

monoinc(/host/key,(sec|#num)<:time shift>,<mode>)

检查值是否存在单调递增。
支持的值类型：Integer。
返回值：1 - 如果时间段内的所有元素都持续递增；0 - 否则。

参数：

• 参见通用参数
  
• mode（必须用双引号括起来）- weak（每个值都大于或等于前一个值；默认）或 strict（每个值都已增大）

示例：

monoinc(/host/system.localtime,#3,"strict")=0 #系统本地时间并未持续递增
monoinc(/host/vfs.dir.count[/mnt/data/logs],24h,"weak")=0 #如果 24 小时内文件数量停滞不变（预期应增长）则触发器

nodata(/host/key,sec,<mode>)

检查是否未收到数据。
支持的值类型：整数、浮点数、字符、文本、日志。
返回值：1 - 在定义的时间段内未收到数据；0 - 其他情况。

参数：

• 参见通用参数
  
• sec - 该时间段不能小于 30 秒，因为 history syncer 进程仅每 30 秒计算一次此函数；不允许使用 nodata(/host/key,0)
• mode - 如果设置为 strict（使用双引号），则此函数将不受 proxy 可用性影响（详见注释）

注释：

• 默认情况下，由 proxy 监控的 'nodata' 触发器会受 proxy 可用性影响——如果 proxy 变为不可用，则在连接恢复后，'nodata' 触发器不会立即触发，而是会跳过延迟期间的数据。 请注意，对于被动 proxy，如果连接恢复时间晚于 15 秒且不少于 2 秒，则会激活抑制。 对于主动 proxy，如果连接恢复时间晚于 15 秒，则会激活抑制。 要关闭对 proxy 可用性的敏感性，请使用第三个参数，例如：nodata(/host/key,5m,"strict")；在这种情况下，一旦无数据的评估周期（五分钟）过去，此函数就会立即触发。
  
• 如果在第 1 个参数指定的时间段内出现以下情况，此函数将显示错误：
  - 没有数据且 Zabbix 服务器已重启
  - 没有数据且维护已完成
  - 没有数据且监控项已添加或重新启用。
  
• 错误会显示在触发器配置中的 Info 列。
  
• 如果 Zabbix 服务器、proxy 和 agent 之间存在时间差，此函数可能无法正常工作。 另请参见：时间同步要求。

示例：

nodata(/host/agent.ping,5m)=1 #如果 5 分钟内未从 Zabbix agent 收到数据，则触发器触发

percentile(/host/key,(sec|#num)<:time shift>,percentage)

某一时间段的第 P 百分位数，其中 P（percentage）由第三个参数指定。
支持的值类型：Float、Integer。

参数：

• 参见通用参数
  
• percentage - 介于 0 和 100 之间（含）的浮点数，小数点后最多 4 位

示例：

percentile(/host/net.if.in[eth0,bytes],1h,95)>1000000 #1 小时内网络入站流量（字节/秒）的第 95 百分位数已超过阈值（例如 1 MB/s）
percentile(/host/system.cpu.util,5m,95)>80 #CPU 利用率用户态百分比的第 95 百分位数已超过 80
percentile(/host/icmppingsec[192.168.0.2],15m,95)>0.15 #大多数延迟测量值低于 150 ms，但较高端的尾部（最高 5%）表明存在规律性延迟
percentile(/host/net.if.in[eth0,bytes],1h,50) #计算 1 小时内入站网络流量的第 50 百分位数（中位数）；这与 avg()（平均值）的结果不同，因为 percentile 不考虑离群值
(percentile(/host/net.if.in[eth0,bytes],1h,50)+percentile(/host/net.if.in[eth0,bytes],1h,51))/2 #在 1 小时内值的数量为偶数时，计算精确的中位数

rate(/host/key,sec<:time shift>)

在定义的时间段内，单调递增计数器的平均每秒增量。
支持的值类型：Float、Integer。

参数：

• 参见通用参数

在功能上对应于 PromQL 的 'rate'。

示例：

rate(/host/key,30s) #如果 30 秒内的单调增量为 20，则此函数返回 0.67。
rate(/host/net.if.in[eth0,bytes],5m)>500000 #过去 5 分钟内 eth0 上的入站接口流量速率已超过 500 KB/s
rate(/host/app.requests.count,1m)>100 #最近 1 分钟内，请求计数器已上升到每秒超过 100 个请求

请参阅所有支持的函数。