image-20230922143921562

Sentinel: 分布式系统的流量防卫兵

Sentinel 是什么？

随着微服务的流行，服务和服务之间的稳定性变得越来越重要。Sentinel 以流量为切入点，从流量控制、熔断降级、系统负载保护等多个维度保护服务的稳定性。

Sentinel 具有以下特征:

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

Sentinel 的主要特性：

image-20230922143928069

Sentinel 的开源生态：

image-20230922143936780

Sentinel 分为两个部分:

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

Quick Start

1.1 公网 Demo

如果希望最快的了解 Sentinel 在做什么，我们可以通过 Sentinel 新手指南 来运行一个例子，并且能在云上控制台上看到最直观的监控和流控效果等。

若希望无侵入将已有服务接入 Sentinel 来快速体验 Sentinel 全方位的流量防护和可观测能力，推荐采用 Java Agent 方式快速、无侵入将应用接入到云上 AHAS 控制台来体验 Sentinel 的能力。

1.2 手动接入 Sentinel 以及控制台

下面的例子将展示应用如何三步接入 Sentinel。同时，Sentinel 也提供所见即所得的控制台，可以实时监控资源以及管理规则。

STEP 1. 在应用中引入Sentinel Jar包

如果应用使用 pom 工程，则在 pom.xml 文件中加入以下代码即可：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-core</artifactId>
    <version>1.8.3</version>
</dependency>

注意: Sentinel 仅支持 JDK 1.8 或者以上版本。

如果您未使用依赖管理工具，请到 Maven Center Repository 直接下载 JAR 包。

STEP 2. 定义资源

接下来，我们把需要控制流量的代码用 Sentinel API SphU.entry("HelloWorld") 和 entry.exit() 包围起来即可。在下面的例子中，我们将 System.out.println("hello world"); 这端代码作为资源，用 API 包围起来（埋点）。参考代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
public static void main(String[] args) {
    initFlowRules();
    while (true) {
        Entry entry = null;
        try {
	    entry = SphU.entry("HelloWorld");
            /*您的业务逻辑 - 开始*/
            System.out.println("hello world");
            /*您的业务逻辑 - 结束*/
	} catch (BlockException e1) {
            /*流控逻辑处理 - 开始*/
	    System.out.println("block!");
            /*流控逻辑处理 - 结束*/
	} finally {
	   if (entry != null) {
	       entry.exit();
	   }
	}
    }
}

完成以上两步后，代码端的改造就完成了。当然，我们也提供了 注解支持模块，可以以低侵入性的方式定义资源。

STEP 3. 定义规则

接下来，通过规则来指定允许该资源通过的请求次数，例如下面的代码定义了资源 HelloWorld 每秒最多只能通过 20 个请求。

1
2
3
4
5
6
7
8
9
10
private static void initFlowRules(){
    List<FlowRule> rules = new ArrayList<>();
    FlowRule rule = new FlowRule();
    rule.setResource("HelloWorld");
    rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
    // Set limit QPS to 20.
    rule.setCount(20);
    rules.add(rule);
    FlowRuleManager.loadRules(rules);
}

完成上面 3 步，Sentinel 就能够正常工作了。更多的信息可以参考 使用文档。

STEP 4. 检查效果

Demo 运行之后，我们可以在日志 ~/logs/csp/${appName}-metrics.log.xxx 里看到下面的输出:

1
2
3
4
5
6
7
|--timestamp-|------date time----|-resource-|p |block|s |e|rt
1529998904000|2018-06-26 15:41:44|HelloWorld|20|0    |20|0|0
1529998905000|2018-06-26 15:41:45|HelloWorld|20|5579 |20|0|728
1529998906000|2018-06-26 15:41:46|HelloWorld|20|15698|20|0|0
1529998907000|2018-06-26 15:41:47|HelloWorld|20|19262|20|0|0
1529998908000|2018-06-26 15:41:48|HelloWorld|20|19502|20|0|0
1529998909000|2018-06-26 15:41:49|HelloWorld|20|18386|20|0|0

其中 p 代表通过的请求, block 代表被阻止的请求, s 代表成功执行完成的请求个数, e 代表用户自定义的异常, rt 代表平均响应时长。

可以看到，这个程序每秒稳定输出 “hello world” 20 次，和规则中预先设定的阈值是一样的。

更详细的说明可以参考: 如何使用

更多的例子可以参考: Sentinel Examples

STEP 5. 启动 Sentinel 控制台

您可以参考 Sentinel 控制台文档 启动控制台，可以实时监控各个资源的运行情况，并且可以实时地修改限流规则。

image-20230922143952400

快速入门

欢迎来到 Sentinel 的世界！这篇新手指南将指引您快速入门 Sentinel。

Sentinel 的使用可以分为两个部分:

  • 核心库（Java 客户端）：不依赖任何框架/库，能够运行于 Java 8 及以上的版本的运行时环境，同时对 Dubbo / Spring Cloud 等框架也有较好的支持（见 主流框架适配）。
  • 控制台（Dashboard）：控制台主要负责管理推送规则、监控、集群限流分配管理、机器发现等。

我们将会提供 本地运行 demo 和 阿里云公网 demo 来帮助新手快速入门。这两种方式都只需要您执行2到5个步骤。其中阿里云 AHAS demo 支持全自动托管的集群流控能力。

本地 Demo

1. 引入 Sentinel 依赖

如果您的应用使用了 Maven，则在 pom.xml 文件中加入以下代码即可：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-core</artifactId>
    <version>1.8.3</version>
</dependency>

如果您未使用依赖管理工具，请到 Maven Center Repository 直接下载 JAR 包。

2. 定义资源

资源 是 Sentinel 中的核心概念之一。最常用的资源是我们代码中的 Java 方法。 当然，您也可以更灵活的定义你的资源，例如，把需要控制流量的代码用 Sentinel API SphU.entry("HelloWorld") 和 entry.exit() 包围起来即可。在下面的例子中，我们将 System.out.println("hello world"); 作为资源（被保护的逻辑），用 API 包装起来。参考代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public static void main(String[] args) {
    // 配置规则.
    initFlowRules();

    while (true) {
        // 1.5.0 版本开始可以直接利用 try-with-resources 特性，自动 exit entry
        try (Entry entry = SphU.entry("HelloWorld")) {
            // 被保护的逻辑
            System.out.println("hello world");
	} catch (BlockException ex) {
            // 处理被流控的逻辑
	    System.out.println("blocked!");
	}
    }
}

完成以上两步后，代码端的改造就完成了。

您也可以通过我们提供的 注解支持模块，来定义我们的资源，类似于下面的代码：

1
2
3
4
5
@SentinelResource("HelloWorld")
public void helloWorld() {
    // 资源中的逻辑
    System.out.println("hello world");
}

这样，helloWorld() 方法就成了我们的一个资源。注意注解支持模块需要配合 Spring AOP 或者 AspectJ 一起使用。

3. 定义规则

接下来，通过流控规则来指定允许该资源通过的请求次数，例如下面的代码定义了资源 HelloWorld 每秒最多只能通过 20 个请求。

1
2
3
4
5
6
7
8
9
10
private static void initFlowRules(){
    List<FlowRule> rules = new ArrayList<>();
    FlowRule rule = new FlowRule();
    rule.setResource("HelloWorld");
    rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
    // Set limit QPS to 20.
    rule.setCount(20);
    rules.add(rule);
    FlowRuleManager.loadRules(rules);
}

完成上面 3 步，Sentinel 就能够正常工作了。更多的信息可以参考 使用文档。

4. 检查效果

Demo 运行之后，我们可以在日志 ~/logs/csp/${appName}-metrics.log.xxx 里看到下面的输出:

1
2
3
4
5
6
7
|--timestamp-|------date time----|--resource-|p |block|s |e|rt
1529998904000|2018-06-26 15:41:44|hello world|20|0    |20|0|0
1529998905000|2018-06-26 15:41:45|hello world|20|5579 |20|0|728
1529998906000|2018-06-26 15:41:46|hello world|20|15698|20|0|0
1529998907000|2018-06-26 15:41:47|hello world|20|19262|20|0|0
1529998908000|2018-06-26 15:41:48|hello world|20|19502|20|0|0
1529998909000|2018-06-26 15:41:49|hello world|20|18386|20|0|0

其中 p 代表通过的请求, block 代表被阻止的请求, s 代表成功执行完成的请求个数, e 代表用户自定义的异常, rt 代表平均响应时长。

可以看到，这个程序每秒稳定输出 “hello world” 20 次，和规则中预先设定的阈值是一样的。

更详细的说明可以参考: 如何使用

更多的例子可以参考: Sentinel Demo 集锦

5. 启动 Sentinel 控制台

Sentinel 开源控制台支持实时监控和规则管理。接入控制台的步骤如下：

（1）下载控制台 jar 包并在本地启动：可以参见 此处文档。

（2）客户端接入控制台，需要：

  • 客户端需要引入 Transport 模块来与 Sentinel 控制台进行通信。您可以通过 pom.xml 引入 JAR 包:
1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-transport-simple-http</artifactId>
    <version>1.8.3</version>
</dependency>
  • 启动时加入 JVM 参数 -Dcsp.sentinel.dashboard.server=consoleIp:port 指定控制台地址和端口。更多的参数参见 启动参数文档。
  • 确保应用端有访问量

完成以上步骤后即可在 Sentinel 控制台上看到对应的应用，机器列表页面可以看到对应的机器：

image-20230922143958556

详细介绍和使用文档可参考：Sentinel 控制台文档。

公网 Demo

若您不希望在本地另启动控制台，可以在本地运行公网 Demo，接入云上版本的 AHAS Sentinel 控制台。这个 Demo 主要是给开发者一个最快最直观的感受，能够最快地感受到：

  1. Sentinel 多样化的限流手段
  2. 如何所见即所得的配置规则
  3. 如何有效地使用 Sentinel 专业全面的监控数据
  4. 如何通过机器上报来管理机器
  5. 快速体验全托管的集群流控

HOT: 推荐采用 Java Agent 方式快速、无侵入将应用接入到 AHAS 流量防护。最新 (1.9.1+) 版本 agent 兼容部分版本 Spring Cloud Alibaba Sentinel，可直接挂载 agent 接入，无需剔除相关依赖。

注意：若要使用阿里云 AHAS Sentinel 控制台，您需要用自己的阿里云账号登录。由于安全策略原因我们无法提供公共账号。运行了这个 Demo 之后，这个 Demo 将会向 AHAS Sentinel 控制台上报基本的机器信息；同时 AHAS Sentinel 控制台也将会根据上报的信息，通过 Sentinel Transport API 拉取簇点监控信息。如果用户不想要运行这个 Demo，停止即可。Demo 的所有的源码都开放可以下载。

1. 下载 Demo jar

您可以 点击此处下载 Sentinel 公网 Demo jar 包。

此 Demo Jar 主要包含的内容有：

  1. 本地 demo 客户端 中已有的 sentinel-core；
  2. 接入 AHAS Sentinel 控制台所需的通信模块 ahas-sentinel-client，用于向控制台上报心跳信息。心跳信息、规则和监控均存于您个人的账号下，其它人均无法访问。
  3. 一个简单的 main 函数，程序类似于：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public static void main(String[] args) {
    // 不断进行资源调用.
    while (true) {
        Entry entry = null;
        try {
	    entry = SphU.entry("HelloWorld");
            // 资源中的逻辑.
            System.out.println("hello world");
	} catch (BlockException e1) {
	    System.out.println("blocked!");
	} finally {
	   if (entry != null) {
	       entry.exit();
	   }
	}
    }
}

若您之前接入了开源 Sentinel 控制台，您也可以简单的通过将 pom 文件中 Sentinel 开源相关依赖替换为 ahas-sentinel-client 模块达到同样的目的。

2. 开通 AHAS 流控降级并获取启动参数

接下来您需要到 阿里云控制台 开通 AHAS 功能。可以根据 开通 AHAS 文档 和 流控降级 Demo 快速入门 里面的指引进行开通。

注意：本地运行接入 AHAS Sentinel 控制台需要在页面左上角选择 公网 环境。

开通后您可以点击左侧侧边栏的 应用防护，进入 Sentinel 控制台应用总览页面。在页面右上角，单击添加应用，选择 SDK 接入页签，到 配置启动参数 页签拿到需要的启动参数（详情请参考 SDK 接入文档），类似于：

1
-Dproject.name=AppName -Dahas.license=<License>

其中 project.name 配置项代表应用名（会显示在控制台），ahas.license 配置项代表自己的授权 license（注意保密）。

3. 启动 demo

接下来我们就可以在本地启动 demo 了，启动应用时需要加上拿到的启动参数：

1
java -Dproject.name=<AppName> -Dahas.license=<License> -jar ahas-sentinel-sdk-demo.jar

当应用开始运行后一段时间，我们刷新一下控制台页面，就可以在 AHAS Sentinel 控制台上看到我们的应用了：

image-20230922144005603

点击应用卡片，进入详情页面后点击左侧侧边栏的“机器列表”。我们可以在机器列表页面看到刚刚接入的机器，代表接入成功：

image-20230922144011577

我们可以在监控详情页面查看聚合监控和历史监控图线：

image-20230922144014743

AHAS Sentinel 控制台提供了一个我们推荐的推送规则的做法，即 配置中心控制台/Sentinel 控制台 → 配置中心 → Sentinel 数据源 → Sentinel，这样的流程就非常清晰了：

image-20230922144018707

Sentinel 是什么

Sentinel 是什么

随着微服务的流行，服务和服务之间的稳定性变得越来越重要。Sentinel 是面向分布式服务架构的流量控制组件，主要以流量为切入点，从限流、流量整形、熔断降级、系统负载保护、热点防护等多个维度来帮助开发者保障微服务的稳定性。

Sentinel 的历史

  • 2012 年，Sentinel 诞生，主要功能为入口流量控制。
  • 2013-2017 年，Sentinel 在阿里巴巴集团内部迅速发展，成为基础技术模块，覆盖了所有的核心场景。Sentinel 也因此积累了大量的流量归整场景以及生产实践。
  • 2018 年，Sentinel 开源，并持续演进。
  • 2019 年，Sentinel 朝着多语言扩展的方向不断探索，推出 C++ 原生版本，同时针对 Service Mesh 场景也推出了 Envoy 集群流量控制支持，以解决 Service Mesh 架构下多语言限流的问题。
  • 2020 年，推出 Sentinel Go 版本，继续朝着云原生方向演进。
  • 2021 年，Sentinel 正在朝着 2.0 云原生高可用决策中心组件进行演进；同时推出了 Sentinel Rust 原生版本。

Sentinel 基本概念

资源

资源是 Sentinel 的关键概念。它可以是 Java 应用程序中的任何内容，例如，由应用程序提供的服务，或由应用程序调用的其它应用提供的服务，甚至可以是一段代码。在接下来的文档中，我们都会用资源来描述代码块。

只要通过 Sentinel API 定义的代码，就是资源，能够被 Sentinel 保护起来。大部分情况下，可以使用方法签名，URL，甚至服务名称作为资源名来标示资源。

规则

围绕资源的实时状态设定的规则，可以包括流量控制规则、熔断降级规则以及系统保护规则。所有规则可以动态实时调整。

Sentinel 功能和设计理念

流量控制

什么是流量控制

流量控制在网络传输中是一个常用的概念，它用于调整网络包的发送数据。然而，从系统稳定性角度考虑，在处理请求的速度上，也有非常多的讲究。任意时间到来的请求往往是随机不可控的，而系统的处理能力是有限的。我们需要根据系统的处理能力对流量进行控制。Sentinel 作为一个调配器，可以根据需要把随机的请求调整成合适的形状，如下图所示：

image-20230922144031150

流量控制设计理念

流量控制有以下几个角度:

  • 资源的调用关系，例如资源的调用链路，资源和资源之间的关系；
  • 运行指标，例如 QPS、线程池、系统负载等；
  • 控制的效果，例如直接限流、冷启动、排队等。

Sentinel 的设计理念是让您自由选择控制的角度，并进行灵活组合，从而达到想要的效果。

熔断降级

什么是熔断降级

除了流量控制以外，及时对调用链路中的不稳定因素进行熔断也是 Sentinel 的使命之一。由于调用关系的复杂性，如果调用链路中的某个资源出现了不稳定，可能会导致请求发生堆积，进而导致级联错误。

image-20230922144037362

Sentinel 和 Hystrix 的原则是一致的: 当检测到调用链路中某个资源出现不稳定的表现，例如请求响应时间长或异常比例升高的时候，则对这个资源的调用进行限制，让请求快速失败，避免影响到其它的资源而导致级联故障。

熔断降级设计理念

在限制的手段上，Sentinel 和 Hystrix 采取了完全不一样的方法。

Hystrix 通过 线程池隔离 的方式，来对依赖（在 Sentinel 的概念中对应 资源）进行了隔离。这样做的好处是资源和资源之间做到了最彻底的隔离。缺点是除了增加了线程切换的成本（过多的线程池导致线程数目过多），还需要预先给各个资源做线程池大小的分配。

Sentinel 对这个问题采取了两种手段:

  • 通过并发线程数进行限制

和资源池隔离的方法不同，Sentinel 通过限制资源并发线程的数量，来减少不稳定资源对其它资源的影响。这样不但没有线程切换的损耗，也不需要您预先分配线程池的大小。当某个资源出现不稳定的情况下，例如响应时间变长，对资源的直接影响就是会造成线程数的逐步堆积。当线程数在特定资源上堆积到一定的数量之后，对该资源的新请求就会被拒绝。堆积的线程完成任务后才开始继续接收请求。

  • 通过响应时间对资源进行降级

