Sentinel 快速入门

前置推荐阅读:Sentinel 介绍-CSDN博客

前置推荐阅读：Nacos快速入门-CSDN博客

快速开始

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

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

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

我们将会提供 本地运行 demo 和 公网 demo 来帮助新手快速入门。这两种方式都只需要您执行2到5个步骤。

本地Demo

1. 引入 Sentinel 依赖

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

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

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

2. 定义资源

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

public static void main(String[] args) {
    // 配置规则.
    initFlowRules();

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

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

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

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

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

3. 定义规则

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

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 里看到下面的输出:

|--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 包:

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-transport-simple-http</artifactId>
    <version>1.8.6</version>
</dependency>

• 启动时加入 JVM 参数 -Dcsp.sentinel.dashboard.server=consoleIp:port 指定控制台地址和端口。更多的参数参见 启动参数文档。
• 确保应用端有访问量

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

详细介绍和使用文档可参考：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 函数，程序类似于：

public static void main(String[] args) {
    // 不断进行资源调用.
    while (true) {
        Entry entry = null;
        try {
	        entry = SphU.entry("HelloWorld");
            // 资源中的逻辑.
            System.out.println("hello world");
        } catch (BlockException ex) {
            System.err.println("blocked!");
        } finally {
            if (entry != null) {
                entry.exit();
            }
        }
    }
}

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

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

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

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

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

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

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

3. 启动 demo

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

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

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

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

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

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

Sentinel 工作主流程

Overview

在 Sentinel 里面，所有的资源都对应一个资源名称以及一个 Entry。Entry 可以通过对主流框架的适配自动创建，也可以通过注解的方式或调用 API 显式创建；每一个 Entry 创建的时候，同时也会创建一系列功能插槽（slot chain）。这些插槽有不同的职责，例如:

• NodeSelectorSlot 负责收集资源的路径，并将这些资源的调用路径，以树状结构存储起来，用于根据调用路径来限流降级；
• ClusterBuilderSlot 则用于存储资源的统计信息以及调用者信息，例如该资源的 RT, QPS, thread count 等等，这些信息将用作为多维度限流，降级的依据；
• StatisticSlot 则用于记录、统计不同纬度的 runtime 指标监控信息；
• FlowSlot 则用于根据预设的限流规则以及前面 slot 统计的状态，来进行流量控制；
• AuthoritySlot 则根据配置的黑白名单和调用来源信息，来做黑白名单控制；
• DegradeSlot 则通过统计信息以及预设的规则，来做熔断降级；
• SystemSlot 则通过系统的状态，例如 load1 等，来控制总的入口流量；

总体的框架如下:

Sentinel 将 ProcessorSlot 作为 SPI 接口进行扩展（1.7.2 版本以前 SlotChainBuilder 作为 SPI），使得 Slot Chain 具备了扩展的能力。您可以自行加入自定义的 slot 并编排 slot 间的顺序，从而可以给 Sentinel 添加自定义的功能。

下面介绍一下各个 slot 的功能。

NodeSelectorSlot

这个 slot 主要负责收集资源的路径，并将这些资源的调用路径，以树状结构存储起来，用于根据调用路径来限流降级。

 ContextUtil.enter("entrance1", "appA");
 Entry nodeA = SphU.entry("nodeA");
 if (nodeA != null) {
    nodeA.exit();
 }
 ContextUtil.exit();

上述代码通过 ContextUtil.enter() 创建了一个名为 entrance1 的上下文，同时指定调用发起者为 appA；接着通过 SphU.entry()请求一个 token，如果该方法顺利执行没有抛 BlockException，表明 token 请求成功。

以上代码将在内存中生成以下结构：

 	     machine-root
                 /     
                /
         EntranceNode1
              /
             /   
      DefaultNode(nodeA)

注意：每个 DefaultNode 由资源 ID 和输入名称来标识。换句话说，一个资源 ID 可以有多个不同入口的 DefaultNode。

  ContextUtil.enter("entrance1", "appA");
  Entry nodeA = SphU.entry("nodeA");
  if (nodeA != null) {
    nodeA.exit();
  }
  ContextUtil.exit();

  ContextUtil.enter("entrance2", "appA");
  nodeA = SphU.entry("nodeA");
  if (nodeA != null) {
    nodeA.exit();
  }
  ContextUtil.exit();

以上代码将在内存中生成以下结构：

                   machine-root
                   /         \
                  /           \
          EntranceNode1   EntranceNode2
                /               \
               /                 \
       DefaultNode(nodeA)   DefaultNode(nodeA)

上面的结构可以通过调用 curl http://localhost:8719/tree?type=root 来显示：

EntranceNode: machine-root(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0)
-EntranceNode1: Entrance1(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0)
--nodeA(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0)
-EntranceNode2: Entrance1(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0)
--nodeA(t:0 pq:1 bq:0 tq:1 rt:0 prq:1 1mp:0 1mb:0 1mt:0)

t:threadNum  pq:passQps  bq:blockedQps  tq:totalQps  rt:averageRt  prq: passRequestQps 1mp:1m-passed 1mb:1m-blocked 1mt:1m-total

ClusterBuilderSlot

此插槽用于构建资源的 ClusterNode 以及调用来源节点。ClusterNode 保持资源运行统计信息（响应时间、QPS、block 数目、线程数、异常数等）以及原始调用者统计信息列表。来源调用者的名字由 ContextUtil.enter(contextName，origin) 中的 origin 标记。可通过如下命令查看某个资源不同调用者的访问情况：curl http://localhost:8719/origin?id=caller：

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        

StatisticSlot

StatisticSlot 是 Sentinel 的核心功能插槽之一，用于统计实时的调用数据。

• clusterNode：资源唯一标识的 ClusterNode 的 runtime 统计
• origin：根据来自不同调用者的统计信息
• defaultnode: 根据上下文条目名称和资源 ID 的 runtime 统计
• 入口的统计

Sentinel 底层采用高性能的滑动窗口数据结构 LeapArray 来统计实时的秒级指标数据，可以很好地支撑写多于读的高并发场景。

FlowSlot

这个 slot 主要根据预设的资源的统计信息，按照固定的次序，依次生效。如果一个资源对应两条或者多条流控规则，则会根据如下次序依次检验，直到全部通过或者有一个规则生效为止:

• 指定应用生效的规则，即针对调用方限流的；
• 调用方为 other 的规则；
• 调用方为 default 的规则。

DegradeSlot

这个 slot 主要针对资源的平均响应时间（RT）以及异常比率，来决定资源是否在接下来的时间被自动熔断掉。

SystemSlot

这个 slot 会根据对于当前系统的整体情况，对入口资源的调用进行动态调配。其原理是让入口的流量和当前系统的预计容量达到一个动态平衡。

注意系统规则只对入口流量起作用（调用类型为 EntryType.IN），对出口流量无效。可通过 SphU.entry(res, entryType) 指定调用类型，如果不指定，默认是EntryType.OUT。

Sentinel 控制台

1. 概述

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

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

Sentinel 控制台包含如下功能:

• 查看机器列表以及健康情况：收集 Sentinel 客户端发送的心跳包，用于判断机器是否在线。
• 监控 (单机和集群聚合)：通过 Sentinel 客户端暴露的监控 API，定期拉取并且聚合应用监控信息，最终可以实现秒级的实时监控。
• 规则管理和推送：统一管理推送规则。
• 鉴权：生产环境中鉴权非常重要。这里每个开发者需要根据自己的实际情况进行定制。

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

2. 启动控制台

2.1 获取 Sentinel 控制台

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

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

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

2.2 启动

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

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

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 包:

<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）。

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

3.3 触发客户端初始化

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

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

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

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

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

注意：请确保在使用较新版本的浏览器，我们不保证支持旧版本的浏览器。

5. 监控

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

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

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

树状链路：

平铺链路：

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

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

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

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

6. 规则管理及推送

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

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

6.1 规则管理

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

6.2 规则推送

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

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

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

Sentinel 同时还提供应用维度规则推送的示例页面（流控规则页面，前端路由为 /v2/flow），用户改造控制台对接配置中心后可直接通过 v2 页面推送规则至配置中心。Sentinel 抽取了通用接口用于向远程配置中心推送规则以及拉取规则：

• DynamicRuleProvider<T>: 拉取规则（应用维度）
• DynamicRulePublisher<T>: 推送规则（应用维度）

用户只需实现 DynamicRuleProvider 和 DynamicRulePublisher 接口，并在 v2 的 controller 中通过 @Qualifier 注解替换相应的 bean 即可实现应用维度推送。我们提供了 Nacos 和 Apollo 的示例，改造详情可参考 应用维度规则推送示例。

鉴权

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

从 Sentinel 1.6.0 起，Sentinel 控制台引入基本的登录功能，默认用户名和密码都是 sentinel。

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

• -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 文件中进行配置。

控制台配置项

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

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

配置示例：

• 命令行方式：

java -Dsentinel.dashboard.app.hideAppNoMachineMillis=60000

• Java 方式：

System.setProperty("sentinel.dashboard.app.hideAppNoMachineMillis", "60000");

• 环境变量方式：

sentinel_dashboard_app_hideAppNoMachineMillis=60000

开源框架适配

• 云原生微服务体系
  • Spring Boot/Spring Cloud
  • Quarkus
• Web 适配
  • Web Servlet
  • Spring Web
  • Spring WebFlux
  • JAX-RS (Java EE)
• RPC 适配
  • Apache Dubbo
  • gRPC
  • Feign
  • SOFARPC
• HTTP client 适配
  • Apache HttpClient
  • OkHttp
• Reactive 适配
  • Reactor
• API Gateway 适配
  • Spring Cloud Gateway
  • Netflix Zuul 1.x
  • Netflix Zuul 2.x
• Apache RocketMQ

注：适配模块仅提供相应适配功能，若希望接入 Sentinel 控制台，请务必参考 Sentinel 控制台文档。

云原生微服务体系

Spring Cloud

Spring Cloud Alibaba 致力于提供微服务开发的一站式解决方案。Sentinel 与 Spring Boot/Spring Cloud 的整合见 Sentinel Spring Cloud Starter。

Spring Cloud Alibaba 默认为 Sentinel 整合了 Servlet、RestTemplate、FeignClient 和 Spring WebFlux。Sentinel 在 Spring Cloud 生态中，不仅补全了 Hystrix 在 Servlet 和 RestTemplate 这一块的空白，而且还完全兼容了 Hystrix 在 FeignClient 中限流降级的用法，并且支持运行时灵活地配置和调整限流降级规则。

Spring Cloud Alibaba Sentinel 的示例可以参考 sentinel-guide-spring-cloud

Quarkus

注：从 1.8.0 版本开始支持，需要 Java 8 及以上版本。

Sentinel 提供针对 Quarkus 微服务的适配模块（支持 native image），可以很方便地将 JAX-RS Web 服务接入并进行高可用防护，同时支持注解方式自定义埋点（基于 CDI）。

相关模块：

• sentinel-jax-rs-quarkus-adapter
• sentinel-annotation-quarkus-adapter

Web 适配

Web Servlet

Sentinel 提供针对 Servlet 的原生整合，可以对 Web 请求进行流量控制。使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-web-servlet</artifactId>
    <version>x.y.z</version>
</dependency>

您只需要在 Web 容器中的 web.xml 配置文件中进行如下配置即可开启 Sentinel 支持：

<filter>
	<filter-name>SentinelCommonFilter</filter-name>
	<filter-class>com.alibaba.csp.sentinel.adapter.servlet.CommonFilter</filter-class>
</filter>

<filter-mapping>
	<filter-name>SentinelCommonFilter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

若是 Spring 应用可以通过 Spring 进行配置，例如：

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean sentinelFilterRegistration() {
        FilterRegistrationBean<Filter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new CommonFilter());
        registration.addUrlPatterns("/*");
        registration.setName("sentinelFilter");
        registration.setOrder(1);

        return registration;
    }
}

