squbs-15. 超时策略

超时是每个异步分布式系统的关键部分。他们通常配置为静态并且很难得到。squbs提供 Timeout Policy设施，作为 squbs-pattern包的一部分来帮助动态确定正确的超时时间（通过提供一个策略而不是静态设置）。这个通过策略来动态定义超时时间。请注意超时策略仅有助于输出超时值，其本身不会导致超时发生。

依赖

在你的build.sbt或scala构建文件中加入以下依赖：

"org.squbs" %% "squbs-pattern" % squbsVersion

快速例子

一个正常的await通过Scala的代码展示如下：

Await.ready(future, timeout.duration)

在如下的闭包内，你可以改变这个代码至一个 await块

val policy = TimeoutPolicy(name = Some("mypolicy"), initial = 1 second)
val result = policy.execute(duration => {
  Await.ready(future, duration)
})

Scala API

你可以通过传递如下规则创建TimeoutPolicy

1. 对于固定的超时时间，你实际上不需要指定一个规则。 fixedRule是默认的

   val policy = TimeoutPolicy(name = Some("MyFixedPolicy"), initial = 1 second, rule = fixedRule)
   

2. 超时时间基于响应时间的标准差（sigma）

   val policy = TimeoutPolicy(name = Some("MySigmaPolicy"), initial = 1 second, rule = 3 sigma)
   

3. 超时时间基于响应时间的百分比

   val policy = TimeoutPolicy(name = Some("MyPctPolicy"), initial = 1 second, rule = 95 percentile)
   

随后你可以使用如下策略:

val result = policy.execute(duration => {
  Await.ready(future, duration)
})

或者不使用闭包的另一个形式

val policy = TimeoutPolicy(name = Some("mypolicy"), initial = 1 second)
val tx = policy.transaction
Await.ready(future, tx.waitTime)
tx.end

tx.end是非常重要的，因为它为单一操作提供闭包（由超时策略监视），当我们使用推荐的闭包版本的API时，某些事情将会自动监控。它用于一个反馈回路来观察实际的运行时间并将这个信息返回给heuristic。

Java API

在JAVA api中，我们通过一个策略builder创建超时策略，可以在以下的例子中看到：

1. 固定的超时时间.

   TimeoutPolicy fixedTimeoutPolicy = TimeoutPolicyBuilder
       .create(new FiniteDuration(INITIAL_TIMEOUT, MILLISECONDS), fromExecutorService(es))
       .minSamples(1)
       .rule(TimeoutPolicyType.FIXED)
       .build();
   

2. 超时时间基于响应时间的标准差（sigma）

   TimeoutPolicy sigmaTimeoutPolicy = TimeoutPolicyBuilder
       .create(new FiniteDuration(INITIAL_TIMEOUT, MILLISECONDS), system.dispatcher())
       .minSamples(1)
       .name("MySigmaPolicy")
       .rule(3.0, TimeoutPolicyType.SIGMA)
       .build();
   

3. 超时时间基于响应时间的百分比

   TimeoutPolicy percentileTimeoutPolicy = TimeoutPolicyBuilder
       .create(new FiniteDuration(INITIAL_TIMEOUT, MILLISECONDS), system.dispatcher())
       .minSamples(1)
       .name("PERCENTILE")
       .rule(95, TimeoutPolicyType.PERCENTILE)
       .build();
   

然后，使用这个超时时间策略，只需要在你的闭包内执行调用，如下：

policy.execute((FiniteDuration t) -> {
    return es.submit(timedCall).get(t.toMillis() + 20, MILLISECONDS);
});

或者，你可以使用非闭包调用：

TimeoutPolicy.TimeoutTransaction tx = policy.transaction();
try {
  return timedFn.get(tx.waitTime());
} catch (Exception e) {
  System.out.println(e);
} finally {
  tx.end();
}

tx.end是重要的，因为它提供一个被超时策略监视的单一操作，当使用推荐的闭包版本的API，这些事会被自动监视。这是用来一个反馈回路来观察真实的调用时间，并且把这些信息返回到heuristic。

TimeoutPolicy中的Heuristics

默认的超时策略是一个固定的超时，代码你将始终获得一个初始值在常规模式，一个调试值在调试环境。不过，拥有一个超时策略的前提是提供heuristics-based超时。下面是超时策略中使用的主要概念：

在统计学中, the [68–95–99.7 rule]规则，如众所周知的 three-sigma rule 或 经验法则，将近所有的值接近三个平方差的正太分布中。

empirical rule
因此，如果你声明你的超时策略如下：

val policy = TimeoutPolicy("mypolicy", initial = 1 second, rule = 2 sigma)

你将获得一个超时值覆盖大约 95%响应时间，放弃 5% 异常值通过使用2个sigma或95%的超时策略。通过调用policy.execute(tiemout=>T) 或 policy.transaction.waitTime生效。

回到统计

这里有三种方式来回顾统计学

1. 在TimeoutPolicy创建时设置startOverCount，当所有的事务计数到达 startOverCount，这将自动开始重新统计
2. 调用 policy.reset重设统计，你可以同样在调用重设方法时提供一个新的 initial 和startOverCount 。
3. 调用TimeoutPolicy.resetPolicy("yourName") 在全局重设策略。

名称

任何构建超时策略提供一个可选的名称。超时策略使用同一个名称和其他策略实例分享他们的指标。 policy-by-name避免用户创建一个策略实例，并通过共享相同策略传递出所有的使用。用户可以干净的复制策略在任何使用点，同时还能收集指标。另外，通过调用TimeoutPolicy.resetPolicy("name")使用策略中名称可以集中清除指标。

警告：不要为完全不同性质的策略使用同一个名称，因为可能混淆你的统计。结果可能不可预测。

调试

用于调试目的，默认的超时策略为1000秒当你在调试模式中执行时。你可以通过传递debug参数至TimeoutPolicy进行设置，如下：

val policy = TimeoutPolicy(name = Some("mypolicy"), initial = 1 second, debug = 10000 seconds)