Sentinel（三）之如何使用

浅浅的花香味﹌ 2023-01-08 05:22 92阅读 0赞

转载自  [Sentinel如何使用][Sentinel]

## 简介 ##

Sentinel 可以简单的分为 Sentinel 核心库和 Dashboard。核心库不依赖 Dashboard，但是结合 Dashboard 可以取得最好的效果。

这篇文章主要介绍 Sentinel 核心库的使用。如果希望有一个最快最直接的了解，可以参考 [新手指南][Link 1] 来获取一个最直观的感受。

我们说的资源，可以是任何东西，服务，服务里的方法，甚至是一段代码。使用 Sentinel 来进行资源保护，主要分为几个步骤:

1.  定义资源
2.  定义规则
3.  检验规则是否生效

先把可能需要保护的资源定义好（埋点），之后再配置规则。也可以理解为，只要有了资源，我们就可以在任何时候灵活地定义各种流量控制规则。在编码的时候，只需要考虑这个代码是否需要保护，如果需要保护，就将之定义为一个资源。

对于主流的框架，我们提供适配，只需要按照适配中的说明配置，Sentinel 就会默认定义提供的服务，方法等为资源。

## 定义资源 ##

### 方式一：主流框架的默认适配 ###

为了减少开发的复杂程度，我们对大部分的主流框架，例如 Web Servlet、Dubbo、Spring Cloud、gRPC、Spring WebFlux、Reactor 等都做了适配。您只需要引入对应的依赖即可方便地整合 Sentinel。可以参见: [主流框架的适配][Link 2]。

### 方式二：抛出异常的方式定义资源 ###

`SphU` 包含了 try-catch 风格的 API。用这种方式，当资源发生了限流之后会抛出 `BlockException`。这个时候可以捕捉异常，进行限流之后的逻辑处理。示例代码如下:

// 1.5.0 版本开始可以利用 try-with-resources 特性（使用有限制）
    // 资源名可使用任意有业务语义的字符串，比如方法名、接口名或其它可唯一标识的字符串。
    try (Entry entry = SphU.entry("resourceName")) {
      // 被保护的业务逻辑
      // do something here...
    } catch (BlockException ex) {
      // 资源访问阻止，被限流或被降级
      // 在此处进行相应的处理操作
    }

**特别地**，若 entry 的时候传入了热点参数，那么 exit 的时候也一定要带上对应的参数（`exit(count, args)`），否则可能会有统计错误。这个时候不能使用 try-with-resources 的方式。另外通过 `Tracer.trace(ex)` 来统计异常信息时，由于 try-with-resources 语法中 catch 调用顺序的问题，会导致无法正确统计异常数，因此统计异常信息时也不能在 try-with-resources 的 catch 块中调用 `Tracer.trace(ex)`。

手动 exit 示例：

Entry entry = null;
    // 务必保证 finally 会被执行
    try {
      // 资源名可使用任意有业务语义的字符串，注意数目不能太多（超过 1K），超出几千请作为参数传入而不要直接作为资源名
      // EntryType 代表流量类型（inbound/outbound），其中系统规则只对 IN 类型的埋点生效
      entry = SphU.entry("自定义资源名");
      // 被保护的业务逻辑
      // do something...
    } catch (BlockException ex) {
      // 资源访问阻止，被限流或被降级
      // 进行相应的处理操作
    } catch (Exception ex) {
      // 若需要配置降级规则，需要通过这种方式记录业务异常
      Tracer.traceEntry(ex, entry);
    } finally {
      // 务必保证 exit，务必保证每个 entry 与 exit 配对
      if (entry != null) {
        entry.exit();
      }
    }

热点参数埋点示例：

Entry entry = null;
    try {
        // 若需要配置例外项，则传入的参数只支持基本类型。
        // EntryType 代表流量类型，其中系统规则只对 IN 类型的埋点生效
        // count 大多数情况都填 1，代表统计为一次调用。
        entry = SphU.entry(resourceName, EntryType.IN, 1, paramA, paramB);
        // Your logic here.
    } catch (BlockException ex) {
        // Handle request rejection.
    } finally {
        // 注意：exit 的时候也一定要带上对应的参数，否则可能会有统计错误。
        if (entry != null) {
            entry.exit(1, paramA, paramB);
        }
    }