接入 filter 之后，所有访问的 Web URL 就会被自动统计为 Sentinel 的资源，可以针对单个 URL 维度进行流控。若希望区分不同 HTTP Method，可以将 HTTP_METHOD_SPECIFY 这个 init parameter 设为 true，给每个 URL 资源加上前缀，比如 GET:/foo。

限流处理逻辑：默认情况下，当请求被限流时会返回默认的提示页面 Blocked by Sentinel (flow limiting)。您也可以通过 JVM 参数 -Dcsp.sentinel.web.servlet.block.page 或代码中调用 WebServletConfig.setBlockPage(blockPage) 方法设定自定义的跳转 URL，当请求被限流时会自动跳转至设定好的 URL。同样您也可以实现 UrlBlockHandler 接口并编写定制化的限流处理逻辑，然后将其注册至 WebCallbackManager 中。

提示：1.7.0 版本开始默认的限流页面 HTTP 返回码是 429。您可以通过 csp.sentinel.web.servlet.block.status 配置项自定义限流页面的 HTTP 状态码。

按来源限流：若希望对 HTTP 请求按照来源限流，则可以自己实现 RequestOriginParser 接口从 HTTP 请求中解析 origin 并注册至 WebCallbackManager 中。注意来源数目不能太多，若太多请自定义埋点作为参数传入并使用热点规则。