除了对并发线程数进行控制以外，Sentinel 还可以通过响应时间来快速降级不稳定的资源。当依赖的资源出现响应时间过长后，所有对该资源的访问都会被直接拒绝，直到过了指定的时间窗口之后才重新恢复。

系统自适应保护

Sentinel 同时提供系统维度的自适应保护能力。防止雪崩，是系统防护中重要的一环。当系统负载较高的时候，如果还持续让请求进入，可能会导致系统崩溃，无法响应。在集群环境下，网络负载均衡会把本应这台机器承载的流量转发到其它的机器上去。如果这个时候其它的机器也处在一个边缘状态的时候，这个增加的流量就会导致这台机器也崩溃，最后导致整个集群不可用。

针对这个情况，Sentinel 提供了对应的保护机制，让系统的入口流量和系统的负载达到一个平衡，保证系统在能力范围之内处理最多的请求。

Sentinel 是如何工作的

Sentinel 的主要工作机制如下：

  • 对主流框架提供适配或者显示的 API，来定义需要保护的资源，并提供设施对资源进行实时统计和调用链路分析。
  • 根据预设的规则，结合对资源的实时统计信息，对流量进行控制。同时，Sentinel 提供开放的接口，方便您定义及改变规则。
  • Sentinel 提供实时的监控系统，方便您快速了解目前系统的状态。

如何使用

简介

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

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

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

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

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

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

定义资源

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

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

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

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

1
2
3
4
5
6
7
8
9
// 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 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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();
  }
}

热点参数埋点示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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() 的参数描述：

参数名 类型 解释 默认值
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，这个时候可以根据返回值，进行限流之后的逻辑处理。示例代码如下:

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

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

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

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

1
2
3
4
5
6
7
8
9
10
// 原本的业务方法.
@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 方法。以下是一个简单的示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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 在调用链上是平级关系（处于同一层），而不是嵌套关系：

1
2
3
4
5
6
// 调用链类似于：
// -parent
// ---asyncResource
// ---syncResource
asyncEntry = SphU.asyncEntry(asyncResource);
entry = SphU.entry(normalResource);

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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).
    }
}

此时的调用链就类似于：

1
2
3
-parent
---asyncInvocation
-----handleResultForAsync

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

规则的种类

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

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

流量控制规则 (FlowRule)

流量规则的定义

重要属性：

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

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

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

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

1
2
3
4
5
6
7
8
9
10
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);
}

更多详细内容可以参考 流量控制。

熔断降级规则 (DegradeRule)

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
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);
}

更多详情可以参考 熔断降级。

系统保护规则 (SystemRule)

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

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

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

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

1
2
3
4
5
6
7
private void initSystemRule() {
    List<SystemRule> rules = new ArrayList<>();
    SystemRule rule = new SystemRule();
    rule.setHighestSystemLoad(10);
    rules.add(rule);
    SystemRuleManager.loadRules(rules);
}

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

访问控制规则 (AuthorityRule)

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

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

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

更多详情可以参考 来源访问控制。

热点规则 (ParamFlowRule)

详情可以参考 热点参数限流。

查询更改规则

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

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

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

获取所有热点规则：

1
http://localhost:8719/getParamRules

定制自己的持久化规则

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

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

更多详情请参考 动态规则配置。

规则生效的效果

判断限流降级异常

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

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

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

1
BlockException.isBlockException(Throwable t);

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

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

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 用于记录业务异常。相关方法：

  • traceEntry(Throwable, 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

相关静态方法：

标识进入调用链入口（上下文）：

以下静态方法用于标识调用链路入口，用于区分不同的调用链路：

  • public static Context enter(String contextName)
  • public static Context enter(String contextName, String origin)

其中 contextName 代表调用链路入口名称（上下文名称），origin 代表调用来源名称。默认调用来源为空。返回值类型为 Context，即生成的调用链路上下文对象。

流控规则中若选择“流控方式”为“链路”方式，则入口资源名即为上面的 contextName。

注意：

  • ContextUtil.enter(xxx) 方法仅在调用链路入口处生效，即仅在当前线程的初次调用生效，后面再调用不会覆盖当前线程的调用链路，直到 exit。Context 存于 ThreadLocal 中，因此切换线程时可能会丢掉，如果需要跨线程使用可以结合 runOnContext 方法使用。
  • origin 数量不要太多，否则内存占用会比较大。

退出调用链（清空上下文）：

  • public static void exit()：该方法用于退出调用链，清理当前线程的上下文。

获取当前线程的调用链上下文：

  • public static Context getContext()：获取当前线程的调用链路上下文对象。

在某个调用链上下文中执行代码：

  • public static void runOnContext(Context context, Runnable f)：常用于异步调用链路中 context 的变换。

项目中使用-熔断降级限流

image-20230922144048221

在我们项目中，用户请求通过 hailtaxi-gateway 路由到 hailtaxi-driver 或者 hailtaxi-order ，还有可能在 hailtaxi-order 中使用feign调用hailtaxi-driver ，所以我们有可能在单个服务中实现熔断限流，也有可能要集成feign调用实现熔断限流，还有可能在微服务网关中实现熔断限流。我们接下来一步一步实现每一种熔断限流操作。

SpringBoot集成

如果在SpringBoot项目中使用Sentinel，首先需要引入 spring-cloud-starter-alibaba-sentinel 依赖，并使用 @SentinelResource 标识资源。

在 hailtaxi-driver 工程中引入 spring-cloud-starter-alibaba-sentinel 依赖，依赖如下：

1
2
3
4
5
6
<!--sentinel-->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
            <version>2.2.5.RELEASE</version>
        </dependency>

降级

@SentinelResource定义资源

@SentinelResource 用于定义资源，并提供可选的异常处理和 fallback配置项。

blockHandler/blockHandlerClass

在 hailtaxi-driver 中找到 DriverController 中的 info 方法，用户在打车的时候，会查询司机信息，如果司机不存在，此时会报错，代码改造如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
    /****
     * 司机信息
     */
    @GetMapping(value = "/info/{id}")
//    @RequestMapping(value = "/info/{id}")
    public Driver info(@PathVariable(value = "id")String id,HttpServletRequest request){
        log.info("当前服务占用的端口为:{}",port);
//        int i=1/0;//产生异常
//        Enumeration<String> headerNames = request.getHeaderNames();
//        while (headerNames.hasMoreElements()){
//            String name = headerNames.nextElement();
//            String value = request.getHeader(name);
//            System.out.println(name+":"+value);
//            System.out.println("--------------------------");
//        }
        Driver driver = driverService.findById(id);
        if (driver == null) {
            throw new RuntimeException("司机id="+id+"不存在");
        }
        return driver;
    }

如果此时访问：http://localhost:18081/driver/info/3 查询司机信息，如果没有ID为3的司机信息，会报如下错误，

image-20220424214654226

这种体验非常差，我们可以集成Sentinel使用 @SentinelResource 的 blockHandler 返回默认错误信息，形成降级！！！

1、Sentinel 支持在程序中抛出它定义的 BlockException 异常，该异常会被Sentinel捕获，然后走降级方法，为 info() 方法添加一个 @SentinelResource 注解，用来标注资源，表示当前方法需要执行限流、降级，在注解中添加value属性，用来标注资源，说白了就是给当前资源起个名字，blockHandler用来表示当前方法发生BlockException 异常的时候，将处理流程交给指定的方法blockExHandler() 处理,此时 blockExHandler() 方法必须和抛出异常的方法在同一个类中，这是一种降级操作，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
   @SentinelResource(value = "info",blockHandler = "blockExHandler")
    @GetMapping(value = "/info/{id}")
//    @RequestMapping(value = "/info/{id}")
    public Driver info(@PathVariable(value = "id")String id,HttpServletRequest request)
        throws BlockException { // 必须是BlockException
        log.info("当前服务占用的端口为:{}",port);
//        int i=1/0;//产生异常
//        Enumeration<String> headerNames = request.getHeaderNames();
//        while (headerNames.hasMoreElements()){
//            String name = headerNames.nextElement();
//            String value = request.getHeader(name);
//            System.out.println(name+":"+value);
//            System.out.println("--------------------------");
//        }
        Driver driver = driverService.findById(id);
        if (driver == null) {
//            throw new RuntimeException("司机id="+id+"不存在");
            throw new SystemBlockException("info","司机id="+id+"不存在",null);
        }
        return driver;
    }
    // info资源出现BlockException后的降级处理
    public Driver blockExHandler(String id, BlockException e) {
        Driver driver = new Driver();
        driver.setId(id);
        driver.setName("系统繁忙,稍候再试");
        return driver;
    }

image-20220424215038810

注意：

如果blockHandler方法和资源方法==不在同一个类==中，我们可以在@SentinelResource 中添加 blockHandlerClass 属性，指定降级处理类的方法所在的类，且要求blockHandler方法是静态的，代码如下：

1
@SentinelResource(value = "info",blockHandler = "blockExHandler",blockHandlerClass = "xxx.xxx.Xxxx")

2、启动测试，访问：http://localhost:18081/driver/info/3 测试出错效果如下：

image-20220424215119536

一般业务上都是自定义异常,blockHandler只能是BlockException,一般用fallback

fallback/fallbackClass

1、如果我们希望抛出任何异常都能处理，都能调用默认处理方法，而并非只是 BlockException 异常才调用，此时可以使用 @SentinelResource 的 fallback 属性，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    @GetMapping(value = "/info/{id}")
//    @RequestMapping(value = "/info/{id}")
//    @SentinelResource(value = "info",blockHandler = "blockExHandler")
    @SentinelResource(value = "info"/*,blockHandler = "blockExHandler"*/, fallback = "exHandler")
    public Driver info(@PathVariable(value = "id") String id, HttpServletRequest request)
        throws BlockException {
        log.info("当前服务占用的端口为:{}", port); 
        Driver driver = driverService.findById(id);
        if (driver == null) {
//            throw new RuntimeException("司机id="+id+"不存在");
            throw new SystemBlockException("info", "司机id=" + id + "不存在", null);
        }
        return driver;
    }

    /**
     * info资源出现任何类型异常后的降级处理 * 方法参数可以添加一个Throwable 类型的参数，也可不添加
     */
    public Driver exHandler(String id, Throwable e) {
        Driver driver = new Driver();
        driver.setId(id);
        driver.setName("系统繁忙,稍后再试");
        return driver;
    }

注意：

如果fallback方法和当前的资源方法不在同一个类中，可以使用@SentinelResource 注解的 fallbackClass 实现，也要求fallback方法是静态的，代码如下：

1
@SentinelResource(value = "info",fallback ="exHandler" ,fallbackClass = "xx.xxx.xxx.xx.Xxx")

2、访问 http://localhost:18081/driver/info/3 测试出错效果如下：

image-20220424221337400

defaultFallback

上面无论是 blockHandler 还是 fallback ，每个方法发生异常，都要为方法独立创建一个处理异常的方法，效率非常低，我们可以使用@SentinelResource 注解的 defaultFallback 属性，为一个类指定一个全局的处理错误的方法，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@RestController
@RequestMapping(value = "/driver")
@Slf4j
@RefreshScope
@SentinelResource(defaultFallback = "defaultExHandler")
public class DriverController {
    
    public Driver defaultExHandler(Throwable e) {
        Driver driver = new Driver();
        driver.setName("系统繁忙,稍后再试-defaultHandler");
        return driver;
    }
    /****
     * 司机信息
     */
    @GetMapping(value = "/info/{id}") 
    @SentinelResource(value = "info") 
    public Driver info(@PathVariable(value = "id") String id, HttpServletRequest request)
        throws BlockException {
        log.info("当前服务占用的端口为:{}", port); 
        Driver driver = driverService.findById(id);
        if (driver == null) {
			throw new RuntimeException("司机id="+id+"不存在"); 
        }
        return driver;
    }

访问 http://localhost:18081/driver/info/3 效果如下：

image-20220424221550416

限流

流量控制规则(FlowRule)

QPS流量控制

1、我们先实现基于QPS流量控制，在 hailtaxi-driver 的 DriverApplication 启动类上添加如下方法加载限流规则，当DriverApplication 初始化完成之后加载规则，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@SpringBootApplication
@EnableDiscoveryClient
@MapperScan(basePackages = "com.itheima.driver.mapper")
public class DriverApplication {

    public static void main(String[] args) {
        SpringApplication.run(DriverApplication.class, args);
    }

    // 初始化规则
    @PostConstruct
    private void initFlowQpsRule() {
        //规则集合
        List<FlowRule> rules = new ArrayList<>();
        //定义一个规则
        FlowRule rule = new FlowRule("info");
        // 设置阈值  
        rule.setCount(2);
        //设置限流阈值类型
        rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
        //default，代表不区分调用来源
        rule.setLimitApp("default");
        //设置流控效果 
        rule.setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT);
        //将定义的规则添加到集合中
        rules.add(rule);
        //加载规则
        FlowRuleManager.loadRules(rules);
    }
}

2、访问 http://localhost:18081/driver/info/1 此时不会抛出异常，但是==频繁刷新==，则会调用降级方法，效果如下：

image-20220424223528141

线程数流量控制

1、我们修改限流阈值类型，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
    // 初始化规则
    @PostConstruct
    private void initFlowQpsRule() {
        //规则集合
        List<FlowRule> rules = new ArrayList<>();
        //定义一个规则
        FlowRule rule = new FlowRule("info");
        // 设置阈值
        rule.setCount(2);
        //设置限流阈值类型
        rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
        //default，代表不区分调用来源
        rule.setLimitApp("default");
        //设置流控效果
//        rule.setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT);
        rule.setGrade(RuleConstant.FLOW_GRADE_THREAD);//默认是 qps
        //将定义的规则添加到集合中
        rules.add(rule);
        //加载规则
        FlowRuleManager.loadRules(rules);
    }

这里用浏览器就没办法测试了,没法造成线程并发

2、此时再来访问 http://localhost:18081/driver/info/1 我们发现用浏览器无论怎么访问都不会出现降级现象，但是如果用Jmeter模拟多个线程，效果就不一样了,效果如下：

image-20220424223802156

熔断降级规则(DegradeRule)

1、在 DriverApplication 规则定义如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@PostConstruct
    public void initDegradeRule() {
        List<DegradeRule> rules = new ArrayList<>();
        DegradeRule rule = new DegradeRule();
        // 设置资源名称 
        rule.setResource("info");
        /**
         * 设置熔断策略 
         * DEGRADE_GRADE_RT:平均响应时间 
         * DEGRADE_GRADE_EXCEPTION_RATIO:异常比例数量 
         * DEGRADE_GRADE_EXCEPTION_COUNT:异常数 
         */
        rule.setGrade(RuleConstant.DEGRADE_GRADE_EXCEPTION_COUNT);
        //设置阈值 
        rule.setCount(2);
        //设置 熔断时长 
        rule.setTimeWindow(30);
        // 统计时长（单位为 ms） 默认1000 
        rule.setStatIntervalMs(60 * 1000);
        //将规则添加到集合中 
        rules.add(rule);
        DegradeRuleManager.loadRules(rules);
    }

2、首先访问：http://localhost:18081/driver/info/1 ，确保没问题，其次访问：http://localhost:18081/driver/info/3，多访问几次，造成熔断（5+2=7）然后在访问：http://localhost:18081/driver/info/1，会发现已经有熔断降级效果了，且查看服务控制台，发现不会有信息输出，表明已经熔断了，且从页面展示效果来看走了降级

image-20220424225142513

等待30s后，再次访问：http://localhost:18081/driver/info/1，查看熔断是否结束！

系统保护规则(SystemRule)

系统应用级别的

1、在 hailtaxi-driver 的 DriverApplication 中创建如下方法，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// 系统自我保护
@PostConstruct
private void initSystemRule() {
    // 系统自我保护集合
    List<SystemRule> rules = new ArrayList<>();
    //创建系统自我保护规则
    SystemRule rule = new SystemRule();
    //CPU使用率 值为[0,1],-1 (不生效)
    rule.setHighestCpuUsage(0.2);
    //所有入口资源的 QPS,-1 (不生效)
    rule.setQps(10);
    //入口流量的最大并发数,-1 (不生效)
    rule.setMaxThread(5);
    //所有入口流量的平均响应时间,单位：秒,-1 (不生效)
    rule.setAvgRt(5);
    //load1 触发值，用于触发自适应控制阶段,系统最高负载，建议取值 CPU cores * 2.5
    rule.setHighestSystemLoad(20);
    //将规则加入到集合
    rules.add(rule); 
    SystemRuleManager.loadRules(rules);
}

我们可以测试CPU使用率自我保护，使用 jmeter 测试如下：

image-20220424230101888

访问控制规则 (AuthorityRule)

黑白名单,比如根据ip限制

1、在 hailtaxi-driver 的 DriverApplication 中创建如下方法，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@PostConstruct
public void initAuthorityRule() {
    AuthorityRule rule = new AuthorityRule();
    rule.setResource("info");
    rule.setStrategy(RuleConstant.AUTHORITY_WHITE);
    rule.setLimitApp("127.0.0.1,appB");
    AuthorityRuleManager.loadRules(Collections.singletonList( rule));
}
// Sentinel提供了 RequestOriginParser 接口来处理访问来 源，Sentinel保护的资源如果被访问，
// 就会调用 RequestOriginParser解析访问来源
@Component
public class IpLimiter implements RequestOriginParser {
    @Override
    public String parseOrigin(HttpServletRequest httpServletRequest) {
        return httpServletRequest.getRemoteAddr();
    }
}

2、访问：http://localhost:18081/driver/info/1，不通过，走了降级

访问：http://127.0.0.1:18081/driver/info/1

热点规则 (ParamFlowRule)

1、在 DriverController 中创建一个司机筛选方法，比如根据城市来筛选，在 DriverController 中创建一个方法：

1
2
3
4
5
6
7
8
9
10
11
// 搜素指定城市的司机
@SentinelResource(value = "search")
@GetMapping(value = "/search/{city}")
public Driver search(@PathVariable(value = "city") String city) {
    System.out.println("查询的司机所在城市：" + city);
    //假设查询到了一个司机信息 
    Driver driver = new Driver();
    driver.setName("唐僧老师");
    driver.setId("No.1");
    return driver;
}

2、对热门参数进行控制，对热点数据执行特殊限流，比如资源参数列表中的第一个参数值为 恩施 的时候执行限流，在 DriverApplication 中创建限流配置，代码如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// 热点参数初始化
@PostConstruct
private static void initParamFlowRules() {
    ParamFlowRule rule = new ParamFlowRule("search")
        //参数下标为0
        .setParamIdx(0)
        // 限流模式为QPS
        .setGrade(RuleConstant.FLOW_GRADE_QPS)
        // 统计窗口时间长度（单位为秒）
        .setDurationInSec(10)
        // 流控效果（支持快速失败和匀速排队模式）
        // CONTROL_BEHAVIOR_DEFAULT：限流行为，直接拒绝
        // CONTROL_BEHAVIOR_WARM_UP:限流行为，匀速排队
        // CONTROL_BEHAVIOR_RATE_LIMITER：限流行为，匀速 排队
        .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT)
        //最大排队等待时长（仅在匀速排队模式生效 CONTROL_BEHAVIOR_RATE_LIMITER）
        // .setMaxQueueingTimeMs(600)
        // 最大阈值为5
        .setCount(5);
    // 为特定参数单独设置规则
    // 如下配置：当下标为0的参数值为恩施的时候，阈值到达2的时候则执 行限流
    ParamFlowItem item = new ParamFlowItem()
        //参数类型为String类型
        .setClassType(String.class.getName())
        // 设置阈值为2
        .setCount(2)
        // 需要统计的值
        .setObject(String.valueOf("恩施"));
    rule.setParamFlowItemList(Collections.singletonList(item));
    // 返回的是不可变的集合，但是这个长度的集合只有1，可以减少内存空 间
    //加载热点数据
    ParamFlowRuleManager.loadRules(Collections.singletonList(rule));
}

