Sentinel使用指南

Sentinel 简介

Sentinel 是阿里中间件团队开源的一款面向分布式服务架构的轻量级高可用的流量控制组件。

As distributed systems become increasingly popular, the reliability between services is becoming more important than ever before. Sentinel takes “flow” as breakthrough point, and works on multiple fields including flow control, circuit breaking and system adaptive protection, to guarantee reliability of microservices.
随着分布式系统的日益普及，服务间的可靠性变得越来越重要。哨兵以“流量”为突破口，在流量控制、断路、系统自适应保护等多个领域开展工作，保证微服务的可靠性
(引用自官方文档)

Sentinel具有的特征

• 丰富的应用场景：Sentinel 承接了阿里巴巴近 10 年的双十一大促流量的核心场景，例如秒杀（即突发流量控制在系统容量可以承受的范围）、消息削峰填谷、集群流量控制、实时熔断下游不可用应用等。
• 完备的实时监控：Sentinel 同时提供实时的监控功能。您可以在控制台中看到接入应用的单台机器秒级数据，甚至 500 台以下规模的集群的汇总运行情况。
• 广泛的开源生态：Sentinel 提供开箱即用的与其它开源框架/库的整合模块，例如与 Spring Cloud、Dubbo、gRPC 的整合。您只需要引入相应的依赖并进行简单的配置即可快速地接入 Sentinel。
• 完善的 SPI 扩展点：Sentinel 提供简单易用、完善的 SPI 扩展接口。您可以通过实现扩展接口来快速地定制逻辑。例如定制规则管理、适配动态数据源等。

Sentinel的组成

Sentinel 分为两个部分:

• 核心库（Java 客户端）不依赖任何框架/库，能够运行于所有 Java 运行时环境，同时对 Dubbo / Spring Cloud 等框架也有较好的支持。
• 控制台（Dashboard）基于 Spring Boot 开发，打包后可以直接运行，不需要额外的 Tomcat 等应用容器。

相关术语

• Resource
  在Sentinel中，Resource是资源的意思，它可以是代码块、方法、接口等任何需要保护的东西。在编程的时候，如果这个代码是否需要保护，那么我们就将之定义为一个资源
• Slot
  Slot是指Sentinel中的插槽。Sentinel的工作流程是围绕着一个个插槽所组成的插槽链来展开的。每个Slot都有自己的功能，通过一定的编排顺序，来达到最终的限流降级的目的。默认的各个插槽之间的顺序是固定的，因为有的插槽需要依赖其他的插槽计算出来的结果才能进行工作。
• Context
  Context是指调用链路上下文，它贯穿一次调用链路中的所有 Entry。Context 维护着当前调用链的元数据：入口节点、本次调用链路节点、调用来源等信息，通过 ThreadLocal 传递。
• Entry
  Entry是指Sentinel中请求是否通过限流的一个凭证。每次执行 SphU.entry() 或 SphO.entry() 都会返回一个 Entry 给调用者。资源调用结束时需要 entry.exit()。Entry 包含了资源名、curNode（当前统计节点）、originNode（来源统计节点）等信息。
• Node
  节点。在Sentinel中保存统计数据的对象有4种：

1. StatisticNode：统计节点，最为基础的统计节点，包含秒级和分钟级两个滑动窗口结构。
2. DefaultNode：链路节点，用于统计调用链路上某个资源的数据，维持树状结构。
3. ClusterNode：簇节点，用于统计每个资源全局的数据（不区分调用链路），以及存放该资源的按来源区分的调用数据。
4. EntranceNode：入口节点，特殊的链路节点，对应某个 Context 入口的所有调用数据。

如何使用Sentinel

引入依赖

我们通过maven将Sentinel依赖引入到项目中

Note: Sentinel requires Java 7 or later.
需要java7 或者更高的版本

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-core</artifactId>
    <version>1.7.1</version>
</dependency>

定义资源

定义资源的方式有五种

• 主流框架的默认适配方式
  对于大部分主流框架，如Web Selvet、Dubbo、Spring Cloud、gRPC、Spring WebFlux、Reactor等都做了适配，只需要引入对应的依赖既可以方便的的整合Sentinel。
  主流框架适配手册
• 抛出异常的方式

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 {
  // 资源名可使用任意有业务语义的字符串
  entry = SphU.entry("自定义资源名");
  // 被保护的业务逻辑
  // do something...
} catch (BlockException e1) {
  // 资源访问阻止，被限流或被降级
  // 进行相应的处理操作
} finally {
  if (entry != null) {
    entry.exit();
  }
}

SphU.entry() 的参数描述：
参数名 类型 解释 默认值
entryType EntryType 资源调用的流量类型，是入口流量（EntryType.IN）还是出口流量（EntryType.OUT），注意系统规则只对 IN 生效 EntryType.OUT
count int 本次资源调用请求的 token 数目 1
args Object[] 传入的参数，用于热点参数限流 无
注意：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 支持异步调用链路的统计。在异步调用中，需要通过 SphU.asyncEntry(xxx) 方法定义资源，并通常需要在异步的回调函数中调用 exit 方法。以下是一个简单的示例：
SphU.asyncEntry(xxx) 不会影响当前（调用线程）的 Context，因此以下两个 entry 在调用链上是平级关系（处于同一层），而不是嵌套关系：

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).
}

若在异步回调中需要嵌套其它的资源调用（无论是 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).
    }
}

定义规则

在定义好资源后，Sentinel需要我们提供限流规则。Sentinel所有的规则都可以在内存中查询和修改，且修改后立即生效。
Sentinel支持的限流规则有：

• 流量控制规则
• 熔断降级规则
• 系统保护规则
• 来源访问控制规则
• 热点参数规则