简介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 异常。常见的错误:
方式三:返回布尔值方式定义资源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 接口的方式,来自定义规则的存储数据源。通常我们的建议有: 更多详情请参考 动态规则配置。
规则生效的效果
判断限流降级异常在 Sentinel 中所有流控降级相关的异常都是异常类 BlockException 的子类: 我们可以通过以下函数判断是否为 Sentinel 的流控降级异常: BlockException.isBlockException(Throwable t); 除了在业务代码逻辑上看到规则生效,我们也可以通过下面简单的方法,来校验规则生效的效果:
block 事件Sentinel 提供以下扩展接口,可以通过 StatisticSlotCallbackRegistry 向 StatisticSlot 注册回调函数: 可以利用这些回调接口来实现报警等功能,实时的监控信息可以从 ClusterNode 中实时获取。
其它 API
业务异常统计 Tracer业务异常记录类 Tracer 用于记录业务异常。相关方法: 如果用户通过 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 。 注意: 退出调用链(清空上下文): 获取当前线程的调用链上下文: 在某个调用链上下文中执行代码:
Dashboard详情请参考:Sentinel Dashboard 文档。
|