2、我们访问 http://localhost:18081/driver/search/天津/ 的时候，连续执行5次，才会限流，

我们访问 http://localhost:18081/driver/search/恩施/ 的时候，连续执行2次，就会限流

OpenFeign支持

Sentinel 适配了 Feign 组件。如果想使用，除了外还需要 2 个步骤：

  • 1：引入 spring-cloud-starter-alibaba-sentinel 的依赖
  • 2：加入 spring-cloud-starter-openfeign 依赖
  • 3：配置文件打开 Sentinel 对 Feign 的支持： feign.sentinel.enabled=true

image-20220424231750405

在上面案例中，我们可以实现用户打车成功调用 hailtaxi-order 执行下单，并且通过feign调用 hailtaxi-driver 修改司机状态，此时我们可以使用Sentinel实现Feign调用降级、限流。

注意：

在进行操作之前，可以先将 hailtaxi-driver 中的访问控制规则注释掉，注释掉 DriverApplication#initAuthorityRule ， DriverApplication#initSystemRule 上的注解即可

1、在 hailtaxi-order 中引入 sentinel 和 OpenFeign 依赖，配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
  <!--sentinel-->
  <dependency>
      <groupId>com.alibaba.cloud</groupId>
      <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
      <version>2.2.5.RELEASE</version>
  </dependency>
<!--配置feign-->
  <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-openfeign</artifactId>
      <version>2.2.5.RELEASE</version>
  </dependency>

2、在 hailtaxi-order 的配置文件中开启Feign支持 sentinel ，配置如下：

1
2
3
4
feign:
  #开启Sentinel对Feign的支持 
  sentinel: 
    enabled: true

注意：现在配置信息都存放在了 nacos 中，所以找到 hailtaxi-order.yaml 的Data ID配置，将以上配置添加进去！

image-20220424232158173

注意修改完后一定要发布才能生效！！！

3、因为 hailtaxi-order 要通过 openfeign 去调用 hailtaxi-driver 中的 DriverController#status 方法，改造一下该方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/****
    * 更新司机信息
    */
   @PutMapping(value = "/status/{id}/{status}")
   public Driver status(@PathVariable(value = "id") String id,
                        @PathVariable(value = "status") Integer status,
                        HttpServletRequest request) {
       log.info("当前服务占用的端口为:{}", port); 

       //修改状态
       driverService.update(id, status);
       //修改状态后的司机信息
       Driver driver = driverService.findById(id);
       if (driver == null) {
           throw new RuntimeException("学生id=" + id + ",不存在");
       }
       return driver;
   }

模拟被调用服务出现异常的情况

3、先验证正确性，启动 hailtaxi-gateway ， hailtaxi-order ，hailtaxi-driver 服务，使用postman访问：

http://localhost:8001/order

4、为了测试程序异常能实现降级操作，我们在 hailtaxi-order 中将OrderInfoController.add() 方法的司机ID改成一个不存在的司机ID，让程序报错，测试降级处理，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
/***
 * 下单
 */
@PostMapping
public OrderInfo add(){
    //修改司机信息 司机ID=1
    Driver driver = driverFeign.status("3", 2); // 改成一个不 存在的id

    //创建订单
    OrderInfo orderInfo = new OrderInfo("No"+((int)(Math.random()*10000)), (int)(Math.random()*100), new Date(), "深圳北站", "罗湖港", driver);
    orderInfoService.add(orderInfo);
    return orderInfo;
}

image-20220424232454127

5、再次启动测试：

image-20220424232503212

注意：服务调用出错要进行降级操作有两个地方都可以进行，一是在被调用方进行降级，一是在调用方进行降级，在被调用方进行降级前面已经讲过了，所以接下来讲解如何在调用方（openfeign）结合 sentinel 进行降级处理

fallback

在 hailtaxi-api 模块中找到 DriverFeign 接口：

1、为Feign接口创建一个实现类：

com.itheima.driver.feign.fallback.DriverFeignFallback ，在实现类中处理程序异常降级处理方法，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Component
public class DriverFeignFallback implements DriverFeign {
    /**
     * status()降级处理方法
     */
    @Override
    public Driver status(String id, Integer status) {
        Driver driver = new Driver();
        driver.setId(id);
        driver.setStatus(status);
        driver.setName("系统比较繁忙，请您稍后再试！");
        return driver;
    }
}

2、在 DriverFeign 接口上添加 fallback 属性指定降级处理的类，代码如下：

1
@FeignClient(value = "hailtaxi-driver",fallback = DriverFeignFallback.class)

注意：修改了 hailtaxi-api 模块，最好 clean ， package ！！

3、启动运行，会发生如下问题：

1
java.lang.AbstractMethodError: com.alibaba.cloud.sentinel.feign.SentinelContractHolder.par seAndValidatateMetadata(Ljava/lang/Class;)Ljava/util/List;

出现上面问题的主要原因是当前SpringCloud版本存在问题。

Hoxton.SR1 中， fegin.context 接口方法的定义为parseAndValidatateMetadata

Hoxton.SR3 中， fegin.context 接口方法的定义为parseAndValidateMetadata

我们现在需要把 Hoxton.SR1 换成 Hoxton.SR3 ，因此需要在 hailtaxi-parent 修改SpringCloud版本：

image-20220424232809924

将 SpringCloud 版本升级至 Hoxton.SR3 同时将 SpringBoot 版本升级至2.2.10 ，如上图：

https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-Hoxton-Release-Notes

此时我们测试，效果如下：

image-20220424232831913

fallbackFactory

我们可以为 DriverFeign 接口创建一个降级处理的工厂对象，在工厂对象中处理程序异常降级处理方法，用工厂对象处理可以拿到异常信息，代码如下：

1、创建：

com.itheima.driver.feign.fallback.DriverFeignFallbackFactory

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Slf4j
@Component
public class DriverFeignFallBackFactory implements FallbackFactory<DriverFeign> {
    @Override
    public DriverFeign create(Throwable throwable) {
        return new DriverFeign() {     
            Driver driver = new Driver();
            driver.setId(id);
            driver.setStatus(status);
            driver.setName("系统比较繁忙，请您稍后再试！");
            return driver; 
        };
    }
}

2、在 DriverFeign 接口上添加 fallbackFactory 属性指定讲解处理的类，代码如下：

1
@FeignClient(value = "hailtaxi-driver",fallbackFactory = DriverFeignFallbackFactory.class)

3、再次启动测试，效果如下：

image-20220424232957643

Sentinel集成Gateway

我们的项目流量入口是 SpringCloud Gateway ，因此我们重点讲解Sentinel集成 Gateway 。

image-20220424233546390

我们如果想要让微服务网关集成Sentinel，需要引入依赖包，使用时只需注入对应的 SentinelGatewayFilter 实例以及SentinelGatewayBlockExceptionHandler 实例即可

1
2
3
4
5
6
<!--Sentinel-->
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-spring-cloud-gateway-adapter</artifactId>
    <version>1.8.0</version>
</dependency>

2、实例引入：创建配置类

com.itheima.config.GatewayConfiguration : 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
package com.itheima.config;

import com.alibaba.csp.sentinel.adapter.gateway.common.SentinelGatewayConstants;
import com.alibaba.csp.sentinel.adapter.gateway.common.api.ApiDefinition;
import com.alibaba.csp.sentinel.adapter.gateway.common.api.ApiPathPredicateItem;
import com.alibaba.csp.sentinel.adapter.gateway.common.api.ApiPredicateItem;
import com.alibaba.csp.sentinel.adapter.gateway.common.api.GatewayApiDefinitionManager;
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.GatewayFlowRule;
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.GatewayParamFlowItem;
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.GatewayRuleManager;
import com.alibaba.csp.sentinel.adapter.gateway.sc.SentinelGatewayFilter;
import com.alibaba.csp.sentinel.adapter.gateway.sc.exception.SentinelGatewayBlockExceptionHandler;
import com.alibaba.csp.sentinel.slots.block.RuleConstant;
import java.util.Collections;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.codec.ServerCodecConfigurer;
import org.springframework.web.reactive.result.view.ViewResolver;

@Configuration
public class GatewayConfiguration {

    private final List<ViewResolver> viewResolvers;
    private final ServerCodecConfigurer serverCodecConfigurer;

    public GatewayConfiguration(ObjectProvider<List<ViewResolver>> viewResolversProvider,
                                ServerCodecConfigurer serverCodecConfigurer) {
        this.viewResolvers = viewResolversProvider.getIfAvailable(Collections::emptyList);
        this.serverCodecConfigurer = serverCodecConfigurer;
    }

    @Bean
    @Order(Ordered.HIGHEST_PRECEDENCE)
    public SentinelGatewayBlockExceptionHandler sentinelGatewayBlockExceptionHandler() {
        // Register the block exception handler for Spring Cloud Gateway.
        return new SentinelGatewayBlockExceptionHandler(viewResolvers, serverCodecConfigurer);
    }

    @Bean
    @Order(Ordered.HIGHEST_PRECEDENCE)
    public GlobalFilter sentinelGatewayFilter() {
        return new SentinelGatewayFilter();
    }


    private void initCustomizedApis() {
        Set<ApiDefinition> definitions = new HashSet<>();
        ApiDefinition api1 = new ApiDefinition("customer_api")
            .setPredicateItems(new HashSet<ApiPredicateItem>() {{
                add(new ApiPathPredicateItem().setPattern("/order/**")
                    /**
                     * 匹配策略：
                     * URL_MATCH_STRATEGY_EXACT：url精确匹配
                     * URL_MATCH_STRATEGY_PREFIX：url前缀匹配
                     * URL_MATCH_STRATEGY_REGEX：url正则匹配
                     */
                    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX));
            }});
        definitions.add(api1);
        GatewayApiDefinitionManager.loadApiDefinitions(definitions);
    }

    private void initGatewayRules() {
        Set<GatewayFlowRule> rules = new HashSet<>();

        rules.add(new GatewayFlowRule("hailtaxi-driver") // 资源名称，可以是网关中的 routeid或者用户自定义的 API分组名称
            .setCount(2) // 限流阈值
            .setIntervalSec(10) // 统计时间窗口默认1s
            .setGrade(RuleConstant.FLOW_GRADE_QPS) // 限流模式
            /**
             * 限流行为:
             * CONTROL_BEHAVIOR_RATE_LIMITER 匀速排队
             * CONTROL_BEHAVIOR_DEFAULT 快速失败(默认)
             * CONTROL_BEHAVIOR_WARM_UP：
             * CONTROL_BEHAVIOR_WARM_UP_RATE_LIMITER：
             */
            .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_RATE_LIMITER)
            //匀速排队模式下的最长排队时间，单位是毫秒，仅在匀速排队模式下生效
            .setMaxQueueingTimeoutMs(1000)
            /**
             * 热点参数限流配置
             * 若不设置,该网关规则将会被转换成普通流控规则；否则会转换成热点规则
             */
            .setParamItem(new GatewayParamFlowItem()
                /**
                 * 从请求中提取参数的策略:
                 * PARAM_PARSE_STRATEGY_CLIENT_IP
                 * PARAM_PARSE_STRATEGY_HOST
                 * PARAM_PARSE_STRATEGY_HEADER
                 * PARAM_PARSE_STRATEGY_URL_PARAM
                 */
                .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_URL_PARAM)
                /**
                 * 若提取策略选择 Header 模式或 URL 参数模式，
                 * 则需要指定对应的 header 名称或 URL 参数名称。
                 */
                .setFieldName("token")
                /**
                 * 参数的匹配策略：
                 * PARAM_MATCH_STRATEGY_EXACT
                 * PARAM_MATCH_STRATEGY_PREFIX
                 * PARAM_MATCH_STRATEGY_REGEX
                 * PARAM_MATCH_STRATEGY_CONTAINS
                 */
                .setMatchStrategy(SentinelGatewayConstants.PARAM_MATCH_STRATEGY_EXACT)
                //参数值的匹配模式，只有匹配该模式的请求属性值会纳入统计和流控
                .setPattern("123456") // token=123456 10s内qps达到2次会被限流
            )
        );

        rules.add(new GatewayFlowRule("customer_api")
            /**
             * 规则是针对 API Gateway 的 route（RESOURCE_MODE_ROUTE_ID）
             * 还是用户在 Sentinel 中定义的 API 分组（RESOURCE_MODE_CUSTOM_API_NAME），默认是 route。
             */
            .setResourceMode(SentinelGatewayConstants.RESOURCE_MODE_CUSTOM_API_NAME)
            .setCount(2)
            .setIntervalSec(1)
            .setGrade(RuleConstant.FLOW_GRADE_QPS)
        );
        GatewayRuleManager.loadRules(rules);
    }


}

此时集成就完成了。

3、启动 hailtaxi-gateway ， hailtaxi-drvier ， hailtaxi-order 测试：使用postman测试，

请求： http://localhost:8001/driver/info/1 10秒内请求超过2次会被限流

请求： localhost:8001/order 1秒内qps达到2次会被限流

应用接入Sentinel-dashboard

hailtaxi-gateway接入控制台：

1、引入依赖包：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
    <version>2.2.5.RELEASE</version>
</dependency>

2、在核心配置文件中配置Sentinel控制台服务地址

1
2
3
4
5
6
7
spring: 
  cloud:
    # sentinel 控制台
    sentinel:
      transport:
        port: 8719
        dashboard: 192.168.213.130:8858

注意：

1、这里的 spring.cloud.sentinel.transport.port 端口配置会在应用对应的机器上启动一个 Http Server，该 Server 会与 Sentinel 控制台做交互，比如限流规则拉取。

2、配置信息现在是存储到nacos中，故要在nacos中找到 hailtaxi-gateway.yaml ，进行如下配置

image-20220425000029874

修改之后记得发布！

3、启动各个服务，

此时我们出发一些请求操作，再看Sentinel控制台会多一个服务监控：

image-20220425000047734

可视化管理

实时监控

同一个服务下的所有机器的簇点信息会被汇总，并且秒级地展示在”实时监控”下。

注意: 实时监控仅存储 5 分钟以内的数据，如果需要持久化，需要通过调用实时监控接口来定制。

image-20220425000916155

如果要获取监控数据，直接调用 http://localhost:8719/clusterNode 即可获取，效果如下：

image-20220425000933635

流控规则

我们可以在【流控规则】页面中新增，点击【流控规则】进入页面新增页面，如下图

image-20220425000957612

资源名：其实可以和请求路径保持一致，这里的流控模式为QPS，触发流控执行阈值为1，流控模式为让当前请求的资源快速直白。

这里的参数和我们程序中的参数其实是一样的，如下说明

  • resource：资源名，即限流规则的作用对象
  • count: 限流阈值
  • grade: 限流阈值类型（QPS 或并发线程数）
  • limitApp: 流控针对的调用来源，若为 default 则不区分调用来源
  • strategy: 调用关系限流策略：直接，关联，链路
  • controlBehavior: 流量控制效果（直接拒绝、Warm Up、匀速排队）

