[comment]: # translation:outdated

[comment]: # attributes: notoc

[comment]: # ({5b5180a2-2e2a1a06})
# 8 预测函数

此处列出的所有函数均支持以下场景:

-   [Trigger expressions](/manual/config/triggers/expression)
-   [Calculated items](/manual/config/items/itemtypes/calculated)
-   [Expression macros](/manual/config/macros/expression_macros)

函数列表不包含额外说明。点击函数名称可查看完整详情。

| 函数 | 描述 |
|--|--------|
| [forecast](#forecast) | 监控项的终值、最大值、最小值、差值或平均值。 |
| [timeleft](#timeleft) | 监控项达到指定阈值所需的秒数。 |

[comment]: # ({/5b5180a2-2e2a1a06})

[comment]: # ({7bb9caf7-4d343eb8})
##### 通用参数

-   `/host/key` 是引用 主机 监控项 历史记录的函数的常见必选第一个参数
-   `(sec|#num)<:time shift>` 是引用 主机 监控项 历史记录的函数的常见第二个参数，其中：
    -   **sec** - 最大 [评估周期](/manual/config/triggers#评估周期) 秒数
        （可以使用时间 [suffixes](/manual/appendix/suffixes)），
        或
    -   **#num** - 最近收集值的最大 [评估周期](/manual/config/triggers#评估周期) 数量（如果前面带有井号）
    -   **时间偏移**（可选）允许将评估点向历史时间移动。请参阅 [时间偏移](/manual/config/triggers/expression#时间偏移) 了解如何指定时间偏移。

[comment]: # ({/7bb9caf7-4d343eb8})

[comment]: # ({c645f0e4-f3b63bc1})
### 函数详情

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

-   函数参数之间用逗号分隔
-   可选的函数参数（或参数部分）通过
    `<` `>` 表示
-   特定函数的参数会在每个函数中分别描述
-   `/host/key` 和 `(sec|#num)<:time shift>` 参数永远不要用引号括起

[comment]: # ({/c645f0e4-f3b63bc1})

[comment]: # ({8a873b31-e4452b37})
##### forecast(/host/key,(sec|#num)<:time shift>,time,<fit>,<mode>) {#forecast}

未来值、最大值、最小值、差值或平均值的监控项。<br>
支持的值类型：*float*、*integer*。

参数：

-   参见[通用参数](#common-parameters)；<br>
-   **time** - 预测时间范围，单位为秒（可以使用时间后缀）；支持负值；<br>
-   **fit**（可选；必须用双引号括起）- 用于拟合历史数据的函数。支持的拟合方式：<br>*linear* - 线性函数（默认）<br>*polynomialN* - N次多项式（1 <= N <= 6）<br>*exponential* - 指数函数<br>*logarithmic* - 对数函数<br>*power* - 幂函数<br>注意：*polynomial1* 等同于 *linear*；
-   **mode**（可选；必须用双引号括起）- 所需的输出模式。支持的模式：<br>*value* - 值（默认）<br>*max* - 最大值<br>*min* - 最小值<br>*delta* - *max* - *min*<br>*avg* - 平均值<br>注意：*value* 估计的是 `now` + `time` 时刻的监控项值；*max*、*min*、*delta* 和 *avg* 则研究 `now` 到 `now` + `time` 区间内的监控项值估计。

注释：

-   如果返回值大于 1.7976931348623158E+308 或小于 -1.7976931348623158E+308，则返回值将被截断为 1.7976931348623158E+308 或 -1.7976931348623158E+308；
-   仅在表达式中误用时（错误的监控项类型、无效参数）变为不支持，否则在出错时返回 -1；
-   另请参阅有关[predictive trigger functions](/manual/config/triggers/prediction)的附加信息。

示例：

    forecast(/主机/key,#10,1h) #基于最后10个值，预测一小时后的监控项值
    forecast(/主机/key,1h,30m) #基于最近一小时的数据，预测30分钟后监控项的值
    forecast(/主机/key,1h:now-1d,12h) #基于一天前的一小时数据，预测12小时后的监控项值
    forecast(/主机/key,1h,10m,"exponential") #基于最近一小时的数据和指数函数，预测10分钟后监控项的值
    forecast(/主机/key,1h,2h,"polynomial3","max") #基于最近一小时的数据和三次（三次多项式），预测未来两小时内监控项可能达到的最大值
    forecast(/主机/key,#2,-20m) #基于最近两个值，估计20分钟前的监控项值（这可能比使用last()更精确，特别是当监控项更新频率较低时，例如每小时一次）

[comment]: # ({/8a873b31-e4452b37})

[comment]: # ({834aceba-9b065620})
##### timeleft(/host/key,(sec|#num)<:time shift>,threshold,<fit>) {#timeleft}

触发器 监控项 达到指定阈值所需的时间（以秒为单位）。
支持的值类型：*float*、*integer*。

参数：

-   参见 [常见参数](#common-parameters)；
-   **阈值** - 要达到的值（可以使用 [unit suffixes](/manual/appendix/suffixes)）；
-   **fit**（可选；必须用双引号括起）- 参见 [forecast()](#forecast)。

评论：

-   如果要返回的值大于 1.7976931348623158E+308，则返回值会被截断为 1.7976931348623158E+308；
-   如果无法达到阈值，则返回 1.7976931348623158E+308；
-   仅在表达式中被错误使用时（错误的 监控项 类型，无效参数）才会变为不支持；否则在发生错误时返回 -1；
-   参见有关 [predictive trigger functions](/manual/config/triggers/prediction) 的附加信息。

示例：

    timeleft(/主机/key,#10,0) #基于最后的 10 值，监控项 值到达零的时间
    timeleft(/主机/key,1h,100) #基于最近一小时的数据，监控项值达到100所需的剩余时间
    timeleft(/主机/key,1h:now-1d,100) #基于一天前一小时，监控项值达到100之前的剩余时间
    timeleft(/主机/key,1h,200,"polynomial2") #基于最近一小时的数据并假设监控项的行为类似于二次（二阶）多项式，监控项值达到200之前的剩余时间

[comment]: # ({/834aceba-9b065620})

[comment]: # ({ba59dd3a-9958c480})
请参见 [all supported functions](/manual/appendix/functions)。

[comment]: # ({/ba59dd3a-9958c480})