`SphU.entry()` 的参数描述：

<table> 
 <thead> 
  <tr> 
   <th>参数名</th> 
   <th>类型</th> 
   <th>解释</th> 
   <th>默认值</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>entryType</td> 
   <td><code>EntryType</code></td> 
   <td>资源调用的流量类型，是入口流量（<code>EntryType.IN</code>）还是出口流量（<code>EntryType.OUT</code>），注意系统规则只对 IN 生效</td> 
   <td><code>EntryType.OUT</code></td> 
  </tr> 
  <tr> 
   <td>count</td> 
   <td><code>int</code></td> 
   <td>本次资源调用请求的 token 数目</td> 
   <td>1</td> 
  </tr> 
  <tr> 
   <td>args</td> 
   <td><code>Object[]</code></td> 
   <td>传入的参数，用于热点参数限流</td> 
   <td>无</td> 
  </tr> 
 </tbody> 
</table>

**注意**：`SphU.entry(xxx)` 需要与 `entry.exit()` 方法成对出现，匹配调用，否则会导致调用链记录异常，抛出 `ErrorEntryFreeException` 异常。常见的错误：

*  自定义埋点只调用 `SphU.entry()`，没有调用 `entry.exit()`
 *  顺序错误，比如：`entry1 -> entry2 -> exit1 -> exit2`，应该为 `entry1 -> entry2 -> exit2 -> exit1`

### 方式三：返回布尔值方式定义资源 ###

`SphO` 提供 if-else 风格的 API。用这种方式，当资源发生了限流之后会返回 `false`，这个时候可以根据返回值，进行限流之后的逻辑处理。示例代码如下:

// 资源名可使用任意有业务语义的字符串
      if (SphO.entry("自定义资源名")) {
        // 务必保证finally会被执行
        try {
          /**
          * 被保护的业务逻辑
          */
        } finally {
          SphO.exit();
        }
      } else {
        // 资源访问阻止，被限流或被降级
        // 进行相应的处理操作
      }