我们测试效果如下：

image-20220425001022799

降级规则

我们可以选择 降级规则>新增降级规则 ，如下图：

image-20220425001045571

降级规则的熔断策略有3种，分别是慢调用比例、异常比例、异常数，和程序中是一样的。

热点数据

热点即经常访问的数据。很多时候我们希望统计某个热点数据中访问频次最高的 Top K 数据，并对其访问进行限制

image-20220425001107017

规则-流量控制

概述

流量控制（flow control），其原理是监控应用流量的 QPS 或并发线程数等指标，当达到指定的阈值时对流量进行控制，以避免被瞬时的流量高峰冲垮，从而保障应用的高可用性。

FlowSlot 会根据预设的规则，结合前面 NodeSelectorSlot、ClusterBuilderSlot、StatisticSlot 统计出来的实时信息进行流量控制。

限流的直接表现是在执行 Entry nodeA = SphU.entry(resourceName) 的时候抛出 FlowException 异常。FlowException 是 BlockException 的子类，您可以捕捉 BlockException 来自定义被限流之后的处理逻辑。

同一个资源可以创建多条限流规则。FlowSlot 会对该资源的所有限流规则依次遍历，直到有规则触发限流或者所有规则遍历完毕。

一条限流规则主要由下面几个因素组成，我们可以组合这些元素来实现不同的限流效果：

  • resource：资源名，即限流规则的作用对象
  • count: 限流阈值
  • grade: 限流阈值类型（QPS 或并发线程数）
  • limitApp: 流控针对的调用来源，若为 default 则不区分调用来源
  • strategy: 调用关系限流策略
  • controlBehavior: 流量控制效果（直接拒绝、Warm Up、匀速排队）

基于QPS/并发数的流量控制

流量控制主要有两种统计类型，一种是统计并发线程数，另外一种则是统计 QPS。类型由 FlowRule 的 grade 字段来定义。其中，0 代表根据并发数量来限流，1 代表根据 QPS 来进行流量控制。其中线程数、QPS 值，都是由 StatisticSlot 实时统计获取的。

我们可以通过下面的命令查看实时统计信息：

1
curl http://localhost:8719/cnode?id=resourceName

输出内容格式如下：

1
2
idx id     thread  pass  blocked   success  total Rt   1m-pass   1m-block   1m-all   exception
2   abc647    0     46      0         46      46   1     2763       0         2763     0

其中：

  • thread： 代表当前处理该资源的并发数；
  • pass： 代表一秒内到来到的请求；
  • blocked： 代表一秒内被流量控制的请求数量；
  • success： 代表一秒内成功处理完的请求；
  • total： 代表到一秒内到来的请求以及被阻止的请求总和；
  • RT： 代表一秒内该资源的平均响应时间；
  • 1m-pass： 则是一分钟内到来的请求；
  • 1m-block： 则是一分钟内被阻止的请求；
  • 1m-all： 则是一分钟内到来的请求和被阻止的请求的总和；
  • exception： 则是一秒内业务本身异常的总和。

并发线程数控制

并发数控制用于保护业务线程池不被慢调用耗尽。例如，当应用所依赖的下游应用由于某种原因导致服务不稳定、响应延迟增加，对于调用者来说，意味着吞吐量下降和更多的线程数占用，极端情况下甚至导致线程池耗尽。为应对太多线程占用的情况，业内有使用隔离的方案，比如通过不同业务逻辑使用不同线程池来隔离业务自身之间的资源争抢（线程池隔离）。这种隔离方案虽然隔离性比较好，但是代价就是线程数目太多，线程上下文切换的 overhead 比较大，特别是对低延时的调用有比较大的影响。Sentinel 并发控制不负责创建和管理线程池，而是简单统计当前请求上下文的线程数目（正在执行的调用数目），如果超出阈值，新的请求会被立即拒绝，效果类似于信号量隔离。并发数控制通常在调用端进行配置。

例子参见：ThreadDemo

QPS流量控制

当 QPS 超过某个阈值的时候，则采取措施进行流量控制。流量控制的效果包括以下几种：直接拒绝、Warm Up、匀速排队。对应 FlowRule 中的 controlBehavior 字段。

注意：若使用除了直接拒绝之外的流量控制效果，则调用关系限流策略（strategy）会被忽略。

直接拒绝

直接拒绝（RuleConstant.CONTROL_BEHAVIOR_DEFAULT）方式是默认的流量控制方式，当QPS超过任意规则的阈值后，新的请求就会被立即拒绝，拒绝方式为抛出FlowException。这种方式适用于对系统处理能力确切已知的情况下，比如通过压测确定了系统的准确水位时。具体的例子参见 FlowQpsDemo。

Warm Up

Warm Up（RuleConstant.CONTROL_BEHAVIOR_WARM_UP）方式，即预热/冷启动方式。当系统长期处于低水位的情况下，当流量突然增加时，直接把系统拉升到高水位可能瞬间把系统压垮。通过”冷启动”，让通过的流量缓慢增加，在一定时间内逐渐增加到阈值上限，给冷系统一个预热的时间，避免冷系统被压垮。详细文档可以参考 流量控制 - Warm Up 文档，具体的例子可以参见 WarmUpFlowDemo。

通常冷启动的过程系统允许通过的 QPS 曲线如下图所示：

image-20230922144351551

匀速排队

匀速排队（RuleConstant.CONTROL_BEHAVIOR_RATE_LIMITER）方式会严格控制请求通过的间隔时间，也即是让请求以均匀的速度通过，对应的是漏桶算法。详细文档可以参考 流量控制 - 匀速器模式，具体的例子可以参见 PaceFlowDemo。

该方式的作用如下图所示：

image-20230922144400281

这种方式主要用于处理间隔性突发的流量，例如消息队列。想象一下这样的场景，在某一秒有大量的请求到来，而接下来的几秒则处于空闲状态，我们希望系统能够在接下来的空闲期间逐渐处理这些请求，而不是在第一秒直接拒绝多余的请求。

注意：匀速排队模式暂时不支持 QPS > 1000 的场景。

基于调用关系的流量控制

调用关系包括调用方、被调用方；一个方法又可能会调用其它方法，形成一个调用链路的层次关系。Sentinel 通过 NodeSelectorSlot 建立不同资源间的调用的关系，并且通过 ClusterBuilderSlot 记录每个资源的实时统计信息。

有了调用链路的统计信息，我们可以衍生出多种流量控制手段。

根据调用方限流

ContextUtil.enter(resourceName, origin) 方法中的 origin 参数标明了调用方身份。这些信息会在 ClusterBuilderSlot 中被统计。可通过以下命令来展示不同的调用方对同一个资源的调用数据：

1
curl http://localhost:8719/origin?id=nodeA

调用数据示例：

1
2
3
4
id: nodeA
idx origin  threadNum passedQps blockedQps totalQps aRt   1m-passed 1m-blocked 1m-total 
1   caller1 0         0         0          0        0     0         0          0
2   caller2 0         0         0          0        0     0         0          0

上面这个命令展示了资源名为 nodeA 的资源被两个不同的调用方调用的统计。

流控规则中的 limitApp 字段用于根据调用来源进行流量控制。该字段的值有以下三种选项，分别对应不同的场景：

  • default：表示不区分调用者，来自任何调用者的请求都将进行限流统计。如果这个资源名的调用总和超过了这条规则定义的阈值，则触发限流。
  • {some_origin_name}：表示针对特定的调用者，只有来自这个调用者的请求才会进行流量控制。例如 NodeA 配置了一条针对调用者caller1的规则，那么当且仅当来自 caller1 对 NodeA 的请求才会触发流量控制。
  • other：表示针对除 {some_origin_name} 以外的其余调用方的流量进行流量控制。例如，资源NodeA配置了一条针对调用者 caller1 的限流规则，同时又配置了一条调用者为 other 的规则，那么任意来自非 caller1 对 NodeA 的调用，都不能超过 other 这条规则定义的阈值。

同一个资源名可以配置多条规则，规则的生效顺序为：**{some_origin_name} > other > default**

注意：调用来源的数目不要太多（一般不要超过几百个），否则内存占用会非常多（调用来源的统计节点最大数目=资源数目*来源数目）。

根据调用链路入口限流：链路限流

NodeSelectorSlot 中记录了资源之间的调用链路，这些资源通过调用关系，相互之间构成一棵调用树。这棵树的根节点是一个名字为 machine-root 的虚拟节点，调用链的入口都是这个虚节点的子节点。

一棵典型的调用树如下图所示：

1
2
3
4
5
6
7
          machine-root
              /       \
             /         \
       Entrance1     Entrance2
          /             \
         /               \
DefaultNode(nodeA)   DefaultNode(nodeA)

上图中来自入口 Entrance1 和 Entrance2 的请求都调用到了资源 NodeA，Sentinel 允许只根据某个入口的统计信息对资源限流。比如我们可以设置 strategy 为 RuleConstant.STRATEGY_CHAIN，同时设置 refResource 为 Entrance1 来表示只有从入口 Entrance1 的调用才会记录到 NodeA 的限流统计当中，而不关心经 Entrance2 到来的调用。

调用链的入口（上下文）是通过 API 方法 ContextUtil.enter(contextName) 定义的，其中 contextName 即对应调用链路入口名称。详情可以参考 ContextUtil 文档。

具有关系的资源流量控制：关联流量控制

当两个资源之间具有资源争抢或者依赖关系的时候，这两个资源便具有了关联。比如对数据库同一个字段的读操作和写操作存在争抢，读的速度过高会影响写得速度，写的速度过高会影响读的速度。如果放任读写操作争抢资源，则争抢本身带来的开销会降低整体的吞吐量。可使用关联限流来避免具有关联关系的资源之间过度的争抢，举例来说，read_db 和 write_db 这两个资源分别代表数据库读写，我们可以给 read_db 设置限流规则来达到写优先的目的：设置 strategy 为 RuleConstant.STRATEGY_RELATE 同时设置 refResource 为 write_db。这样当写库操作过于频繁时，读数据的请求会被限流。

规则-熔断降级

概述

除了流量控制以外，对调用链路中不稳定的资源进行熔断降级也是保障高可用的重要措施之一。一个服务常常会调用别的模块，可能是另外的一个远程服务、数据库，或者第三方 API 等。例如，支付的时候，可能需要远程调用银联提供的 API；查询某个商品的价格，可能需要进行数据库查询。然而，这个被依赖服务的稳定性是不能保证的。如果依赖的服务出现了不稳定的情况，请求的响应时间变长，那么调用服务的方法的响应时间也会变长，线程会产生堆积，最终可能耗尽业务自身的线程池，服务本身也变得不可用。

image-20230922144342514

现代微服务架构都是分布式的，由非常多的服务组成。不同服务之间相互调用，组成复杂的调用链路。以上的问题在链路调用中会产生放大的效果。复杂链路上的某一环不稳定，就可能会层层级联，最终导致整个链路都不可用。因此我们需要对不稳定的弱依赖服务调用进行熔断降级，暂时切断不稳定调用，避免局部不稳定因素导致整体的雪崩。熔断降级作为保护自身的手段，通常在客户端（调用端）进行配置。

注意：本文档针对 Sentinel 1.8.0 及以上版本。1.8.0 版本对熔断降级特性进行了全新的改进升级，请使用最新版本以更好地利用熔断降级的能力。

熔断策略

Sentinel 提供以下几种熔断策略：

  • 慢调用比例 (SLOW_REQUEST_RATIO)：选择以慢调用比例作为阈值，需要设置允许的慢调用 RT（即最大的响应时间），请求的响应时间大于该值则统计为慢调用。当单位统计时长（statIntervalMs）内请求数目大于设置的最小请求数目，并且慢调用的比例大于阈值，则接下来的熔断时长内请求会自动被熔断。经过熔断时长后熔断器会进入探测恢复状态（HALF-OPEN 状态），若接下来的一个请求响应时间小于设置的慢调用 RT 则结束熔断，若大于设置的慢调用 RT 则会再次被熔断。
  • 异常比例 (ERROR_RATIO)：当单位统计时长（statIntervalMs）内请求数目大于设置的最小请求数目，并且异常的比例大于阈值，则接下来的熔断时长内请求会自动被熔断。经过熔断时长后熔断器会进入探测恢复状态（HALF-OPEN 状态），若接下来的一个请求成功完成（没有错误）则结束熔断，否则会再次被熔断。异常比率的阈值范围是 [0.0, 1.0]，代表 0% - 100%。
  • 异常数 (ERROR_COUNT)：当单位统计时长内的异常数目超过阈值之后会自动进行熔断。经过熔断时长后熔断器会进入探测恢复状态（HALF-OPEN 状态），若接下来的一个请求成功完成（没有错误）则结束熔断，否则会再次被熔断。

注意异常降级仅针对业务异常，对 Sentinel 限流降级本身的异常（BlockException）不生效。为了统计异常比例或异常数，需要通过 Tracer.trace(ex) 记录业务异常。示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Entry entry = null;
try {
  entry = SphU.entry(key, EntryType.IN, key);

  // Write your biz code here.
  // <<BIZ CODE>>
} catch (Throwable t) {
  if (!BlockException.isBlockException(t)) {
    Tracer.trace(t);
  }
} finally {
  if (entry != null) {
    entry.exit();
  }
}

开源整合模块，如 Sentinel Dubbo Adapter, Sentinel Web Servlet Filter 或 @SentinelResource 注解会自动统计业务异常，无需手动调用。

熔断降级规则说明

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

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

熔断器事件监听

Sentinel 支持注册自定义的事件监听器监听熔断器状态变换事件（state change event）。示例：

1
2
3
4
5
6
7
8
9
10
11
EventObserverRegistry.getInstance().addStateChangeObserver("logging",
    (prevState, newState, rule, snapshotValue) -> {
        if (newState == State.OPEN) {
            // 变换至 OPEN state 时会携带触发时的值
            System.err.println(String.format("%s -> OPEN at %d, snapshotValue=%.2f", prevState.name(),
                TimeUtil.currentTimeMillis(), snapshotValue));
        } else {
            System.err.println(String.format("%s -> %s at %d", prevState.name(), newState.name(),
                TimeUtil.currentTimeMillis()));
        }
    });

示例

慢调用比例熔断示例：SlowRatioCircuitBreakerDemo

规则-系统自适应限流

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

背景

在开始之前，我们先了解一下系统保护的目的：

  • 保证系统不被拖垮
  • 在系统稳定的前提下，保持系统的吞吐量

长期以来，系统保护的思路是根据硬指标，即系统的负载 (load1) 来做系统过载保护。当系统负载高于某个阈值，就禁止或者减少流量的进入；当 load 开始好转，则恢复流量的进入。这个思路给我们带来了不可避免的两个问题：

  • load 是一个“结果”，如果根据 load 的情况来调节流量的通过率，那么就始终有延迟性。也就意味着通过率的任何调整，都会过一段时间才能看到效果。当前通过率是使 load 恶化的一个动作，那么也至少要过 1 秒之后才能观测到；同理，如果当前通过率调整是让 load 好转的一个动作，也需要 1 秒之后才能继续调整，这样就浪费了系统的处理能力。所以我们看到的曲线，总是会有抖动。
  • 恢复慢。想象一下这样的一个场景（真实），出现了这样一个问题，下游应用不可靠，导致应用 RT 很高，从而 load 到了一个很高的点。过了一段时间之后下游应用恢复了，应用 RT 也相应减少。这个时候，其实应该大幅度增大流量的通过率；但是由于这个时候 load 仍然很高，通过率的恢复仍然不高。

TCP BBR 的思想给了我们一个很大的启发。我们应该根据系统能够处理的请求，和允许进来的请求，来做平衡，而不是根据一个间接的指标（系统 load）来做限流。最终我们追求的目标是 在系统不被拖垮的情况下，提高系统的吞吐率，而不是 load 一定要到低于某个阈值。如果我们还是按照固有的思维，超过特定的 load 就禁止流量进入，系统 load 恢复就放开流量，这样做的结果是无论我们怎么调参数，调比例，都是按照果来调节因，都无法取得良好的效果。

Sentinel 在系统自适应保护的做法是，用 load1 作为启动自适应保护的因子，而允许通过的流量由处理请求的能力，即请求的响应时间以及当前系统正在处理的请求速率来决定。

系统规则

系统保护规则是从应用级别的入口流量进行控制，从单台机器的 load、CPU 使用率、平均 RT、入口 QPS 和并发线程数等几个维度监控应用指标，让系统尽可能跑在最大吞吐量的同时保证系统整体的稳定性。

系统保护规则是应用整体维度的，而不是资源维度的，并且仅对入口流量生效。入口流量指的是进入应用的流量（EntryType.IN），比如 Web 服务或 Dubbo 服务端接收的请求，都属于入口流量。

系统规则支持以下的模式：

  • Load 自适应（仅对 Linux/Unix-like 机器生效）：系统的 load1 作为启发指标，进行自适应系统保护。当系统 load1 超过设定的启发值，且系统当前的并发线程数超过估算的系统容量时才会触发系统保护（BBR 阶段）。系统容量由系统的 maxQps * minRt 估算得出。设定参考值一般是 CPU cores * 2.5。
  • CPU usage（1.5.0+ 版本）：当系统 CPU 使用率超过阈值即触发系统保护（取值范围 0.0-1.0），比较灵敏。
  • 平均 RT：当单台机器上所有入口流量的平均 RT 达到阈值即触发系统保护，单位是毫秒。
  • 并发线程数：当单台机器上所有入口流量的并发线程数达到阈值即触发系统保护。
  • 入口 QPS：当单台机器上所有入口流量的 QPS 达到阈值即触发系统保护。