注意：Sentinel Web Filter 会将每个到来的不同的 URL 都作为不同的资源处理，因此对于 REST 风格的 API，需要自行实现 UrlCleaner 接口清洗一下资源（比如将满足 /foo/:id 的 URL 都归到 /foo/* 资源下），然后将其注册至 WebCallbackManager 中。否则会导致资源数量过多，超出资源数量阈值（目前是 6000）时多出的资源的规则将 不会生效。

从 1.6.3 版本开始，UrlCleaner 还可以来过滤掉不希望统计的 URL，只需要在 UrlCleaner 中将不希望统计的 URL 转换成空字符串（""）即可。示例：

WebCallbackManager.setUrlCleaner(new UrlCleaner() {
    @Override
    public String clean(String originUrl) {
        if (originUrl == null || originUrl.isEmpty()) {
            return originUrl;
        }

        // 比如将满足 /foo/{id} 的 URL 都归到 /foo/*
        if (originUrl.startsWith("/foo/")) {
            return "/foo/*";
        }
        // 不希望统计 *.ico 的资源文件，可以将其转换为 empty string (since 1.6.3)
        if (originUrl.endsWith(".ico")) {
            return "";
        }
        return originUrl;
    }
});

如果您正在使用 Spring Boot / Spring Cloud，那么可以通过引入 Spring Cloud Alibaba Sentinel 来更方便地整合 Sentinel，详情请见 Spring Cloud Alibaba 文档。

Spring WebFlux

注：从 1.5.0 版本开始支持，需要 Java 8 及以上版本。

Sentinel 提供与 Spring WebFlux 的整合模块，从而 Reactive Web 应用也可以利用 Sentinel 的流控降级来保障稳定性。该整合模块基于 Sentinel Reactor Adapter 实现。

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

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-spring-webflux-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

使用时只需注入对应的 SentinelWebFluxFilter 实例以及 SentinelBlockExceptionHandler 实例即可。比如：

@Configuration
public class WebFluxConfig {

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

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

    @Bean
    @Order(-1)
    public SentinelBlockExceptionHandler sentinelBlockExceptionHandler() {
        // Register the block exception handler for Spring WebFlux.
        return new SentinelBlockExceptionHandler(viewResolvers, serverCodecConfigurer);
    }

    @Bean
    @Order(-1)
    public SentinelWebFluxFilter sentinelWebFluxFilter() {
        // Register the Sentinel WebFlux filter.
        return new SentinelWebFluxFilter();
    }
}

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

• setBlockHandler：注册函数用于实现自定义的逻辑处理被限流的请求，对应接口为 BlockRequestHandler。默认实现为 DefaultBlockRequestHandler，当被限流时会返回类似于下面的错误信息：Blocked by Sentinel: FlowException。
• setUrlCleaner：注册函数用于 Web 资源名的归一化。函数类型为 (ServerWebExchange, String) → String，对应含义为 (webExchange, originalUrl) → finalUrl。
• setRequestOriginParser：注册函数用于从请求中解析请求来源。函数类型为 ServerWebExchange → String。

相关示例：sentinel-demo-spring-webflux

JAX-RS (Java EE)

注：从 1.8.0 版本开始原生支持。若您的服务是 Spring Web 服务，可参考 Spring Web 适配文档接入。

sentinel-jax-rs-adapter

RPC 适配

Dubbo

Sentinel 提供 Dubbo 的相关适配 Sentinel Dubbo Adapter，主要包括针对 Service Provider 和 Service Consumer 实现的 Filter。相关模块：

• sentinel-apache-dubbo3-adapter（兼容 Apache Dubbo 3.0.5 及以上版本，自 Sentinel 1.8.5 开始支持）
• sentinel-apache-dubbo-adapter（兼容 Apache Dubbo 2.7.x 及以上版本，自 Sentinel 1.5.1 开始支持）
• sentinel-dubbo-adapter（兼容 Dubbo 2.6.x 版本）

对于 Apache Dubbo 3.0.5 及以上版本，使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-apache-dubbo3-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

对于 Apache Dubbo 2.7.x 及以上版本，使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-apache-dubbo-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

对于 Dubbo 2.6.x 及以下版本，使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-dubbo-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

引入此依赖后，Dubbo 的服务接口和方法（包括调用端和服务端）就会成为 Sentinel 中的资源，在配置了规则后就可以自动享受到 Sentinel 的防护能力。

注：若希望接入 Dashboard，请参考 接入控制台的步骤。只引入 Sentinel Dubbo Adapter 无法接入控制台！

若不希望开启 Sentinel Dubbo Adapter 中的某个 Filter，可以手动关闭对应的 Filter，比如：

<!-- 关闭 Sentinel 对应的 Service Consumer Filter -->
<dubbo:consumer filter="-sentinel.dubbo.consumer.filter"/>

限流粒度可以是服务接口和服务方法两种粒度：

• 服务接口：resourceName 为 接口全限定名，如 com.alibaba.csp.sentinel.demo.dubbo.FooService
• 服务方法：resourceName 为 接口全限定名:方法签名，如 com.alibaba.csp.sentinel.demo.dubbo.FooService:sayHello(java.lang.String)

Sentinel Dubbo Adapter 还支持配置全局的 fallback 函数，可以在 Dubbo 服务被限流/降级/负载保护的时候进行相应的 fallback 处理。用户只需要实现自定义的 DubboFallback 接口，并通过 DubboFallbackRegistry 注册即可。默认情况会直接将 BlockException 包装后抛出。同时，我们还可以配合 Dubbo 的 fallback 机制 来为降级的服务提供替代的实现。

我们提供了 Dubbo 的相关示例，请见 sentinel-demo-dubbo。

有关 Sentinel 在 Dubbo 中的最佳实践，请参考 Sentinel: Dubbo 服务的流量哨兵。

关于 Dubbo Filter 的更多信息，请参考 Dubbo Filter 文档。

gRPC

Sentinel 提供与 gRPC Java 的整合，以 gRPC ServerInterceptor 和 ClientInterceptor 的形式保护 gRPC 服务资源。使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-grpc-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

在使用 Sentinel gRPC Adapter 时，只需要将对应的 Interceptor 注册至对应的客户端或服务端中。其中客户端的示例如下：

public class ServiceClient {

    private final ManagedChannel channel;

    ServiceClient(String host, int port) {
        this.channel = ManagedChannelBuilder.forAddress(host, port)
            .intercept(new SentinelGrpcClientInterceptor()) // 在此处注册拦截器
            .build();
        // 在此处初始化客户端 stub 类
    }
}

服务端的示例如下：

import io.grpc.Server;

Server server = ServerBuilder.forPort(port)
     .addService(new MyServiceImpl()) // 添加自己的服务实现
     .intercept(new SentinelGrpcServerInterceptor()) // 在此处注册拦截器
     .build();

注意：Sentinel gRPC Adapter 目前只支持 unary call。

Feign

Feign 适配整合在 Spring Cloud Alibaba 中，可以参考 Spring Cloud Alibaba Sentinel 文档 进行接入。

SOFARPC

从 1.7.2 版本开始，Sentinel 提供 SOFARPC 的适配模块 sentinel-sofa-rpc-adapter，主要包括针对 Service Provider 和 Service Consumer 实现的 Filter。使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-sofa-rpc-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

引入此依赖后，Sentinel 会自动统计 SOFARPC 的服务接口和方法调用（包括调用端和服务端），在配置了规则后就可以自动享受到 Sentinel 的防护能力。

HTTP Client 适配

Apache HttpClient

注：从 Sentinel 1.8.0 版本开始支持。

Sentinel 提供 Apache HttpClient 的适配模块 sentinel-apache-httpclient-adapter，可以针对 HTTP client 请求进行流控和熔断。使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-apache-httpclient-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

注意目前暂不支持 AsyncHttpClient。

OkHttp

注：从 Sentinel 1.8.0 版本开始支持。

Sentinel 提供 OkHttp 的适配模块 sentinel-okhttp-adapter，可以针对 HTTP client 请求进行流控和熔断。使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-okhttp-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

Reactive 适配

Reactor

注：从 1.5.0 版本开始支持，需要 Java 8 及以上版本。

Sentinel 提供 Reactor 的适配，可以方便地在 reactive 应用中接入 Sentinel。使用时需引入以下模块（以 Maven 为例）：

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-reactor-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

Sentinel Reactor Adapter 分别针对 Mono 和 Flux 实现了对应的 Sentinel Operator，从而在各种事件触发时汇入 Sentinel 的相关逻辑。同时 Sentinel 在上层提供了 SentinelReactorTransformer 用于在组装期装入对应的 operator，用户使用时只需要通过 transform 操作符来进行变换即可。接入示例：

someService.doSomething() // return type: Mono<T> or Flux<T>
   .transform(new SentinelReactorTransformer<>(resourceName)) // 在此处进行变换
   .subscribe();

API Gateway 适配

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

Spring Cloud Gateway

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

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

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

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

使用时只需注入对应的 SentinelGatewayFilter 实例以及 SentinelGatewayBlockExceptionHandler 实例即可。比如：

@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(-1)
    public GlobalFilter sentinelGatewayFilter() {
        return new SentinelGatewayFilter();
    }
}

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

详细文档可以参考 网关限流 - Spring Cloud Gateway 文档。

Zuul 1.x

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

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

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

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-zuul-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

详细文档可以参考 网关限流 - Zuul 1.x。

如果您正在使用 Spring Cloud Zuul Starter，那么可以通过引入 spring-cloud-alibaba-sentinel-zuul 来更方便地整合 Sentinel。请参考 对应文档。

Zuul 2.x

注：从 1.7.2 版本开始支持，需要 Java 8 及以上版本。

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

• route 维度：对应 SessionContext 中的 routeVIP
• 自定义 API 维度：用户可以利用 Sentinel 提供的 API 来自定义一些 API 分组

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

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-zuul2-adapter</artifactId>
    <version>x.y.z</version>
</dependency>

详细文档可以参考 网关限流 - Zuul 2.x。

Apache RocketMQ

在 Apache RocketMQ 中，当消费者去消费消息的时候，无论是通过 pull 的方式还是 push 的方式，都可能会出现大批量的消息突刺。如果此时要处理所有消息，很可能会导致系统负载过高，影响稳定性。但其实可能后面几秒之内都没有消息投递，若直接把多余的消息丢掉则没有充分利用系统处理消息的能力。我们希望可以把消息突刺均摊到一段时间内，让系统负载保持在消息处理水位之下的同时尽可能地处理更多消息，从而起到“削峰填谷”的效果：

上图中红色的部分代表超出消息处理能力的部分。我们可以看到消息突刺往往都是瞬时的、不规律的，其后一段时间系统往往都会有空闲资源。我们希望把红色的那部分消息平摊到后面空闲时去处理，这样既可以保证系统负载处在一个稳定的水位，又可以尽可能地处理更多消息。Sentinel 专门为这种场景提供了匀速器的特性，可以把突然到来的大量请求以匀速的形式均摊，以固定的间隔时间让请求通过，以稳定的速度逐步处理这些请求，起到“削峰填谷”的效果，从而避免流量突刺造成系统负载过高。同时堆积的请求将会排队，逐步进行处理；当请求排队预计超过最大超时时长的时候则直接拒绝，而不是拒绝全部请求。

比如在 RocketMQ 的场景下配置了匀速模式下请求 QPS 为 5，则会每 200 ms 处理一条消息，多余的处理任务将排队；同时设置了超时时间为 5 s，预计排队时长超过 5 s 的处理任务将会直接被拒绝。示意图如下图所示：

RocketMQ 用户可以根据不同的 group 和不同的 topic 分别设置限流规则，限流控制模式设置为匀速器模式（RuleConstant.CONTROL_BEHAVIOR_RATE_LIMITER），比如：

结合 RocketMQ Client 使用 Sentinel 时，用户需要在处理消息时手动埋点。详情请见 Sentinel RocketMQ Demo。相关 Blog 见 Sentinel 为 RocketMQ 保驾护航。