**注意**：`SphO.entry(xxx)` 需要与 SphO.exit()`方法成对出现，匹配调用，位置正确，否则会导致调用链记录异常，抛出`ErrorEntryFreeException\` 异常。

### 方式四：注解方式定义资源 ###

Sentinel 支持通过 `@SentinelResource` 注解定义资源并配置 `blockHandler` 和 `fallback` 函数来进行限流之后的处理。示例：

// 原本的业务方法.
    @SentinelResource(blockHandler = "blockHandlerForGetUser")
    public User getUserById(String id) {
        throw new RuntimeException("getUserById command failed");
    }
    
    // blockHandler 函数，原方法调用被限流/降级/系统保护的时候调用
    public User blockHandlerForGetUser(String id, BlockException ex) {
        return new User("admin");
    }

注意 `blockHandler` 函数会在原方法被限流/降级/系统保护的时候调用，而 `fallback` 函数会针对所有类型的异常。请注意 `blockHandler` 和 `fallback` 函数的形式要求，更多指引可以参见 [Sentinel 注解支持文档][Sentinel 1]。

### 方式五：异步调用支持 ###

Sentinel 支持异步调用链路的统计。在异步调用中，需要通过 `SphU.asyncEntry(xxx)` 方法定义资源，并通常需要在异步的回调函数中调用 `exit` 方法。以下是一个简单的示例：

try {
        AsyncEntry entry = SphU.asyncEntry(resourceName);
    
        // 异步调用.
        doAsync(userId, result -> {
            try {
                // 在此处处理异步调用的结果.
            } finally {
                // 在回调结束后 exit.
                entry.exit();
            }
        });
    } catch (BlockException ex) {
        // Request blocked.
        // Handle the exception (e.g. retry or fallback).
    }

`SphU.asyncEntry(xxx)` 不会影响当前（调用线程）的 Context，因此以下两个 entry 在调用链上是平级关系（处于同一层），而不是嵌套关系：

// 调用链类似于：
    // -parent
    // ---asyncResource
    // ---syncResource
    asyncEntry = SphU.asyncEntry(asyncResource);
    entry = SphU.entry(normalResource);

若在异步回调中需要嵌套其它的资源调用（无论是 `entry` 还是 `asyncEntry`），只需要借助 Sentinel 提供的上下文切换功能，在对应的地方通过 `ContextUtil.runOnContext(context, f)` 进行 Context 变换，将对应资源调用处的 Context 切换为生成的异步 Context，即可维持正确的调用链路关系。示例如下：

public void handleResult(String result) {
        Entry entry = null;
        try {
            entry = SphU.entry("handleResultForAsync");
            // Handle your result here.
        } catch (BlockException ex) {
            // Blocked for the result handler.
        } finally {
            if (entry != null) {
                entry.exit();
            }
        }
    }
    
    public void someAsync() {
        try {
            AsyncEntry entry = SphU.asyncEntry(resourceName);
    
            // Asynchronous invocation.
            doAsync(userId, result -> {
                // 在异步回调中进行上下文变换，通过 AsyncEntry 的 getAsyncContext 方法获取异步 Context
                ContextUtil.runOnContext(entry.getAsyncContext(), () -> {
                    try {
                        // 此处嵌套正常的资源调用.
                        handleResult(result);
                    } finally {
                        entry.exit();
                    }
                });
            });
        } catch (BlockException ex) {
            // Request blocked.
            // Handle the exception (e.g. retry or fallback).
        }
    }

此时的调用链就类似于：

-parent
    ---asyncInvocation
    -----handleResultForAsync

更详细的示例可以参考 Demo 中的 [AsyncEntryDemo][]，里面包含了普通资源与异步资源之间的各种嵌套示例。

## 规则的种类 ##

Sentinel 的所有规则都可以在内存态中动态地查询及修改，修改之后立即生效。同时 Sentinel 也提供相关 API，供您来定制自己的规则策略。

Sentinel 支持以下几种规则：**流量控制规则**、**熔断降级规则**、**系统保护规则**、**来源访问控制规则** 和 **热点参数规则**。

### 流量控制规则 (FlowRule) ###

流量规则的定义

重要属性：

<table> 
 <thead> 
  <tr> 
   <th>Field</th> 
   <th>说明</th> 
   <th>默认值</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>resource</td> 
   <td>资源名，资源名是限流规则的作用对象</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>count</td> 
   <td>限流阈值</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>grade</td> 
   <td>限流阈值类型，QPS 模式（1）或并发线程数模式（0）</td> 
   <td>QPS 模式</td> 
  </tr> 
  <tr> 
   <td>limitApp</td> 
   <td>流控针对的调用来源</td> 
   <td><code>default</code>，代表不区分调用来源</td> 
  </tr> 
  <tr> 
   <td>strategy</td> 
   <td>调用关系限流策略：直接、链路、关联</td> 
   <td>根据资源本身（直接）</td> 
  </tr> 
  <tr> 
   <td>controlBehavior</td> 
   <td>流控效果（直接拒绝/WarmUp/匀速+排队等待），不支持按调用关系限流</td> 
   <td>直接拒绝</td> 
  </tr> 
  <tr> 
   <td>clusterMode</td> 
   <td>是否集群限流</td> 
   <td>否</td> 
  </tr> 
 </tbody> 
</table>

同一个资源可以同时有多个限流规则，检查规则时会依次检查。

通过代码定义流量控制规则

理解上面规则的定义之后，我们可以通过调用 `FlowRuleManager.loadRules()` 方法来用硬编码的方式定义流量控制规则，比如：

private void initFlowQpsRule() {
        List<FlowRule> rules = new ArrayList<>();
        FlowRule rule = new FlowRule(resourceName);
        // set limit qps to 20
        rule.setCount(20);
        rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
        rule.setLimitApp("default");
        rules.add(rule);
        FlowRuleManager.loadRules(rules);
    }

更多详细内容可以参考 [流量控制][Link 3]。

### 熔断降级规则 (DegradeRule) ###

熔断降级规则包含下面几个重要的属性：

<table> 
 <thead> 
  <tr> 
   <th>Field</th> 
   <th>说明</th> 
   <th>默认值</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>resource</td> 
   <td>资源名，即规则的作用对象</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>grade</td> 
   <td>熔断策略，支持慢调用比例/异常比例/异常数策略</td> 
   <td>慢调用比例</td> 
  </tr> 
  <tr> 
   <td>count</td> 
   <td>慢调用比例模式下为慢调用临界 RT（超出该值计为慢调用）；异常比例/异常数模式下为对应的阈值</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>timeWindow</td> 
   <td>熔断时长，单位为 s</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>minRequestAmount</td> 
   <td>熔断触发的最小请求数，请求数小于该值时即使异常比率超出阈值也不会熔断（1.7.0 引入）</td> 
   <td>5</td> 
  </tr> 
  <tr> 
   <td>statIntervalMs</td> 
   <td>统计时长（单位为 ms），如 60*1000 代表分钟级（1.8.0 引入）</td> 
   <td>1000 ms</td> 
  </tr> 
  <tr> 
   <td>slowRatioThreshold</td> 
   <td>慢调用比例阈值，仅慢调用比例模式有效（1.8.0 引入）</td> 
   <td>&nbsp;</td> 
  </tr> 
 </tbody> 
</table>

同一个资源可以同时有多个降级规则。

理解上面规则的定义之后，我们可以通过调用 `DegradeRuleManager.loadRules()` 方法来用硬编码的方式定义流量控制规则。

private void initDegradeRule() {
        List<DegradeRule> rules = new ArrayList<>();
        DegradeRule rule = new DegradeRule();
        rule.setResource(KEY);
        // set threshold RT, 10 ms
        rule.setCount(10);
        rule.setGrade(RuleConstant.DEGRADE_GRADE_RT);
        rule.setTimeWindow(10);
        rules.add(rule);
        DegradeRuleManager.loadRules(rules);
    }

更多详情可以参考 [熔断降级][Link 4]。

### 系统保护规则 (SystemRule) ###

Sentinel 系统自适应限流从整体维度对应用入口流量进行控制，结合应用的 Load、CPU 使用率、总体平均 RT、入口 QPS 和并发线程数等几个维度的监控指标，通过自适应的流控策略，让系统的入口流量和系统的负载达到一个平衡，让系统尽可能跑在最大吞吐量的同时保证系统整体的稳定性。

系统规则包含下面几个重要的属性：

<table> 
 <thead> 
  <tr> 
   <th>Field</th> 
   <th>说明</th> 
   <th>默认值</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>highestSystemLoad</td> 
   <td><code>load1</code>&nbsp;触发值，用于触发自适应控制阶段</td> 
   <td>-1 (不生效)</td> 
  </tr> 
  <tr> 
   <td>avgRt</td> 
   <td>所有入口流量的平均响应时间</td> 
   <td>-1 (不生效)</td> 
  </tr> 
  <tr> 
   <td>maxThread</td> 
   <td>入口流量的最大并发数</td> 
   <td>-1 (不生效)</td> 
  </tr> 
  <tr> 
   <td>qps</td> 
   <td>所有入口资源的 QPS</td> 
   <td>-1 (不生效)</td> 
  </tr> 
  <tr> 
   <td>highestCpuUsage</td> 
   <td>当前系统的 CPU 使用率（0.0-1.0）</td> 
   <td>-1 (不生效)</td> 
  </tr> 
 </tbody> 
</table>

理解上面规则的定义之后，我们可以通过调用 `SystemRuleManager.loadRules()` 方法来用硬编码的方式定义流量控制规则。

private void initSystemRule() {
        List<SystemRule> rules = new ArrayList<>();
        SystemRule rule = new SystemRule();
        rule.setHighestSystemLoad(10);
        rules.add(rule);
        SystemRuleManager.loadRules(rules);
    }

注意系统规则只针对入口资源（EntryType=IN）生效。更多详情可以参考 [系统自适应保护文档][Link 5]。

### 访问控制规则 (AuthorityRule) ###

很多时候，我们需要根据调用方来限制资源是否通过，这时候可以使用 Sentinel 的访问控制（黑白名单）的功能。黑白名单根据资源的请求来源（`origin`）限制资源是否通过，若配置白名单则只有请求来源位于白名单内时才可通过；若配置黑名单则请求来源位于黑名单时不通过，其余的请求通过。

授权规则，即黑白名单规则（`AuthorityRule`）非常简单，主要有以下配置项：

*  `resource`：资源名，即规则的作用对象
 *  `limitApp`：对应的黑名单/白名单，不同 origin 用 `,` 分隔，如 `appA,appB`
 *  `strategy`：限制模式，`AUTHORITY_WHITE` 为白名单模式，`AUTHORITY_BLACK` 为黑名单模式，默认为白名单模式

更多详情可以参考 [来源访问控制][Link 6]。

### 热点规则 (ParamFlowRule) ###

详情可以参考 [热点参数限流][Link 7]。

## 查询更改规则 ##

引入了 transport 模块后，可以通过以下的 HTTP API 来获取所有已加载的规则：

http://localhost:8719/getRules?type=<XXXX>

其中，`type=flow` 以 JSON 格式返回现有的限流规则，degrade 返回现有生效的降级规则列表，system 则返回系统保护规则。

获取所有热点规则：

http://localhost:8719/getParamRules

## 定制自己的持久化规则 ##

上面的规则配置，都是存在内存中的。即如果应用重启，这个规则就会失效。因此我们提供了开放的接口，您可以通过实现 [`DataSource`][DataSource] 接口的方式，来自定义规则的存储数据源。通常我们的建议有：

*  整合动态配置系统，如 ZooKeeper、[Nacos][]、Apollo 等，动态地实时刷新配置规则
 *  结合 RDBMS、NoSQL、VCS 等来实现该规则
 *  配合 Sentinel Dashboard 使用

更多详情请参考 [动态规则配置][Link 8]。

## 规则生效的效果 ##

### 判断限流降级异常 ###

在 Sentinel 中所有流控降级相关的异常都是异常类 `BlockException` 的子类：

*  流控异常：`FlowException`
 *  熔断降级异常：`DegradeException`
 *  系统保护异常：`SystemBlockException`
 *  热点参数限流异常：`ParamFlowException`

我们可以通过以下函数判断是否为 Sentinel 的流控降级异常：

BlockException.isBlockException(Throwable t);

除了在业务代码逻辑上看到规则生效，我们也可以通过下面简单的方法，来校验规则生效的效果：

*  **暴露的 HTTP 接口**：通过运行下面命令 `curl http://localhost:8719/cnode?id=<资源名称>`，观察返回的数据。如果规则生效，在返回的数据栏中的 `block` 以及 `block(m)` 中会有显示
 *  **日志**：Sentinel 提供秒级的资源运行日志以及限流日志，详情可以参考: [日志][Link 9]