原理

先用经典图来镇楼:

image-20230922144323789

我们把系统处理请求的过程想象为一个水管，到来的请求是往这个水管灌水，当系统处理顺畅的时候，请求不需要排队，直接从水管中穿过，这个请求的RT是最短的；反之，当请求堆积的时候，那么处理请求的时间则会变为：排队时间 + 最短处理时间。

  • 推论一: 如果我们能够保证水管里的水量，能够让水顺畅的流动，则不会增加排队的请求；也就是说，这个时候的系统负载不会进一步恶化。

我们用 T 来表示(水管内部的水量)，用RT来表示请求的处理时间，用P来表示进来的请求数，那么一个请求从进入水管道到从水管出来，这个水管会存在 P * RT　个请求。换一句话来说，当 T ≈ QPS * Avg(RT) 的时候，我们可以认为系统的处理能力和允许进入的请求个数达到了平衡，系统的负载不会进一步恶化。

接下来的问题是，水管的水位是可以达到了一个平衡点，但是这个平衡点只能保证水管的水位不再继续增高，但是还面临一个问题，就是在达到平衡点之前，这个水管里已经堆积了多少水。如果之前水管的水已经在一个量级了，那么这个时候系统允许通过的水量可能只能缓慢通过，RT会大，之前堆积在水管里的水会滞留；反之，如果之前的水管水位偏低，那么又会浪费了系统的处理能力。

  • 推论二:　当保持入口的流量是水管出来的流量的最大的值的时候，可以最大利用水管的处理能力。

然而，和 TCP BBR 的不一样的地方在于，还需要用一个系统负载的值（load1）来激发这套机制启动。

注：这种系统自适应算法对于低 load 的请求，它的效果是一个“兜底”的角色。对于不是应用本身造成的 load 高的情况（如其它进程导致的不稳定的情况），效果不明显。

示例

我们提供了系统自适应限流的示例：SystemGuardDemo。

规则-黑白名单控制

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

调用方信息通过 ContextUtil.enter(resourceName, origin) 方法中的 origin 参数传入。

规则配置

来源访问控制规则（AuthorityRule）非常简单，主要有以下配置项：

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

示例

比如我们希望控制对资源 test 的访问设置白名单，只有来源为 appA 和 appB 的请求才可通过，则可以配置如下白名单规则：

1
2
3
4
5
AuthorityRule rule = new AuthorityRule();
rule.setResource("test");
rule.setStrategy(RuleConstant.AUTHORITY_WHITE);
rule.setLimitApp("appA,appB");
AuthorityRuleManager.loadRules(Collections.singletonList(rule));

详细示例请参考 AuthorityDemo.

规则-热点参数限流

Overview

何为热点？热点即经常访问的数据。很多时候我们希望统计某个热点数据中访问频次最高的 Top K 数据，并对其访问进行限制。比如：

  • 商品 ID 为参数，统计一段时间内最常购买的商品 ID 并进行限制
  • 用户 ID 为参数，针对一段时间内频繁访问的用户 ID 进行限制

热点参数限流会统计传入参数中的热点参数，并根据配置的限流阈值与模式，对包含热点参数的资源调用进行限流。热点参数限流可以看做是一种特殊的流量控制，仅对包含热点参数的资源调用生效。

image-20230922144134026

Sentinel 利用 LRU 策略统计最近最常访问的热点参数，结合令牌桶算法来进行参数级别的流控。热点参数限流支持集群模式。

基本使用

要使用热点参数限流功能，需要引入以下依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-parameter-flow-control</artifactId>
    <version>x.y.z</version>
</dependency>

然后为对应的资源配置热点参数限流规则，并在 entry 的时候传入相应的参数，即可使热点参数限流生效。

注：若自行扩展并注册了自己实现的 SlotChainBuilder，并希望使用热点参数限流功能，则可以在 chain 里面合适的地方插入 ParamFlowSlot。

那么如何传入对应的参数以便 Sentinel 统计呢？我们可以通过 SphU 类里面几个 entry 重载方法来传入：

1
2
3
public static Entry entry(String name, EntryType type, int count, Object... args) throws BlockException

public static Entry entry(Method method, EntryType type, int count, Object... args) throws BlockException

其中最后的一串 args 就是要传入的参数，有多个就按照次序依次传入。比如要传入两个参数 paramA 和 paramB，则可以：

1
2
3
// paramA in index 0, paramB in index 1.
// 若需要配置例外项或者使用集群维度流控，则传入的参数只支持基本类型。
SphU.entry(resourceName, EntryType.IN, 1, paramA, paramB);

注意：若 entry 的时候传入了热点参数，那么 exit 的时候也一定要带上对应的参数（exit(count, args)），否则可能会有统计错误。正确的示例：

1
2
3
4
5
6
7
8
9
10
11
Entry entry = null;
try {
    entry = SphU.entry(resourceName, EntryType.IN, 1, paramA, paramB);
    // Your logic here.
} catch (BlockException ex) {
    // Handle request rejection.
} finally {
    if (entry != null) {
        entry.exit(1, paramA, paramB);
    }
}

对于 @SentinelResource 注解方式定义的资源，若注解作用的方法上有参数，Sentinel 会将它们作为参数传入 SphU.entry(res, args)。比如以下的方法里面 uid 和 type 会分别作为第一个和第二个参数传入 Sentinel API，从而可以用于热点规则判断：

1
2
3
4
@SentinelResource("myMethod")
public Result doSomething(String uid, int type) {
  // some logic here...
}

注意：目前 Sentinel 自带的 adapter 仅 Dubbo 方法埋点带了热点参数，其它适配模块（如 Web）默认不支持热点规则，可通过自定义埋点方式指定新的资源名并传入希望的参数。注意自定义埋点的资源名不要和适配模块生成的资源名重复，否则会导致重复统计。

热点参数规则

热点参数规则（ParamFlowRule）类似于流量控制规则（FlowRule）：

属性 说明 默认值
resource 资源名，必填
count 限流阈值，必填
grade 限流模式 QPS 模式
durationInSec 统计窗口时间长度（单位为秒），1.6.0 版本开始支持 1s
controlBehavior 流控效果（支持快速失败和匀速排队模式），1.6.0 版本开始支持 快速失败
maxQueueingTimeMs 最大排队等待时长（仅在匀速排队模式生效），1.6.0 版本开始支持 0ms
paramIdx 热点参数的索引，必填，对应 SphU.entry(xxx, args) 中的参数索引位置
paramFlowItemList 参数例外项，可以针对指定的参数值单独设置限流阈值，不受前面 count 阈值的限制。仅支持基本类型和字符串类型
clusterMode 是否是集群参数流控规则 false
clusterConfig 集群流控相关配置

我们可以通过 ParamFlowRuleManager 的 loadRules 方法更新热点参数规则，下面是一个示例：

1
2
3
4
5
6
7
8
9
10
ParamFlowRule rule = new ParamFlowRule(resourceName)
    .setParamIdx(0)
    .setCount(5);
// 针对 int 类型的参数 PARAM_B，单独设置限流 QPS 阈值为 10，而不是全局的阈值 5.
ParamFlowItem item = new ParamFlowItem().setObject(String.valueOf(PARAM_B))
    .setClassType(int.class.getName())
    .setCount(10);
rule.setParamFlowItemList(Collections.singletonList(item));

ParamFlowRuleManager.loadRules(Collections.singletonList(rule));

示例

示例可参见 sentinel-demo-parameter-flow-control。

热点参数监控

可以参考 AHAS Sentinel 热点监控能力。

image-20230922144409339

动态规则扩展

规则

Sentinel 的理念是开发者只需要关注资源的定义，当资源定义成功后可以动态增加各种流控降级规则。Sentinel 提供两种方式修改规则：

  • 通过 API 直接修改 (loadRules)
  • 通过 DataSource 适配不同数据源修改

手动通过 API 修改比较直观，可以通过以下几个 API 修改不同的规则：

1
2
FlowRuleManager.loadRules(List<FlowRule> rules); // 修改流控规则
DegradeRuleManager.loadRules(List<DegradeRule> rules); // 修改降级规则

手动修改规则（硬编码方式）一般仅用于测试和演示，生产上一般通过动态规则源的方式来动态管理规则。

DataSource 扩展

上述 loadRules() 方法只接受内存态的规则对象，但更多时候规则存储在文件、数据库或者配置中心当中。DataSource 接口给我们提供了对接任意配置源的能力。相比直接通过 API 修改规则，实现 DataSource 接口是更加可靠的做法。

我们推荐通过控制台设置规则后将规则推送到统一的规则中心，客户端实现 ReadableDataSource 接口端监听规则中心实时获取变更，流程如下：

image-20230922144145891

DataSource 扩展常见的实现方式有:

  • 拉模式：客户端主动向某个规则管理中心定期轮询拉取规则，这个规则中心可以是 RDBMS、文件，甚至是 VCS 等。这样做的方式是简单，缺点是无法及时获取变更；
  • 推模式：规则中心统一推送，客户端通过注册监听器的方式时刻监听变化，比如使用 Nacos、Zookeeper 等配置中心。这种方式有更好的实时性和一致性保证。

Sentinel 目前支持以下数据源扩展：

拉模式拓展

实现拉模式的数据源最简单的方式是继承 AutoRefreshDataSource 抽象类，然后实现 readSource() 方法，在该方法里从指定数据源读取字符串格式的配置数据。比如 基于文件的数据源。

推模式拓展

实现推模式的数据源最简单的方式是继承 AbstractDataSource 抽象类，在其构造方法中添加监听器，并实现 readSource() 从指定数据源读取字符串格式的配置数据。比如 基于 Nacos 的数据源。

控制台通常需要做一些改造来直接推送应用维度的规则到配置中心。功能示例可以参考 AHAS Sentinel 控制台的规则推送功能。改造指南可以参考 在生产环境中使用 Sentinel 控制台。

注册数据源

通常需要调用以下方法将数据源注册至指定的规则管理器中：

1
2
ReadableDataSource<String, List<FlowRule>> flowRuleDataSource = new NacosDataSource<>(remoteAddress, groupId, dataId, parser);
FlowRuleManager.register2Property(flowRuleDataSource.getProperty());

若不希望手动注册数据源，可以借助 Sentinel 的 InitFunc SPI 扩展接口。只需要实现自己的 InitFunc 接口，在 init 方法中编写注册数据源的逻辑。比如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package com.test.init;

public class DataSourceInitFunc implements InitFunc {

    @Override
    public void init() throws Exception {
        final String remoteAddress = "localhost";
        final String groupId = "Sentinel:Demo";
        final String dataId = "com.alibaba.csp.sentinel.demo.flow.rule";

        ReadableDataSource<String, List<FlowRule>> flowRuleDataSource = new NacosDataSource<>(remoteAddress, groupId, dataId,
            source -> JSON.parseObject(source, new TypeReference<List<FlowRule>>() {}));
        FlowRuleManager.register2Property(flowRuleDataSource.getProperty());
    }
}

接着将对应的类名添加到位于资源目录（通常是 resource 目录）下的 META-INF/services 目录下的 com.alibaba.csp.sentinel.init.InitFunc 文件中，比如：

1
com.test.init.DataSourceInitFunc

这样，当初次访问任意资源的时候，Sentinel 就可以自动去注册对应的数据源了。

示例

API 模式：使用客户端规则 API 配置规则

Sentinel Dashboard 通过客户端自带的规则 API来实时查询和更改内存中的规则。

注意: 要使客户端具备规则 API，需在客户端引入以下依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-transport-simple-http</artifactId>
    <version>x.y.z</version>
</dependency>

拉模式：使用文件配置规则

这个示例展示 Sentinel 是如何从文件获取规则信息的。FileRefreshableDataSource 会周期性的读取文件以获取规则，当文件有更新时会及时发现，并将规则更新到内存中。使用时只需添加以下依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-datasource-extension</artifactId>
    <version>x.y.z</version>
</dependency>

推模式：使用 Nacos 配置规则

Nacos 是阿里中间件团队开源的服务发现和动态配置中心。Sentinel 针对 Nacos 作了适配，底层可以采用 Nacos 作为规则配置数据源。使用时只需添加以下依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-datasource-nacos</artifactId>
    <version>x.y.z</version>
</dependency>

然后创建 NacosDataSource 并将其注册至对应的 RuleManager 上即可。比如：

1
2
3
4
5
// remoteAddress 代表 Nacos 服务端的地址
// groupId 和 dataId 对应 Nacos 中相应配置
ReadableDataSource<String, List<FlowRule>> flowRuleDataSource = new NacosDataSource<>(remoteAddress, groupId, dataId,
    source -> JSON.parseObject(source, new TypeReference<List<FlowRule>>() {}));
FlowRuleManager.register2Property(flowRuleDataSource.getProperty());

详细示例可以参见 sentinel-demo-nacos-datasource。

推模式：使用 ZooKeeper 配置规则

Sentinel 针对 ZooKeeper 作了相应适配，底层可以采用 ZooKeeper 作为规则配置数据源。使用时只需添加以下依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-datasource-zookeeper</artifactId>
    <version>x.y.z</version>
</dependency>

然后创建 ZookeeperDataSource 并将其注册至对应的 RuleManager 上即可。比如：

1
2
3
4
// remoteAddress 代表 ZooKeeper 服务端的地址
// path 对应 ZK 中的数据路径
ReadableDataSource<String, List<FlowRule>> flowRuleDataSource = new ZookeeperDataSource<>(remoteAddress, path, source -> JSON.parseObject(source, new TypeReference<List<FlowRule>>() {}));
FlowRuleManager.register2Property(flowRuleDataSource.getProperty());

详细示例可以参见 sentinel-demo-zookeeper-datasource。

推模式：使用 Apollo 配置规则

Sentinel 针对 Apollo 作了相应适配，底层可以采用 Apollo 作为规则配置数据源。使用时只需添加以下依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-datasource-apollo</artifactId>
    <version>x.y.z</version>
</dependency>

然后创建 ApolloDataSource 并将其注册至对应的 RuleManager 上即可。比如：

1
2
3
4
5
// namespaceName 对应 Apollo 的命名空间名称
// ruleKey 对应规则存储的 key
// defaultRules 对应连接不上 Apollo 时的默认规则
ReadableDataSource<String, List<FlowRule>> flowRuleDataSource = new ApolloDataSource<>(namespaceName, ruleKey, defaultRules, source -> JSON.parseObject(source, new TypeReference<List<FlowRule>>() {}));
FlowRuleManager.register2Property(flowRuleDataSource.getProperty());

详细示例可以参见 sentinel-demo-apollo-datasource。

推模式：使用 Redis 配置规则

Sentinel 针对 Redis 作了相应适配，底层可以采用 Redis 作为规则配置数据源。使用时只需添加以下依赖：

1
2
3
4
5
6
<!-- 仅支持 JDK 1.8+ -->
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-datasource-redis</artifactId>
    <version>x.y.z</version>
</dependency>

Redis 动态配置源采用 Redis PUB-SUB 机制实现，详细文档参考：https://github.com/alibaba/Sentinel/tree/master/sentinel-extension/sentinel-datasource-redis

注解支持

Sentinel 提供了 @SentinelResource 注解用于定义资源，并提供了 AspectJ 的扩展用于自动定义资源、处理 BlockException 等。使用 Sentinel Annotation AspectJ Extension 的时候需要引入以下依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-annotation-aspectj</artifactId>
    <version>x.y.z</version>
</dependency>

@SentinelResource 注解

注意：注解方式埋点不支持 private 方法。

@SentinelResource 用于定义资源，并提供可选的异常处理和 fallback 配置项。 @SentinelResource 注解包含以下属性：

  • value：资源名称，必需项（不能为空）
  • entryType：entry 类型，可选项（默认为 EntryType.OUT）
  • blockHandler / blockHandlerClass: blockHandler 对应处理 BlockException 的函数名称，可选项。blockHandler 函数访问范围需要是 public，返回类型需要与原方法相匹配，参数类型需要和原方法相匹配并且最后加一个额外的参数，类型为 BlockException。blockHandler 函数默认需要和原方法在同一个类中。若希望使用其他类的函数，则可以指定 blockHandlerClass 为对应的类的 Class 对象，注意对应的函数必需为 static 函数，否则无法解析。
  • fallback/fallbackClass：fallback 函数名称，可选项，用于在抛出异常的时候提供 fallback 处理逻辑。fallback 函数可以针对所有类型的异常（除了exceptionsToIgnore里面排除掉的异常类型）进行处理。fallback 函数签名和位置要求：
    • 返回值类型必须与原函数返回值类型一致；
    • 方法参数列表需要和原函数一致，或者可以额外多一个 Throwable 类型的参数用于接收对应的异常。
    • fallback 函数默认需要和原方法在同一个类中。若希望使用其他类的函数，则可以指定 fallbackClass 为对应的类的 Class 对象，注意对应的函数必需为 static 函数，否则无法解析。
  • defaultFallback（since 1.6.0）：默认的 fallback 函数名称，可选项，通常用于通用的 fallback 逻辑（即可以用于很多服务或方法）。默认 fallback 函数可以针对所有类型的异常（除了exceptionsToIgnore里面排除掉的异常类型）进行处理。若同时配置了 fallback 和 defaultFallback，则只有 fallback 会生效。defaultFallback 函数签名要求：
    • 返回值类型必须与原函数返回值类型一致；
    • 方法参数列表需要为空，或者可以额外多一个 Throwable 类型的参数用于接收对应的异常。
    • defaultFallback 函数默认需要和原方法在同一个类中。若希望使用其他类的函数，则可以指定 fallbackClass 为对应的类的 Class 对象，注意对应的函数必需为 static 函数，否则无法解析。
  • exceptionsToIgnore（since 1.6.0）：用于指定哪些异常被排除掉，不会计入异常统计中，也不会进入 fallback 逻辑中，而是会原样抛出。

