简介
Sentinel 可以简单的分为 Sentinel 核心库和 Dashboard。核心库不依赖 Dashboard，但是结合 Dashboard 可以取得最好的效果。
这篇文章主要介绍 Sentinel 核心库的使用。如果希望有一个最快最直接的了解，可以参考 新手指南 来获取一个最直观的感受。
我们说的资源，可以是任何东西，服务，服务里的方法，甚至是一段代码。使用 Sentinel 来进行资源保护，主要分为几个步骤:
-
定义资源
-
定义规则
-
检验规则是否生效
先把可能需要保护的资源定义好（埋点），之后再配置规则。也可以理解为，只要有了资源，我们就可以在任何时候灵活地定义各种流量控制规则。在编码的时候，只需要考虑这个代码是否需要保护，如果需要保护，就将之定义为一个资源。
对于主流的框架，我们提供适配，只需要按照适配中的说明配置，Sentinel 就会默认定义提供的服务，方法等为资源。
定义资源
方式一：主流框架的默认适配
为了减少开发的复杂程度，我们对大部分的主流框架，例如 Web Servlet、Dubbo、Spring Cloud、gRPC、Spring WebFlux、Reactor 等都做了适配。您只需要引入对应的依赖即可方便地整合 Sentinel。可以参见: 主流框架的适配。
方式二：抛出异常的方式定义资源
SphU 包含了 try-catch 风格的 API。用这种方式，当资源发生了限流之后会抛出 BlockException。这个时候可以捕捉异常，进行限流之后的逻辑处理。示例代码如下:
// 1.5.0 版本开始可以利用 try-with-resources 特性（使用有限制）
// 资源名可使用任意有业务语义的字符串，比如方法名、接口名或其它可唯一标识的字符串。
try (Entry entry = SphU.entry("resourceName")) {
// 被保护的业务逻辑
// do something here...
} catch (BlockException ex) {
// 资源访问阻止，被限流或被降级
// 在此处进行相应的处理操作
}
特别地，若 entry 的时候传入了热点参数，那么 exit 的时候也一定要带上对应的参数（exit(count, args)），否则可能会有统计错误。这个时候不能使用 try-with-resources 的方式。另外通过 Tracer.trace(ex) 来统计异常信息时，由于 try-with-resources 语法中 catch 调用顺序的问题，会导致无法正确统计异常数，因此统计异常信息时也不能在 try-with-resources 的 catch 块中调用 Tracer.trace(ex)。
手动 exit 示例：
Entry entry = null;
// 务必保证 finally 会被执行
try {
// 资源名可使用任意有业务语义的字符串，注意数目不能太多（超过 1K），超出几千请作为参数传入而不要直接作为资源名
// EntryType 代表流量类型（inbound/outbound），其中系统规则只对 IN 类型的埋点生效
entry = SphU.entry("自定义资源名");
// 被保护的业务逻辑
// do something...
} catch (BlockException ex) {
// 资源访问阻止，被限流或被降级
// 进行相应的处理操作
} catch (Exception ex) {
// 若需要配置降级规则，需要通过这种方式记录业务异常
Tracer.traceEntry(ex, entry);
} finally {
// 务必保证 exit，务必保证每个 entry 与 exit 配对
if (entry != null) {
entry.exit();
}
}
热点参数埋点示例：
Entry entry = null;
try {
// 若需要配置例外项，则传入的参数只支持基本类型。
// EntryType 代表流量类型，其中系统规则只对 IN 类型的埋点生效
// count 大多数情况都填 1，代表统计为一次调用。
entry = SphU.entry(resourceName, EntryType.IN, 1, paramA, paramB);
// Your logic here.
} catch (BlockException ex) {
// Handle request rejection.
} finally {
// 注意：exit 的时候也一定要带上对应的参数，否则可能会有统计错误。
if (entry != null) {
entry.exit(1, paramA, paramB);
}
}
SphU.entry() 的参数描述：
| 参数名 | 类型 | 解释 | 默认值 |
|---|---|---|---|
| entryType | EntryType | 资源调用的流量类型，是入口流量（EntryType.IN）还是出口流量（EntryType.OUT），注意系统规则只对 IN 生效 | EntryType.OUT |
| count | int | 本次资源调用请求的 token 数目 | 1 |
| args | Object[] | 传入的参数，用于热点参数限流 | 无 |
注意：SphU.entry(xxx) 需要与 entry.exit() 方法成对出现，匹配调用，否则会导致调用链记录异常，抛出 ErrorEntryFreeException 异常。常见的错误：
-
自定义埋点只调用
SphU.entry()，没有调用entry.exit() -
顺序错误，比如：
entry1 -> entry2 -> exit1 -> exit2，应该为entry1 -> entry2 -> exit2 -> exit1
方式三：返回布尔值方式定义资源
SphO 提供 if-else 风格的 API。用这种方式，当资源发生了限流之后会返回 false，这个时候可以根据返回值，进行限流之后的逻辑处理。示例代码如下:
// 资源名可使用任意有业务语义的字符串
if (SphO.entry("自定义资源名")) {
// 务必保证finally会被执行
try {
/**
* 被保护的业务逻辑
*/
} finally {
SphO.exit();
}
} else {
// 资源访问阻止，被限流或被降级
// 进行相应的处理操作
}
注意：SphO.entry(xxx) 需要与 SphO.exit()方法成对出现，匹配调用，位置正确，否则会导致调用链记录异常，抛出ErrorEntryFreeException` 异常。
方式四：注解方式定义资源
Sentinel 支持通过 @SentinelResource 注解定义资源并配置 blockHandler 和 fallback 函数来进行限流之后的处理。示例：
// 原本的业务方法.
@SentinelResource(blockHandler = "blockHandlerForGetUser")
public User getUserById(String id) {
throw new RuntimeException("getUserById command failed");
}
// blockHandler 函数，原方法调用被限流/降级/系统保护的时候调用
public User blockHandlerForGetUser(String id, BlockException ex) {
return new User("admin");
}
注意 blockHandler 函数会在原方法被限流/降级/系统保护的时候调用，而 fallback 函数会针对所有类型的异常。请注意 blockHandler 和 fallback 函数的形式要求，更多指引可以参见 Sentinel 注解支持文档。
方式五：异步调用支持
Sentinel 支持异步调用链路的统计。在异步调用中，需要通过 SphU.asyncEntry(xxx) 方法定义资源，并通常需要在异步的回调函数中调用 exit 方法。以下是一个简单的示例：
try {
AsyncEntry entry = SphU.asyncEntry(resourceName);
// 异步调用.
doAsync(userId, result -> {
try {
// 在此处处理异步调用的结果.
} finally {
// 在回调结束后 exit.
entry.exit();
}
});
} catch (BlockException ex) {
// Request blocked.
// Handle the exception (e.g. retry or fallback).
}
SphU.asyncEntry(xxx) 不会影响当前（调用线程）的 Context，因此以下两个 entry 在调用链上是平级关系（处于同一层），而不是嵌套关系：
// 调用链类似于： // -parent // ---asyncResource // ---syncResource asyncEntry = SphU.asyncEntry(asyncResource); entry = SphU.entry(normalResource);
若在异步回调中需要嵌套其它的资源调用（无论是 entry 还是 asyncEntry），只需要借助 Sentinel 提供的上下文切换功能，在对应的地方通过 ContextUtil.runOnContext(context, f) 进行 Context 变换，将对应资源调用处的 Context 切换为生成的异步 Context，即可维持正确的调用链路关系。示例如下：
public void handleResult(String result) {
Entry entry = null;
try {
entry = SphU.entry("handleResultForAsync");
// Handle your result here.
} catch (BlockException ex) {
// Blocked for the result handler.
} finally {
if (entry != null) {
entry.exit();
}
}
}
public void someAsync() {
try {
AsyncEntry entry = SphU.asyncEntry(resourceName);
// Asynchronous invocation.
doAsync(userId, result -> {
// 在异步回调中进行上下文变换，通过 AsyncEntry 的 getAsyncContext 方法获取异步 Context
ContextUtil.runOnContext(entry.getAsyncContext(), () -> {
try {
// 此处嵌套正常的资源调用.
handleResult(result);
} finally {
entry.exit();
}
});
});
} catch (BlockException ex) {
// Request blocked.
// Handle the exception (e.g. retry or fallback).
}
}
此时的调用链就类似于：
-parent
---asyncInvocation
-----handleResultForAsync
更详细的示例可以参考 Demo 中的 AsyncEntryDemo，里面包含了普通资源与异步资源之间的各种嵌套示例。
规则的种类
Sentinel 的所有规则都可以在内存态中动态地查询及修改，修改之后立即生效。同时 Sentinel 也提供相关 API，供您来定制自己的规则策略。
Sentinel 支持以下几种规则：流量控制规则、熔断降级规则、系统保护规则、来源访问控制规则 和 热点参数规则。
流量控制规则 (FlowRule)
流量规则的定义
重要属性：
| Field | 说明 | 默认值 |
|---|---|---|
| resource | 资源名，资源名是限流规则的作用对象 | |
| count | 限流阈值 | |
| grade | 限流阈值类型，QPS 模式（1）或并发线程数模式（0） | QPS 模式 |
| limitApp | 流控针对的调用来源 | default，代表不区分调用来源 |
| strategy | 调用关系限流策略：直接、链路、关联 | 根据资源本身（直接） |
| controlBehavior | 流控效果（直接拒绝/WarmUp/匀速+排队等待），不支持按调用关系限流 | 直接拒绝 |
| clusterMode | 是否集群限流 | 否 |
同一个资源可以同时有多个限流规则，检查规则时会依次检查。
通过代码定义流量控制规则
理解上面规则的定义之后，我们可以通过调用 FlowRuleManager.loadRules() 方法来用硬编码的方式定义流量控制规则，比如：
private void initFlowQpsRule() {
List<FlowRule> rules = new ArrayList<>();
FlowRule rule = new FlowRule(resourceName);
// set limit qps to 20
rule.setCount(20);
rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
rule.setLimitApp("default");
rules.add(rule);
FlowRuleManager.loadRules(rules);
}
更多详细内容可以参考 流量控制。
熔断降级规则 (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() 方法来用硬编码的方式定义流量控制规则。
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() 方法来用硬编码的方式定义流量控制规则。
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 来获取所有已加载的规则：
http://localhost:8719/getRules?type=<XXXX>
其中，type=flow 以 JSON 格式返回现有的限流规则，degrade 返回现有生效的降级规则列表，system 则返回系统保护规则。
获取所有热点规则：
http://localhost:8719/getParamRules
定制自己的持久化规则
上面的规则配置，都是存在内存中的。即如果应用重启，这个规则就会失效。因此我们提供了开放的接口，您可以通过实现 DataSource 接口的方式，来自定义规则的存储数据源。通常我们的建议有：
-
整合动态配置系统，如 ZooKeeper、Nacos、Apollo 等，动态地实时刷新配置规则
-
结合 RDBMS、NoSQL、VCS 等来实现该规则
-
配合 Sentinel Dashboard 使用
更多详情请参考 动态规则配置。
规则生效的效果
判断限流降级异常
在 Sentinel 中所有流控降级相关的异常都是异常类 BlockException 的子类：
-
流控异常：
FlowException -
熔断降级异常：
DegradeException -
系统保护异常：
SystemBlockException -
热点参数限流异常：
ParamFlowException
我们可以通过以下函数判断是否为 Sentinel 的流控降级异常：
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 用于记录业务异常。相关方法：
-
trace(Throwable e)：记录业务异常（非BlockException异常），对应的资源为当前线程 context 下 entry 对应的资源。该方法必须在SphU.entry(xxx)成功之后且 exit 之前调用，否则当前 context 为空则会抛出异常。 -
trace(Throwable e, int count)：记录业务异常（非BlockException异常），异常数目为传入的count。该方法必须在SphU.entry(xxx)成功之后且 exit 之前调用，否则当前 context 为空则会抛出异常。 -
traceEntry(Throwable, int, Entry)：向传入 entry 对应的资源记录业务异常（非BlockException异常），异常数目为传入的count。
如果用户通过 SphU 或 SphO 手动定义资源，则 Sentinel 不能感知上层业务的异常，需要手动调用 Tracer.trace(ex) 来记录业务异常，否则对应的异常不会统计到 Sentinel 异常计数中。注意不要在 try-with-resources 形式的 SphU.entry(xxx) 中使用，否则会统计不上。
从 1.3.1 版本开始，注解方式定义资源支持自动统计业务异常，无需手动调用 Tracer.trace(ex) 来记录业务异常。Sentinel 1.3.1 以前的版本需要手动记录。
上下文工具类 ContextUtil
相关静态方法：
标识进入调用链入口（上下文）：
以下静态方法用于标识调用链路入口，用于区分不同的调用链路：
-
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 的变换。
1636
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