### block 事件 ###

Sentinel 提供以下扩展接口，可以通过 `StatisticSlotCallbackRegistry` 向 `StatisticSlot` 注册回调函数：

*  `ProcessorSlotEntryCallback`: callback when resource entry passed (`onPass`) or blocked (`onBlocked`)
 *  `ProcessorSlotExitCallback`: callback when resource entry successfully completed (`onExit`)

可以利用这些回调接口来实现报警等功能，实时的监控信息可以从 `ClusterNode` 中实时获取。

## 其它 API ##

### 业务异常统计 Tracer ###

业务异常记录类 `Tracer` 用于记录业务异常。相关方法：

*  `trace(Throwable e)`：记录业务异常（非 `BlockException` 异常），对应的资源为当前线程 context 下 entry 对应的资源。该方法必须在 `SphU.entry(xxx)` 成功之后且 exit 之前调用，否则当前 context 为空则会抛出异常。
 *  `trace(Throwable e, int count)`：记录业务异常（非 `BlockException` 异常），异常数目为传入的 `count`。该方法必须在 `SphU.entry(xxx)` 成功之后且 exit 之前调用，否则当前 context 为空则会抛出异常。
 *  `traceEntry(Throwable, int, Entry)`：向传入 entry 对应的资源记录业务异常（非 `BlockException` 异常），异常数目为传入的 `count`。

如果用户通过 `SphU` 或 `SphO` 手动定义资源，则 Sentinel 不能感知上层业务的异常，需要手动调用 `Tracer.trace(ex)` 来记录业务异常，否则对应的异常不会统计到 Sentinel 异常计数中。注意不要在 try-with-resources 形式的 `SphU.entry(xxx)` 中使用，否则会统计不上。

从 1.3.1 版本开始，注解方式定义资源支持自动统计业务异常，无需手动调用 `Tracer.trace(ex)` 来记录业务异常。Sentinel 1.3.1 以前的版本需要手动记录。

### 上下文工具类 ContextUtil ###