1.8.0 版本开始，defaultFallback 支持在类级别进行配置。

注：1.6.0 之前的版本 fallback 函数只针对降级异常（DegradeException）进行处理，不能针对业务异常进行处理。

特别地，若 blockHandler 和 fallback 都进行了配置，则被限流降级而抛出 BlockException 时只会进入 blockHandler 处理逻辑。若未配置 blockHandler、fallback 和 defaultFallback，则被限流降级时会将 BlockException 直接抛出（若方法本身未定义 throws BlockException 则会被 JVM 包装一层 UndeclaredThrowableException）。

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
public class TestService {

    // 原函数
    @SentinelResource(value = "hello", blockHandler = "exceptionHandler", fallback = "helloFallback")
    public String hello(long s) {
        return String.format("Hello at %d", s);
    }
    
    // Fallback 函数，函数签名与原函数一致或加一个 Throwable 类型的参数.
    public String helloFallback(long s) {
        return String.format("Halooooo %d", s);
    }

    // Block 异常处理函数，参数最后多一个 BlockException，其余与原函数一致.
    public String exceptionHandler(long s, BlockException ex) {
        // Do some log here.
        ex.printStackTrace();
        return "Oops, error occurred at " + s;
    }

    // 这里单独演示 blockHandlerClass 的配置.
    // 对应的 `handleException` 函数需要位于 `ExceptionUtil` 类中，并且必须为 public static 函数.
    @SentinelResource(value = "test", blockHandler = "handleException", blockHandlerClass = {ExceptionUtil.class})
    public void test() {
        System.out.println("Test");
    }
}

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

配置

Spring Cloud Alibaba

若您是通过 Spring Cloud Alibaba 接入的 Sentinel，则无需额外进行配置即可使用 @SentinelResource 注解。

Spring AOP

若您的应用使用了 Spring AOP（无论是 Spring Boot 还是传统 Spring 应用），您需要通过配置的方式将 SentinelResourceAspect 注册为一个 Spring Bean：

1
2
3
4
5
6
7
8
@Configuration
public class SentinelAspectConfiguration {

    @Bean
    public SentinelResourceAspect sentinelResourceAspect() {
        return new SentinelResourceAspect();
    }
}

我们提供了 Spring AOP 的示例，可以参见 sentinel-demo-annotation-spring-aop。

AspectJ

若您的应用直接使用了 AspectJ，那么您需要在 aop.xml 文件中引入对应的 Aspect：

1
2
3
<aspects>
    <aspect name="com.alibaba.csp.sentinel.annotation.aspectj.SentinelResourceAspect"/>
</aspects>

网关流控

Sentinel 支持对 Spring Cloud Gateway、Zuul 等主流的 API Gateway 进行限流。

image-20230922144154800

Sentinel 1.6.0 引入了 Sentinel API Gateway Adapter Common 模块，此模块中包含网关限流的规则和自定义 API 的实体和管理逻辑：

  • GatewayFlowRule：网关限流规则，针对 API Gateway 的场景定制的限流规则，可以针对不同 route 或自定义的 API 分组进行限流，支持针对请求中的参数、Header、来源 IP 等进行定制化的限流。

