[comment]: # translation:outdated

[comment]: # attributes: notoc

[comment]: # (terms: forecast, timeleft )

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

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

-   [触发器表达式](/manual/config/triggers/expression)
-   [计算型监控项公式](/manual/config/items/itemtypes/calculated)
-   [表达式宏](/manual/config/macros/expression_macros)

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

|Function|Description|
|--|--------|
|[forecast](#forecast)|监控项未来的值、最大值、最小值、差值或平均值。|
|[timeleft](#timeleft)|监控项达到指定阈值所需的时间（秒）。|

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

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

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

[comment]: # ({/645b8a56-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(/host/key,#10,1h) #根据最近 10 个值预测一小时后的监控项值
    forecast(/host/key,1h,30m) #根据最近一小时的数据预测 30 分钟后的监控项值
    forecast(/host/key,1h:now-1d,12h) #根据一天前那一小时的数据预测 12 小时后的监控项值
    forecast(/host/key,1h,10m,"exponential") #根据最近一小时的数据和指数函数预测 10 分钟后的监控项值
    forecast(/host/key,1h,2h,"polynomial3","max") #根据最近一小时的数据和三次（3 阶）多项式预测监控项在接下来两小时内可达到的最大值
    forecast(/host/key,#2,-20m) #根据最近两个值估算 20 分钟前的监控项值（这可能比使用 last() 更精确，尤其是在监控项更新频率较低时，例如每小时一次）

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

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

监控项达到指定阈值所需的时间（以秒为单位）。<br>
支持的值类型：*Float*、*Integer*。

参数：

-   参见[通用参数](#common-parameters)；<br>
-   **threshold** - 要达到的值（可使用[单位后缀](/manual/appendix/suffixes)）；
-   **fit**（可选；必须用双引号括起来） - 参见 [forecast()](#forecast)。

说明：

-   如果返回值大于 1.7976931348623158E+308，则返回值会被截断为 1.7976931348623158E+308；
-   如果无法达到阈值，则返回 1.7976931348623158E+308；
-   仅当在表达式中使用不当时才会变为不支持（错误的监控项类型、无效参数）；否则在发生错误时返回 -1；
-   另请参见关于[预测型触发器函数](/manual/config/triggers/prediction)的更多信息。

示例：

    timeleft(/host/key,#10,0) #基于最近 10 个值，直到监控项值达到零所需的时间
    timeleft(/host/key,1h,100) #基于最近一小时的数据，直到监控项值达到 100 所需的时间
    timeleft(/host/key,1h:now-1d,100) #基于一天前一小时的数据，直到监控项值达到 100 所需的时间
    timeleft(/host/key,1h,200,"polynomial2") #基于最近一小时的数据，并假设监控项表现为二次（2 阶）多项式，直到监控项值达到 200 所需的时间

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

[comment]: # ({ba58f5e4-9958c480})
请参阅[所有支持的函数](/manual/config/triggers/expression#functions)。

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