image-20220424233523892

  • ApiDefinition：用户自定义的 API 定义分组，可以看做是一些 URL 匹配的组合。比如我们可以定义一个 API 叫 my_api，请求 path 模式为 /foo/** 和 /baz/** 的都归到 my_api 这个 API 分组下面。限流的时候可以针对这个自定义的 API 分组维度进行限流。

其中网关限流规则 GatewayFlowRule 的字段解释如下：

  • resource：资源名称，可以是网关中的 route 名称或者用户自定义的 API 分组名称。
  • resourceMode：规则是针对 API Gateway 的 route（RESOURCE_MODE_ROUTE_ID）还是用户在 Sentinel 中定义的 API 分组（RESOURCE_MODE_CUSTOM_API_NAME），默认是 route。
  • grade：限流指标维度，同限流规则的 grade 字段。
  • count：限流阈值
  • intervalSec：统计时间窗口，单位是秒，默认是 1 秒。
  • controlBehavior：流量整形的控制效果，同限流规则的 controlBehavior 字段，目前支持快速失败和匀速排队两种模式，默认是快速失败。
  • burst：应对突发请求时额外允许的请求数目。
  • maxQueueingTimeoutMs：匀速排队模式下的最长排队时间，单位是毫秒，仅在匀速saaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaasa排队模式下生效。
  • paramItem：参数限流配置。若不提供，则代表不针对参数进行限流，该网关规则将会被转换成普通流控规则；否则会转换成热点规则。其中的字段：
    • parseStrategy：从请求中提取参数的策略，目前支持提取来源 IP（PARAM_PARSE_STRATEGY_CLIENT_IP）、Host（PARAM_PARSE_STRATEGY_HOST）、任意 Header（PARAM_PARSE_STRATEGY_HEADER）和任意 URL 参数（PARAM_PARSE_STRATEGY_URL_PARAM）四种模式。
    • fieldName：若提取策略选择 Header 模式或 URL 参数模式，则需要指定对应的 header 名称或 URL 参数名称。
    • pattern：参数值的匹配模式，只有匹配该模式的请求属性值会纳入统计和流控；若为空则统计该请求属性的所有值。（1.6.2 版本开始支持）
    • matchStrategy：参数值的匹配策略，目前支持精确匹配（PARAM_MATCH_STRATEGY_EXACT）、子串匹配（PARAM_MATCH_STRATEGY_CONTAINS）和正则匹配（PARAM_MATCH_STRATEGY_REGEX）。（1.6.2 版本开始支持）

用户可以通过 GatewayRuleManager.loadRules(rules) 手动加载网关规则，或通过 GatewayRuleManager.register2Property(property) 注册动态规则源动态推送（推荐方式）。

Spring Cloud Gateway

从 1.6.0 版本开始，Sentinel 提供了 Spring Cloud Gateway 的适配模块，可以提供两种资源维度的限流：

  • route 维度：即在 Spring 配置文件中配置的路由条目，资源名为对应的 routeId
  • 自定义 API 维度：用户可以利用 Sentinel 提供的 API 来自定义一些 API 分组

使用时需引入以下模块（以 Maven 为例）：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-spring-cloud-gateway-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

使用时只需注入对应的 SentinelGatewayFilter 实例以及 SentinelGatewayBlockExceptionHandler 实例即可（若使用了 Spring Cloud Alibaba Sentinel，则只需按照文档进行配置即可，无需自己加 Configuration）。比如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@Configuration
public class GatewayConfiguration {

    private final List<ViewResolver> viewResolvers;
    private final ServerCodecConfigurer serverCodecConfigurer;

    public GatewayConfiguration(ObjectProvider<List<ViewResolver>> viewResolversProvider,
                                ServerCodecConfigurer serverCodecConfigurer) {
        this.viewResolvers = viewResolversProvider.getIfAvailable(Collections::emptyList);
        this.serverCodecConfigurer = serverCodecConfigurer;
    }

    @Bean
    @Order(Ordered.HIGHEST_PRECEDENCE)
    public SentinelGatewayBlockExceptionHandler sentinelGatewayBlockExceptionHandler() {
        // Register the block exception handler for Spring Cloud Gateway.
        return new SentinelGatewayBlockExceptionHandler(viewResolvers, serverCodecConfigurer);
    }

    @Bean
    @Order(Ordered.HIGHEST_PRECEDENCE)
    public GlobalFilter sentinelGatewayFilter() {
        return new SentinelGatewayFilter();
    }
}

Demo 示例：sentinel-demo-spring-cloud-gateway

比如我们在 Spring Cloud Gateway 中配置了以下路由：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
server:
  port: 8090
spring:
  application:
    name: spring-cloud-gateway
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          lower-case-service-id: true
      routes:
        # Add your routes here.
        - id: product_route
          uri: lb://product
          predicates:
            - Path=/product/**
        - id: httpbin_route
          uri: https://httpbin.org
          predicates:
            - Path=/httpbin/**
          filters:
            - RewritePath=/httpbin/(?<segment>.*), /$\{segment}

同时自定义了一些 API 分组：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
private void initCustomizedApis() {
    Set<ApiDefinition> definitions = new HashSet<>();
    ApiDefinition api1 = new ApiDefinition("some_customized_api")
        .setPredicateItems(new HashSet<ApiPredicateItem>() {{
            add(new ApiPathPredicateItem().setPattern("/product/baz"));
            add(new ApiPathPredicateItem().setPattern("/product/foo/**")
                .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX));
        }});
    ApiDefinition api2 = new ApiDefinition("another_customized_api")
        .setPredicateItems(new HashSet<ApiPredicateItem>() {{
            add(new ApiPathPredicateItem().setPattern("/ahas"));
        }});
    definitions.add(api1);
    definitions.add(api2);
    GatewayApiDefinitionManager.loadApiDefinitions(definitions);
}

那么这里面的 route ID（如 product_route）和 API name（如 some_customized_api）都会被标识为 Sentinel 的资源。比如访问网关的 URL 为 http://localhost:8090/product/foo/22 的时候，对应的统计会加到 product_route 和 some_customized_api 这两个资源上面，而 http://localhost:8090/httpbin/json 只会对应到 httpbin_route 资源上面。

注意：有的时候 Spring Cloud Gateway 会自己在 route 名称前面拼一个前缀，如 ReactiveCompositeDiscoveryClient_xxx 这种。请观察簇点链路页面实际的资源名。

您可以在 GatewayCallbackManager 注册回调进行定制：

  • setBlockHandler：注册函数用于实现自定义的逻辑处理被限流的请求，对应接口为 BlockRequestHandler。默认实现为 DefaultBlockRequestHandler，当被限流时会返回类似于下面的错误信息：Blocked by Sentinel: FlowException。

注意：

  • Sentinel 网关流控默认的粒度是 route 维度以及自定义 API 分组维度，默认不支持 URL 粒度。若通过 Spring Cloud Alibaba 接入，请将 spring.cloud.sentinel.filter.enabled 配置项置为 false（若在网关流控控制台上看到了 URL 资源，就是此配置项没有置为 false）。
  • 若使用 Spring Cloud Alibaba Sentinel 数据源模块，需要注意网关流控规则数据源类型是 gw-flow，若将网关流控规则数据源指定为 flow 则不生效。

Zuul 1.x

Sentinel 提供了 Zuul 1.x 的适配模块，可以为 Zuul Gateway 提供两种资源维度的限流：

  • route 维度：即在 Spring 配置文件中配置的路由条目，资源名为对应的 route ID（对应 RequestContext 中的 proxy 字段）
  • 自定义 API 维度：用户可以利用 Sentinel 提供的 API 来自定义一些 API 分组

使用时需引入以下模块（以 Maven 为例）：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-zuul-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

若使用的是 Spring Cloud Netflix Zuul，我们可以直接在配置类中将三个 filter 注入到 Spring 环境中即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@Configuration
public class ZuulConfig {

    @Bean
    public ZuulFilter sentinelZuulPreFilter() {
        // We can also provider the filter order in the constructor.
        return new SentinelZuulPreFilter();
    }

    @Bean
    public ZuulFilter sentinelZuulPostFilter() {
        return new SentinelZuulPostFilter();
    }

    @Bean
    public ZuulFilter sentinelZuulErrorFilter() {
        return new SentinelZuulErrorFilter();
    }
}

Sentinel Zuul Adapter 生成的调用链路类似于下面，其中的资源名都是 route ID 或者自定义的 API 分组名称：

1
2
3
4
5
6
-EntranceNode: sentinel_gateway_context$$route$$another-route-b(t:0 pq:0.0 bq:0.0 tq:0.0 rt:0.0 prq:0.0 1mp:8 1mb:1 1mt:9)
--another-route-b(t:0 pq:0.0 bq:0.0 tq:0.0 rt:0.0 prq:0.0 1mp:4 1mb:1 1mt:5)
--another_customized_api(t:0 pq:0.0 bq:0.0 tq:0.0 rt:0.0 prq:0.0 1mp:4 1mb:0 1mt:4)
-EntranceNode: sentinel_gateway_context$$route$$my-route-1(t:0 pq:0.0 bq:0.0 tq:0.0 rt:0.0 prq:0.0 1mp:6 1mb:0 1mt:6)
--my-route-1(t:0 pq:0.0 bq:0.0 tq:0.0 rt:0.0 prq:0.0 1mp:2 1mb:0 1mt:2)
--some_customized_api(t:0 pq:0.0 bq:0.0 tq:0.0 rt:0.0 prq:0.0 1mp:2 1mb:0 1mt:2)

发生限流之后的处理流程 ：

  • 发生限流之后可自定义返回参数，通过实现 SentinelFallbackProvider 接口，默认的实现是 DefaultBlockFallbackProvider。
  • 默认的 fallback route 的规则是 route ID 或自定义的 API 分组名称。

比如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// 自定义 FallbackProvider 
public class MyBlockFallbackProvider implements ZuulBlockFallbackProvider {

    private Logger logger = LoggerFactory.getLogger(DefaultBlockFallbackProvider.class);
    
    // you can define route as service level 
    @Override
    public String getRoute() {
        return "/book/app";
    }

    @Override
        public BlockResponse fallbackResponse(String route, Throwable cause) {
            RecordLog.info(String.format("[Sentinel DefaultBlockFallbackProvider] Run fallback route: %s", route));
            if (cause instanceof BlockException) {
                return new BlockResponse(429, "Sentinel block exception", route);
            } else {
                return new BlockResponse(500, "System Error", route);
            }
        }
 }
 
 // 注册 FallbackProvider
 ZuulBlockFallbackManager.registerProvider(new MyBlockFallbackProvider());

默认情况下限流后会返回 429 状态码，返回结果为：

1
2
3
4
5
{
    "code":429,
    "message":"Sentinel block exception",
    "route":"/"
}

注意：

  • Sentinel 网关流控默认的粒度是 route 维度以及自定义 API 分组维度，默认不支持 URL 粒度。若通过 Spring Cloud Alibaba 接入，请将 spring.cloud.sentinel.filter.enabled 配置项置为 false（若在网关流控控制台上看到了 URL 资源，就是此配置项没有置为 false）。
  • 若使用 Spring Cloud Alibaba Sentinel 数据源模块，需要注意网关流控规则数据源类型是 gw-flow，若将网关流控规则数据源指定为 flow 则不生效。

网关流控实现原理

当通过 GatewayRuleManager 加载网关流控规则（GatewayFlowRule）时，无论是否针对请求属性进行限流，Sentinel 底层都会将网关流控规则转化为热点参数规则（ParamFlowRule），存储在 GatewayRuleManager 中，与正常的热点参数规则相隔离。转换时 Sentinel 会根据请求属性配置，为网关流控规则设置参数索引（idx），并同步到生成的热点参数规则中。

外部请求进入 API Gateway 时会经过 Sentinel 实现的 filter，其中会依次进行 路由/API 分组匹配、请求属性解析和参数组装。Sentinel 会根据配置的网关流控规则来解析请求属性，并依照参数索引顺序组装参数数组，最终传入 SphU.entry(res, args) 中。Sentinel API Gateway Adapter Common 模块向 Slot Chain 中添加了一个 GatewayFlowSlot，专门用来做网关规则的检查。GatewayFlowSlot 会从 GatewayRuleManager 中提取生成的热点参数规则，根据传入的参数依次进行规则检查。若某条规则不针对请求属性，则会在参数最后一个位置置入预设的常量，达到普通流控的效果。

image-20230922144206570

网关流控控制台

Sentinel 1.6.3 引入了网关流控控制台的支持，用户可以直接在 Sentinel 控制台上查看 API Gateway 实时的 route 和自定义 API 分组监控，管理网关规则和 API 分组配置。

在 API Gateway 端，用户只需要在原有启动参数的基础上添加如下启动参数即可标记应用为 API Gateway 类型：

1
2
# 注：通过 Spring Cloud Alibaba Sentinel 自动接入的 API Gateway 整合则无需此参数
-Dcsp.sentinel.app.type=1

添加正确的启动参数并有访问量后，我们就可以在 Sentinel 上面看到对应的 API Gateway 了。我们可以查看实时的 route 和自定义 API 分组的监控和调用信息，并针对其配置规则：

image-20230922144217578

网关规则动态配置及网关集群流控可以参考 AHAS Sentinel 网关流控。

集群流控

介绍

为什么要使用集群流控呢？假设我们希望给某个用户限制调用某个 API 的总 QPS 为 50，但机器数可能很多（比如有 100 台）。这时候我们很自然地就想到，找一个 server 来专门来统计总的调用量，其它的实例都与这台 server 通信来判断是否可以调用。这就是最基础的集群流控的方式。

另外集群流控还可以解决流量不均匀导致总体限流效果不佳的问题。假设集群中有 10 台机器，我们给每台机器设置单机限流阈值为 10 QPS，理想情况下整个集群的限流阈值就为 100 QPS。不过实际情况下流量到每台机器可能会不均匀，会导致总量没有到的情况下某些机器就开始限流。因此仅靠单机维度去限制的话会无法精确地限制总体流量。而集群流控可以精确地控制整个集群的调用总量，结合单机限流兜底，可以更好地发挥流量控制的效果。

集群流控中共有两种身份：

  • Token Client：集群流控客户端，用于向所属 Token Server 通信请求 token。集群限流服务端会返回给客户端结果，决定是否限流。
  • Token Server：即集群流控服务端，处理来自 Token Client 的请求，根据配置的集群规则判断是否应该发放 token（是否允许通过）。

模块结构

Sentinel 1.4.0 开始引入了集群流控模块，主要包含以下几部分：

  • sentinel-cluster-common-default: 公共模块，包含公共接口和实体
  • sentinel-cluster-client-default: 默认集群流控 client 模块，使用 Netty 进行通信，提供接口方便序列化协议扩展
  • sentinel-cluster-server-default: 默认集群流控 server 模块，使用 Netty 进行通信，提供接口方便序列化协议扩展；同时提供扩展接口对接规则判断的具体实现（TokenService），默认实现是复用 sentinel-core 的相关逻辑

集群流控规则

规则

FlowRule 添加了两个字段用于集群限流相关配置：

1
2
private boolean clusterMode; // 标识是否为集群限流配置
private ClusterFlowConfig clusterConfig; // 集群限流相关配置项

其中 用一个专门的 ClusterFlowConfig 代表集群限流相关配置项，以与现有规则配置项分开：

1
2
3
4
5
6
7
8
9
10
// （必需）全局唯一的规则 ID，由集群限流管控端分配.
private Long flowId;

// 阈值模式，默认（0）为单机均摊，1 为全局阈值.
private int thresholdType = ClusterRuleConstant.FLOW_THRESHOLD_AVG_LOCAL;

private int strategy = ClusterRuleConstant.FLOW_CLUSTER_STRATEGY_NORMAL;

// 在 client 连接失败或通信失败时，是否退化到本地的限流模式
private boolean fallbackToLocalWhenFail = true;
  • flowId 代表全局唯一的规则 ID，Sentinel 集群限流服务端通过此 ID 来区分各个规则，因此务必保持全局唯一。一般 flowId 由统一的管控端进行分配，或写入至 DB 时生成。
  • thresholdType 代表集群限流阈值模式。其中单机均摊模式下配置的阈值等同于单机能够承受的限额，token server 会根据客户端对应的 namespace（默认为 project.name 定义的应用名）下的连接数来计算总的阈值（比如独立模式下有 3 个 client 连接到了 token server，然后配的单机均摊阈值为 10，则计算出的集群总量就为 30）；而全局模式下配置的阈值等同于整个集群的总阈值。

ParamFlowRule 热点参数限流相关的集群配置与 FlowRule 相似。

集群规则配置方式

在集群流控的场景下，我们推荐使用动态规则源来动态地管理规则。

对于客户端，我们可以按照原有的方式来向 FlowRuleManager 和 ParamFlowRuleManager 注册动态规则源，例如：

1
2
ReadableDataSource<String, List<FlowRule>> flowRuleDataSource = new NacosDataSource<>(remoteAddress, groupId, dataId, parser);
FlowRuleManager.register2Property(flowRuleDataSource.getProperty());

对于集群流控 token server，由于集群限流服务端有作用域（namespace）的概念，因此我们需要注册一个自动根据 namespace 生成动态规则源的 PropertySupplier:

1
2
3
4
5
// Supplier 类型：接受 namespace，返回生成的动态规则源，类型为 SentinelProperty<List<FlowRule>>
// ClusterFlowRuleManager 针对集群限流规则，ClusterParamFlowRuleManager 针对集群热点规则，配置方式类似
ClusterFlowRuleManager.setPropertySupplier(namespace -> {
    return new SomeDataSource(namespace).getProperty();
});

然后每当集群限流服务端 namespace set 产生变更时，Sentinel 会自动针对新加入的 namespace 生成动态规则源并进行自动监听，并删除旧的不需要的规则源。

集群限流客户端

要想使用集群限流功能，必须引入集群限流 client 相关依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-cluster-client-default</artifactId>
    <version>1.8.2</version>
</dependency>

用户可以通过 API 将当前模式置为客户端模式：

1
http://<ip>:<port>/setClusterMode?mode=<xxx>

或者通过 ClusterStateManager API 手动指定模式：

1
2
// 指定当前身份为 Token Client
ClusterStateManager.applyState(ClusterStateManager.CLUSTER_CLIENT);

其中 mode 为 0 代表 client（ClusterStateManager.CLUSTER_CLIENT），1 代表 server。设置成功后，若已有客户端的配置，集群限流客户端将会开启并连接远程的 token server。我们可以在 ~/logs/csp/sentinel-record.log 日志中查看连接的相关日志。

若集群限流客户端未进行配置，则用户需要对客户端进行基本的配置，比如指定集群限流 token server。我们提供了 API 进行配置：

1
http://<ip>:<port>/cluster/client/modifyConfig?data=<config>

其中 data 是 JSON 格式的配置项：

  • serverHost: token server host
  • serverPort: token server 端口
  • requestTimeout: 请求的超时时间（默认为 20 ms）

当然也可以通过动态配置源进行配置。集群限流 token client 共有两种配置：

  • 客户端分配配置（ClusterClientAssignConfig），包括要连接的对端 token server 地址等相关信息。我们可以通过 ClusterClientConfigManager 的 registerServerAssignProperty 方法注册动态配置源。分配配置通常通过统一的分配表解析而来，可以参考 embedded 模式 demo。
  • 客户端通信配置（ClusterClientConfig），包括通信的超时时长等配置。我们可以通过 ClusterClientConfigManager 的 registerClientConfigProperty 方法注册动态配置源。

配置源注册的相关逻辑可以置于 InitFunc 实现类中，并通过 SPI 注册，在 Sentinel 初始化时即可自动进行配置源加载监听。

若用户未引入集群限流 client 相关依赖，或者 client 未开启/连接失败/通信失败，则对于开启了集群模式的规则：

  • 集群热点限流默认直接通过
  • 普通集群限流会退化到 local 模式的限流，即在本地按照单机阈值执行限流检查

当 token client 与 server 之间的连接意外断开时，token client 会不断进行重试，每次重试的间隔时间以 n * 2000 ms 的形式递增。

集群限流服务端

要想使用集群限流服务端，必须引入集群限流 server 相关依赖：

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-cluster-server-default</artifactId>
    <version>1.8.2</version>
</dependency>

启动方式

Sentinel 集群限流服务端有两种启动方式：

  • 独立模式（Alone），即作为独立的 token server 进程启动，独立部署，隔离性好，但是需要额外的部署操作。独立模式适合作为 Global Rate Limiter 给集群提供流控服务。

image-20230922144225971

  • 嵌入模式（Embedded），即作为内置的 token server 与服务在同一进程中启动。在此模式下，集群中各个实例都是对等的，token server 和 client 可以随时进行转变，因此无需单独部署，灵活性比较好。但是隔离性不佳，需要限制 token server 的总 QPS，防止影响应用本身。嵌入模式适合某个应用集群内部的流控。

image-20230922144231865

我们提供了 HTTP API 用于在 embedded 模式下转换集群流控身份：

1
http://<ip>:<port>/setClusterMode?mode=<xxx>

其中 mode 为 0 代表 client，1 代表 server，-1 代表关闭。注意应用端需要引入集群限流客户端或服务端的相应依赖。

在独立模式下，我们可以直接创建对应的 ClusterTokenServer 实例并在 main 函数中通过 start 方法启动 Token Server。

规则配置

见前面 规则配置 相关内容。

属性配置

我们推荐给集群限流服务端注册动态配置源来动态地进行配置。配置类型有以下几种：

  • namespace set: 集群限流服务端的作用域（命名空间），用于指定该 token server 可以服务哪些应用或分组，嵌入模式下可以设置为自己的应用名。集群限流 client 在连接到 token server 后会上报自己的命名空间（默认为 project.name 配置的应用名），token server 会根据上报的命名空间名称统计连接数。
  • transport config: 集群限流服务端通信相关配置，如 server port
  • flow config: 集群限流服务端限流相关配置，如滑动窗口统计时长、格子数目、最大允许总 QPS等

我们可以通过 ClusterServerConfigManager 的各个 registerXxxProperty 方法来注册相关的配置源。

从 1.4.1 版本开始，Sentinel 支持给 token server 配置最大允许的总 QPS（maxAllowedQps），用于对 Token Server 的资源使用进行限制，防止在嵌入模式下影响应用本身。

Token Server 分配配置

image-20230922144237096

示例

sentinel-demo-cluster 提供了嵌入模式和独立模式的示例：

注意：若在本地启动多个 Demo 示例，需要加上 -Dcsp.sentinel.log.use.pid=true 参数，否则控制台显示监控会不准确。

集群限流控制台

使用集群限流功能需要对 Sentinel 控制台进行相关的改造，推送规则时直接推送至配置中心，接入端引入 push 模式的动态数据源。可以参考 Sentinel 控制台（集群流控管理文档）。

同时云上版本 AHAS Sentinel 提供开箱即用的全自动托管集群流控能力，无需手动指定/分配 token server 以及管理连接状态，同时支持分钟小时级别流控、大流量低延时场景流控场景，同时支持 Istio/Envoy 场景的 Mesh 流控能力。

其它

若在生产环境使用集群限流，管控端还需要关注以下的问题：

  • Token Server 自动管理、调度（分配/选举 Token Server）
  • Token Server 高可用，在某个 server 不可用时自动 failover 到其它机器

集群流控日志

  • ${log_dir}/sentinel-cluster-client.log：Token Client 日志，会记录请求失败的信息

扩展接口设计

整体扩展架构

image-20230922144242311

通用扩展接口

以下通用接口位于 sentinel-core 中：

  • TokenService: 集群限流功能接口，server / client 均可复用
  • ClusterTokenClient: 集群限流功能客户端
  • ClusterTokenServer: 集群限流服务端接口
  • EmbeddedClusterTokenServer: 集群限流服务端接口（embedded 模式）

以下通用接口位于 sentinel-cluster-common-default:

  • EntityWriter
  • EntityDecoder

Client 扩展接口

集群流控 Client 端通信相关扩展接口：

  • ClusterTransportClient：集群限流通信客户端
  • RequestEntityWriter
  • ResponseEntityDecoder

Server 扩展接口

集群流控 Server 端通信相关扩展接口：

  • ResponseEntityWriter
  • RequestEntityDecoder

集群流控 Server 端请求处理扩展接口：

  • RequestProcessor: 请求处理接口 (request -> response)

启动配置项

配置方式

Sentinel 提供如下的配置方式：

  • JVM -D 参数方式
  • properties 文件方式（1.7.0 版本开始支持）

其中，project.name 参数只能通过 JVM -D 参数方式配置（since 1.8.0 取消该限制），其它参数支持所有的配置方式。

优先级顺序：JVM -D 参数的优先级最高。若 properties 和 JVM 参数中有相同项的配置，以 JVM 参数配置的为准。

用户可以通过 -Dcsp.sentinel.config.file 参数配置 properties 文件的路径，支持 classpath 路径配置（如 classpath:sentinel.properties）。默认 Sentinel 会尝试从 classpath:sentinel.properties 文件读取配置，读取编码默认为 UTF-8。

注：1.7.0 以下版本可以通过旧的 ${user_home}/logs/csp/${project.name}.properties 配置文件进行配置（除 project.name 和日志相关配置项）。

注：若您的应用为 Spring Boot 或 Spring Cloud 应用，您可以使用 Spring Cloud Alibaba，通过 Spring 配置文件来指定配置，详情请参考 Spring Cloud Alibaba Sentinel 文档。

配置项列表

sentinel-core 的配置项

基础配置项

名称 含义 类型 默认值 是否必需 备注
project.name 指定应用的名称 String null 否
csp.sentinel.app.type 指定应用的类型 int 0 (APP_TYPE_COMMON) 否 1.6.0 引入
csp.sentinel.metric.file.single.size 单个监控日志文件的大小 long 52428800 (50MB) 否
csp.sentinel.metric.file.total.count 监控日志文件的总数上限 int 6 否
csp.sentinel.statistic.max.rt 最大的有效响应时长（ms），超出此值则按照此值记录 int 4900 否 1.4.1 引入
csp.sentinel.spi.classloader SPI 加载时使用的 ClassLoader，默认为给定类的 ClassLoader String default 否 若配置 context 则使用 thread context ClassLoader。1.7.0 引入

其中 project.name 项用于指定应用名（appName）。若未指定，则默认解析 main 函数的类名作为应用名。实际项目使用中建议手动指定应用名。

日志相关配置项

名称 含义 类型 默认值 是否必需 备注
csp.sentinel.log.dir Sentinel 日志文件目录 String ${user.home}/logs/csp/ 否 1.3.0 引入
csp.sentinel.log.use.pid 日志文件名中是否加入进程号，用于单机部署多个应用的情况 boolean false 否 1.3.0 引入
csp.sentinel.log.output.type Record 日志输出的类型，file 代表输出至文件，console 代表输出至终端 String file 否 1.6.2 引入

注意：若需要在单台机器上运行相同服务的多个实例，则需要加入 -Dcsp.sentinel.log.use.pid=true 来保证不同实例日志的独立性。

sentinel-transport-common 的配置项

名称 含义 类型 默认值 是否必需
csp.sentinel.dashboard.server 控制台的地址，指定控制台后客户端会自动向该地址发送心跳包。地址格式为：hostIp:port String null 是
csp.sentinel.heartbeat.interval.ms 心跳包发送周期，单位毫秒 long null 非必需，若不进行配置，则会从相应的 HeartbeatSender 中提取默认值
csp.sentinel.api.port 本地启动 HTTP API Server 的端口号 int 8719 否
csp.sentinel.heartbeat.client.ip 指定心跳包中本机的 IP String - 若不指定则通过 HostNameUtil 解析；该配置项多用于多网卡环境

注：csp.sentinel.api.port 可不提供，默认为 8719，若端口冲突会自动向下探测可用的端口。

Sentinel 控制台

1. 概述

Sentinel 提供一个轻量级的开源控制台，它提供机器发现以及健康情况管理、监控（单机和集群），规则管理和推送的功能。这里，我们将会详细讲述如何通过简单的步骤就可以使用这些功能。

接下来，我们将会逐一介绍如何整合 Sentinel 核心库和 Dashboard，让它发挥最大的作用。同时我们也在阿里云上提供企业级的 Sentinel 服务：AHAS Sentinel 控制台，您只需要几个简单的步骤，就能最直观地看到控制台如何实现这些功能，并体验多样化的监控及全自动托管的集群流控能力。

Sentinel 控制台包含如下功能:

注意：Sentinel 控制台目前仅支持单机部署。Sentinel 控制台项目提供 Sentinel 功能全集示例，不作为开箱即用的生产环境控制台，不提供安全可靠保障。若希望在生产环境使用请根据文档自行进行定制和改造。

2. 启动控制台

2.1 获取 Sentinel 控制台

您可以从 release 页面 下载最新版本的控制台 jar 包。

您也可以从最新版本的源码自行构建 Sentinel 控制台：

  • 下载 控制台 工程
  • 使用以下命令将代码打包成一个 fat jar: mvn clean package

2.2 启动

注意：启动 Sentinel 控制台需要 JDK 版本为 1.8 及以上版本。

使用如下命令启动控制台：

1
java -Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080 -Dproject.name=sentinel-dashboard -jar sentinel-dashboard.jar

其中 -Dserver.port=8080 用于指定 Sentinel 控制台端口为 8080。

从 Sentinel 1.6.0 起，Sentinel 控制台引入基本的登录功能，默认用户名和密码都是 sentinel。可以参考 鉴权模块文档 配置用户名和密码。

注：若您的应用为 Spring Boot 或 Spring Cloud 应用，您可以通过 Spring 配置文件来指定配置，详情请参考 Spring Cloud Alibaba Sentinel 文档。

3. 客户端接入控制台

控制台启动后，客户端需要按照以下步骤接入到控制台。

3.1 引入JAR包

客户端需要引入 Transport 模块来与 Sentinel 控制台进行通信。您可以通过 pom.xml 引入 JAR 包:

1
2
3
4
5
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-transport-simple-http</artifactId>
    <version>x.y.z</version>
</dependency>

3.2 配置启动参数

启动时加入 JVM 参数 -Dcsp.sentinel.dashboard.server=consoleIp:port 指定控制台地址和端口。若启动多个应用，则需要通过 -Dcsp.sentinel.api.port=xxxx 指定客户端监控 API 的端口（默认是 8719）。

从 1.6.3 版本开始，控制台支持网关流控规则管理。您需要在接入端添加 -Dcsp.sentinel.app.type=1 启动参数以将您的服务标记为 API Gateway，在接入控制台时您的服务会自动注册为网关类型，然后您即可在控制台配置网关规则和 API 分组。

除了修改 JVM 参数，也可以通过配置文件取得同样的效果。更详细的信息可以参考 启动配置项。

3.3 触发客户端初始化

确保客户端有访问量，Sentinel 会在客户端首次调用的时候进行初始化，开始向控制台发送心跳包。

注意：您还需要根据您的应用类型和接入方式引入对应的 适配依赖，否则即使有访问量也不能被 Sentinel 统计。

4. 查看机器列表以及健康情况

当您在机器列表中看到您的机器，就代表着您已经成功接入控制台；如果没有看到您的机器，请检查配置，并通过 ${user.home}/logs/csp/sentinel-record.log.xxx 日志来排查原因，详细的部分请参考 日志文档。

image-20230922144253237

注意：若接入 Sentinel 控制台不成功，可以参考 FAQ 排查问题。

5. 监控

5.1 “簇点链路”中显示刚刚调用的资源（单机实时）

簇点链路（单机调用链路）页面实时的去拉取指定客户端资源的运行情况。它一共提供两种展示模式：一种用树状结构展示资源的调用链路，另外一种则不区分调用链路展示资源的实时情况。

注意: 簇点链路监控是内存态的信息，它仅展示启动后调用过的资源。

树状链路 平铺链路
resourceTree cluster

5.2 “实时监控”汇总资源信息（集群聚合）

同时，同一个服务下的所有机器的簇点信息会被汇总，并且秒级地展示在”实时监控”下。

注意: 实时监控仅存储 5 分钟以内的数据，如果需要持久化，需要通过调用实时监控接口来定制。

image-20230922144258638

注意：请确保 Sentinel 控制台所在的机器时间与自己应用的机器时间保持一致，否则会导致拉不到实时的监控数据。

6. 规则管理及推送

Sentinel 控制台同时提供简单的规则管理以及推送的功能。规则推送分为 3 种模式，包括 “原始模式”、”Pull 模式” 和”Push 模式”。

这里先简单的介绍”原始模式”。

6.1 规则管理

您可以在控制台通过接入端暴露的 HTTP API 来查询规则。

image-20230922144302397

6.2 规则推送

image-20230922144306685

目前控制台的规则推送也是通过 规则查询更改 HTTP API 来更改规则。这也意味着这些规则仅在内存态生效，应用重启之后，该规则会丢失。

注：若通过控制台推送规则时出现 invalid type 或 empty type 的错误，请确保 transport 模块版本与 core 模块版本保持一致；若控制台版本 >= 1.7.1，请将接入端的相关依赖也升级至 1.7.1 及以上版本。

以上是原始模式。当了解了原始模式之后，我们非常鼓励您通过 动态规则 并结合各种外部存储来定制自己的规则源。我们推荐通过动态配置源的控制台来进行规则写入和推送，而不是通过 Sentinel 客户端直接写入到动态配置源中。在生产环境中，我们推荐 push 模式，具体可以参考：在生产环境使用 Sentinel。

注：若要使用集群流控功能，则必须对接动态规则源，否则无法正常使用。您也可以接入 AHAS Sentinel 快速接入全自动托管、高可用的集群流控能力。

6.3 网关流控规则

参考 网关流控控制台文档。

鉴权

从 Sentinel 1.5.0 开始，控制台提供通用的鉴权接口 AuthService，用户可根据需求自行实现。

从 Sentinel 1.6.0 起，Sentinel 控制台引入基本的登录功能，默认用户名和密码都是 sentinel。该鉴权能力非常基础，生产环境使用建议根据安全需要自行改造。

image-20230922144311466

用户可以通过如下参数进行配置：

  • -Dsentinel.dashboard.auth.username=sentinel 用于指定控制台的登录用户名为 sentinel；
  • -Dsentinel.dashboard.auth.password=123456 用于指定控制台的登录密码为 123456；如果省略这两个参数，默认用户和密码均为 sentinel；
  • -Dserver.servlet.session.timeout=7200 用于指定 Spring Boot 服务端 session 的过期时间，如 7200 表示 7200 秒；60m 表示 60 分钟，默认为 30 分钟；

同样也可以直接在 Spring properties 文件中进行配置。

注意：部署多台控制台时，session 默认不会在各实例之间共享，这一块需要自行改造。

控制台配置项

控制台的一些特性可以通过配置项来进行配置，配置项主要有两个来源：System.getProperty() 和 System.getenv()，同时存在时后者可以覆盖前者。

通过环境变量进行配置时，因为不支持 . 所以需要将其更换为 _。

配置项 类型 默认值 最小值 描述
auth.enabled boolean true - 是否开启登录鉴权，仅用于日常测试，生产上不建议关闭
sentinel.dashboard.auth.username String sentinel - 登录控制台的用户名，默认为 sentinel
sentinel.dashboard.auth.password String sentinel - 登录控制台的密码，默认为 sentinel
sentinel.dashboard.app.hideAppNoMachineMillis Integer 0 60000 是否隐藏无健康节点的应用，距离最近一次主机心跳时间的毫秒数，默认关闭
sentinel.dashboard.removeAppNoMachineMillis Integer 0 120000 是否自动删除无健康节点的应用，距离最近一次其下节点的心跳时间毫秒数，默认关闭
sentinel.dashboard.unhealthyMachineMillis Integer 60000 30000 主机失联判定，不可关闭
sentinel.dashboard.autoRemoveMachineMillis Integer 0 300000 距离最近心跳时间超过指定时间是否自动删除失联节点，默认关闭
sentinel.dashboard.unhealthyMachineMillis Integer 60000 30000 主机失联判定，不可关闭
server.servlet.session.cookie.name String sentinel_dashboard_cookie - 控制台应用的 cookie 名称，可单独设置避免同一域名下 cookie 名冲突

配置示例：

  • 命令行方式：
1
java -Dsentinel.dashboard.app.hideAppNoMachineMillis=60000
  • Java 方式：
1
System.setProperty("sentinel.dashboard.app.hideAppNoMachineMillis", "60000");
  • 环境变量方式：
1
sentinel_dashboard_app_hideAppNoMachineMillis=60000

在生产环境中使用 Sentinel

引言

Sentinel 目前已可用于生产环境，除了阿里巴巴以外，也有很多企业在生产环境中广泛使用 Sentinel。

生产环境的 Sentinel Dashboard 需要具备下面几个特性:

  • **规则管理及推送**，集中管理和推送规则。sentinel-core 提供 API 和扩展接口来接收信息。开发者需要根据自己的环境，选取一个可靠的推送规则方式；同时，规则最好在控制台中集中管理。
  • **监控**，支持可靠、快速的实时监控和历史监控数据查询。sentinel-core 记录秒级的资源运行情况，并且提供 API 来拉取资源运行信息。当机器大于一台以上的时候，可以通过 Dashboard 来拉取，聚合，并且存储这些信息。这个时候，Dashboard 需要有一个存储媒介，来存储历史运行情况。
  • 权限控制，区分用户角色，来进行操作。生产环境下的权限控制是非常重要的，理论上只有管理员等高级用户才有权限去修改应用的规则。

由于开发者有各自不一样的环境和需求，我们会对“规则管理和推送”，“监控”这两个方面给出建议以及最佳实践；对于权限控制，由于每个开发者的环境都不一样，我们在最佳实践中仅仅使用了简单的认证。开发者可以依循自己的需求，结合实际生产环境，选择最适合自己的方式。

同时我们也在云上提供 企业级的 Sentinel 控制台 (AHAS Sentinel)，欢迎大家体验。

规则管理及推送

一般来说，规则的推送有下面三种模式:

推送模式 说明 优点 缺点
原始模式 API 将规则推送至客户端并直接更新到内存中，扩展写数据源（WritableDataSource） 简单，无任何依赖 不保证一致性；规则保存在内存中，重启即消失。严重不建议用于生产环境
Pull 模式 扩展写数据源（WritableDataSource）， 客户端主动向某个规则管理中心定期轮询拉取规则，这个规则中心可以是 RDBMS、文件 等 简单，无任何依赖；规则持久化 不保证一致性；实时性不保证，拉取过于频繁也可能会有性能问题。
Push 模式 扩展读数据源（ReadableDataSource），规则中心统一推送，客户端通过注册监听器的方式时刻监听变化，比如使用 Nacos、Zookeeper 等配置中心。这种方式有更好的实时性和一致性保证。生产环境下一般采用 push 模式的数据源。 规则持久化；一致性；快速 引入第三方依赖

原始模式

如果不做任何修改，Dashboard 的推送规则方式是通过 API 将规则推送至客户端并直接更新到内存中：

image-20220215222428715

这种做法的好处是简单，无依赖；坏处是应用重启规则就会消失，仅用于简单测试，不能用于生产环境。

Pull模式

pull 模式的数据源（如本地文件、RDBMS 等）一般是可写入的。使用时需要在客户端注册数据源：将对应的读数据源注册至对应的 RuleManager，将写数据源注册至 transport 的 WritableDataSourceRegistry 中。以本地文件数据源为例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
public class FileDataSourceInit implements InitFunc {

    @Override
    public void init() throws Exception {
        String flowRulePath = "xxx";

        ReadableDataSource<String, List<FlowRule>> ds = new FileRefreshableDataSource<>(
            flowRulePath, source -> JSON.parseObject(source, new TypeReference<List<FlowRule>>() {})
        );
        // 将可读数据源注册至 FlowRuleManager.
        FlowRuleManager.register2Property(ds.getProperty());

        WritableDataSource<List<FlowRule>> wds = new FileWritableDataSource<>(flowRulePath, this::encodeJson);
        // 将可写数据源注册至 transport 模块的 WritableDataSourceRegistry 中.
        // 这样收到控制台推送的规则时，Sentinel 会先更新到内存，然后将规则写入到文件中.
        WritableDataSourceRegistry.registerFlowDataSource(wds);
    }

    private <T> String encodeJson(T t) {
        return JSON.toJSONString(t);
    }
}

本地文件数据源会定时轮询文件的变更，读取规则。这样我们既可以在应用本地直接修改文件来更新规则，也可以通过 Sentinel 控制台推送规则。以本地文件数据源为例，推送过程如下图所示：

image-20220215222543801

首先 Sentinel 控制台通过 API 将规则推送至客户端并更新到内存中，接着注册的写数据源会将新的规则保存到本地的文件中。使用 pull 模式的数据源时一般不需要对 Sentinel 控制台进行改造。

这种实现方法好处是简单，不引入新的依赖，坏处是无法保证监控数据的一致性。

Push模式

生产环境下一般更常用的是 push 模式的数据源。对于 push 模式的数据源,如远程配置中心（ZooKeeper, Nacos, Apollo等等），推送的操作不应由 Sentinel 客户端进行，而应该经控制台统一进行管理，直接进行推送，数据源仅负责获取配置中心推送的配置并更新到本地。因此推送规则正确做法应该是 配置中心控制台/Sentinel 控制台 → 配置中心 → Sentinel 数据源 → Sentinel，而不是经 Sentinel 数据源推送至配置中心。这样的流程就非常清晰了：

image-20230922144334802

我们提供了 ZooKeeper, Apollo, Nacos 等的动态数据源实现。以 ZooKeeper 为例子，如果要使用第三方的配置中心作为配置管理，您需要做下面的几件事情:

  1. 实现一个公共的 ZooKeeper 客户端用于推送规则，在 Sentinel 控制台配置项中需要指定 ZooKeeper 的地址，启动时即创建 ZooKeeper Client。
  2. 我们需要针对每个应用（appName），每种规则设置不同的 path（可随时修改）；或者约定大于配置（如 path 的模式统一为 /sentinel_rules/{appName}/{ruleType}，e.g. sentinel_rules/appA/flowRule）。
  3. 规则配置页需要进行相应的改造，直接针对应用维度进行规则配置；修改同个应用多个资源的规则时可以批量进行推送，也可以分别推送。Sentinel 控制台将规则缓存在内存中（如 InMemFlowRuleStore），可以对其进行改造使其支持应用维度的规则缓存（key 为 appName），每次添加/修改/删除规则都先更新内存中的规则缓存，然后需要推送的时候从规则缓存中获取全量规则，然后通过上面实现的 Client 将规则推送到 ZooKeeper 即可。
  4. 应用客户端需要注册对应的读数据源以监听变更，可以参考 相关文档。

从 Sentinel 1.4.0 开始，Sentinel 控制台提供 DynamicRulePublisher 和 DynamicRuleProvider 接口用于实现应用维度的规则推送和拉取，并提供了相关的示例。Sentinel 提供应用维度规则推送的示例页面（/v2/flow），用户改造控制台对接配置中心后可直接通过 v2 页面推送规则至配置中心。改造详情可参考 应用维度规则推送示例。

部署多个控制台实例时，通常需要将规则存至 DB 中，规则变更后同步向配置中心推送规则。

监控

Sentinel 会记录资源访问的秒级数据（若没有访问则不进行记录）并保存在本地日志中，具体格式请见 秒级监控日志文档。Sentinel 控制台可以通过 Sentinel 客户端预留的 HTTP API 从秒级监控日志中拉取监控数据，并进行聚合。

目前 Sentinel 控制台中监控数据聚合后直接存在内存中，未进行持久化，且仅保留最近 5 分钟的监控数据。若需要监控数据持久化的功能，可以自行扩展实现 MetricsRepository 接口（0.2.0 版本），然后注册成 Spring Bean 并在相应位置通过 @Qualifier 注解指定对应的 bean name 即可。MetricsRepository 接口定义了以下功能：

  • save 与 saveAll：存储对应的监控数据
  • queryByAppAndResourceBetween：查询某段时间内的某个应用的某个资源的监控数据
  • listResourcesOfApp：查询某个应用下的所有资源

其中默认的监控数据类型为 MetricEntity，包含应用名称、时间戳、资源名称、异常数、请求通过数、请求拒绝数、平均响应时间等信息。对于监控数据的存储，用户需要根据自己的存储精度，来考虑如何存储这些监控数据。为了更好地支撑大规模的集群，生产环境通常需要部署多个控制台实例，通常需要仔细设计下监控分片拉取和写入策略。

同时用户可以自行进行扩展，适配 Grafana 等可视化平台，以便将监控数据更好地进行可视化。

最佳实践

我们提供了一个云上版本的控制台。通过这个版本，开发者可以看到一个完整的生产环境的控制台的功能全集。它主要包括:

  • 可靠的实时监控和历史监控数据查询：该控制台将会示范 Sentinel 的监控能做成什么样子，包括实时监控、集群热力图等，请参考“监控”以及“簇点链路”模块。
  • 动态规则管理/推送：该控制台将会示范如何做一个合理的 push 结构的实现，请参考“规则”模块。
  • 机器列表：如何利用 Sentinel 上报的机器信息进行管理，请参考“机器列表”模块。
  • 全自动托管的集群流控与 Service Mesh 流控能力

详情请参考 AHAS Sentinel 控制台文档来参考如何在生产环境中使用控制台。

同类组件功能对比

Sentinel Hystrix resilience4j
隔离策略 信号量隔离（并发控制） 线程池隔离/信号量隔离 信号量隔离
熔断降级策略 基于慢调用比例、异常比例、异常数 基于异常比例 基于异常比例、响应时间
实时统计实现 滑动窗口（LeapArray） 滑动窗口（基于 RxJava） Ring Bit Buffer
动态规则配置 支持近十种动态数据源 支持多种数据源 有限支持
扩展性 多个扩展点 插件的形式 接口的形式
基于注解的支持 支持 支持 支持
单机限流 基于 QPS，支持基于调用关系的限流 有限的支持 Rate Limiter
集群流控 支持 不支持 不支持
流量整形 支持预热模式与匀速排队控制效果 不支持 简单的 Rate Limiter 模式
系统自适应保护 支持 不支持 不支持
热点识别/防护 支持 不支持 不支持
多语言支持 Java/Go/C++ Java Java
Service Mesh 支持 支持 Envoy/Istio 不支持 不支持
控制台 提供开箱即用的控制台，可配置规则、实时监控、机器发现等 简单的监控查看 不提供控制台，可对接其它监控系统

docker 部署 sentinel-dashboard

Sentinel控制台安装可以基于jar包启动的方式安装，也可以基于docker安装，为了方便操作，我们这里采用docker安装方式：

1
docker run --name=sentinel-dashboard -d -p 8858:8858 -d --restart=on-failure bladex/sentinel-dashboard:1.8.0

安装好了后，我们可以直接访问 http://192.168.200.129:8858/，默认用户名和密码都是 sentinel

image-20220424234952045

登录后，效果如下：

image-20220424235001178

流控模式是链路模式

拓展知识点：

注意：如果流控模式是链路模式，需要引入如下依赖：

1
2
3
4
5
6
7
8
9
<dependency> 

<groupId>com.alibaba.csp</groupId> 

<artifactId>sentinel-web-servlet</artifactId> 

<version>1.8.0</version> 

</dependency>

创建过滤器

1
2
3
4
5
6
7
8
9
10
11
12
/*** * CommonFilter过滤器 * @return */
 @Bean
 public FilterRegistrationBean sentinelFilterRegistration() {
     FilterRegistrationBean registration = new FilterRegistrationBean();
     registration.setFilter(new CommonFilter());
     registration.addUrlPatterns("/*");
     //过滤所有请求 // 入口资源关闭聚合
     registration.addInitParameter(CommonFilter.WEB_CONTEXT_UN IFY, "false");
     registration.setName("sentinelFilter");
     registration.setOrder(1);
     return registration;
 }

bootstrap.yml配置： web-context-unify: false

1
2
3
4
5
6
cloud: 
	sentinel: 
		transport: 
			port: 8719 
			dashboard: localhost:8858 
		web-context-unify: false #可根据不同的URL 进行链路限流