title | keywords | description | ||
---|---|---|---|---|
进阶指南 |
|
sentinel, Advanced Guide. |
开启该功能需要 3 个步骤:
您可以从 Release 页面 下载最新版本的控制台 jar 包。
您也可以从最新版本的源码自行构建 Sentinel 控制台:
-
下载 控制台 工程。
-
使用以下命令将代码打包成一个 fat jar:
$ mvn clean package
Sentinel 控制台是一个标准的 Spring Boot 应用,以 Spring Boot 的方式运行 jar 包即可。
$ java -Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080 -Dproject.name=sentinel-dashboard -jar sentinel-dashboard.jar
如若 8080 端口冲突,可使用 -Dserver.port=新端口 进行设置。
在应用的配置文件中,增加如下控制台配置信息:
spring:
cloud:
sentinel:
transport:
port: 8719
dashboard: localhost:8080
这里的 spring.cloud.sentinel.transport.port 端口配置会在应用对应的机器上启动一个 Http Server,该 Server 会与 Sentinel 控制台做交互。比如 Sentinel 控制台添加了 1 个限流规则,会把规则数据 push 给这个 Http Server 接收,Http Server 再将规则注册到 Sentinel 中。
更多 Sentinel 控制台的使用及问题参考 Sentinel 控制台。
Spring Cloud Alibaba 提供的 Sentinel 有关 Starter 提供了对 Spring Cloud 生态中如 OpenFeign、RestTemplate 等主流的客户端组件的适配支持。
spring-cloud-starter-alibaba-sentinel 适配了 OpenFeign 组件。如果想使用,除了引入必要的 Starter 依赖外还需要在配置文件打开 sentinel 对 feign 的支持:feign.sentinel.enabled=true。
这是一个 FeignClient 的简单使用示例:
@FeignClient(name = "service-provider", fallback = EchoServiceFallback.class, configuration = FeignConfiguration.class)
public interface EchoService {
@GetMapping(value = "/echo/{str}")
String echo(@PathVariable("str") String str);
}
class FeignConfiguration {
@Bean
public EchoServiceFallback echoServiceFallback() {
return new EchoServiceFallback();
}
}
class EchoServiceFallback implements EchoService {
@Override
public String echo(@PathVariable("str") String str) {
return "echo fallback";
}
}
NOTE: Feign 对应的接口中的资源名策略定义:httpmethod:protocol://requesturl。@FeignClient 注解中的所有属性,Sentinel 都做了兼容。
EchoService 接口中方法 echo 对应的资源名为 GET:http://service-provider/echo/{str}。
spring-cloud-starter-alibaba-sentinel 支持对 RestTemplate 的服务调用使用 Sentinel 进行保护,在构造 RestTemplate bean 的时候需要加上 @SentinelRestTemplate 注解。
@Bean
@SentinelRestTemplate(blockHandler = "handleException", blockHandlerClass = ExceptionUtil.class)
public RestTemplate restTemplate() {
return new RestTemplate();
}
@SentinelRestTemplate 注解的属性支持限流(blockHandler, blockHandlerClass)和降级(fallback, fallbackClass)的处理。
其中 blockHandler 或 fallback 属性对应的方法必须是对应 blockHandlerClass 或 fallbackClass 属性中的静态方法。
该方法的参数跟返回值跟 org.springframework.http.client.ClientHttpRequestInterceptor#interceptor 方法一致,其中参数多出了一个 BlockException 参数用于获取 Sentinel 捕获的异常。
比如上述 @SentinelRestTemplate 注解中 ExceptionUtil 的 handleException 属性对应的方法声明如下:
public class ExceptionUtil {
public static ClientHttpResponse handleException(HttpRequest request, byte[] body, ClientHttpRequestExecution execution, BlockException exception) {
...
}
}
NOTE: 应用启动的时候会检查 @SentinelRestTemplate 注解对应的限流或降级方法是否存在,如不存在会抛出异常
@SentinelRestTemplate 注解的限流(blockHandler, blockHandlerClass)和降级(fallback, fallbackClass)属性不强制填写。
当使用 RestTemplate 调用被 Sentinel 熔断后,会返回 RestTemplate request block by sentinel 信息,或者也可以编写对应的方法自行处理返回信息。这里提供了 SentinelClientHttpResponse 用于构造返回信息。
Sentinel RestTemplate 限流的资源规则提供两种粒度:
-
httpmethod:schema://host:port/path:协议、主机、端口和路径
-
httpmethod:schema://host:port:协议、主机和端口
NOTE: 以 https://www.taobao.com/test 这个 url 并使用 GET 方法为例。对应的资源名有两种粒度,分别是 GET:https://www.taobao.com 以及 GET:https://www.taobao.com/test。
SentinelProperties 内部提供了 TreeMap 类型的 datasource 属性用于配置数据源信息。
比如配置 4 个数据源:
spring.cloud.sentinel.datasource.ds1.file.file=classpath: degraderule.json
spring.cloud.sentinel.datasource.ds1.file.rule-type=flow
#spring.cloud.sentinel.datasource.ds1.file.file=classpath: flowrule.json
#spring.cloud.sentinel.datasource.ds1.file.data-type=custom
#spring.cloud.sentinel.datasource.ds1.file.converter-class=org.springframework.cloud.alibaba.cloud.examples.JsonFlowRuleListConverter
#spring.cloud.sentinel.datasource.ds1.file.rule-type=flow
spring.cloud.sentinel.datasource.ds2.nacos.server-addr=127.0.0.1:8848
spring.cloud.sentinel.datasource.ds2.nacos.data-id=sentinel
spring.cloud.sentinel.datasource.ds2.nacos.group-id=DEFAULT_GROUP
spring.cloud.sentinel.datasource.ds2.nacos.data-type=json
spring.cloud.sentinel.datasource.ds2.nacos.rule-type=degrade
spring.cloud.sentinel.datasource.ds3.zk.path = /Sentinel-Demo/SYSTEM-CODE-DEMO-FLOW
spring.cloud.sentinel.datasource.ds3.zk.server-addr = localhost:2181
spring.cloud.sentinel.datasource.ds3.zk.rule-type=authority
spring.cloud.sentinel.datasource.ds4.apollo.namespace-name = application
spring.cloud.sentinel.datasource.ds4.apollo.flow-rules-key = sentinel
spring.cloud.sentinel.datasource.ds4.apollo.default-flow-rule-value = test
spring.cloud.sentinel.datasource.ds4.apollo.rule-type=param-flow
这种配置方式参考了 Spring Cloud Stream Binder 的配置,内部使用了 TreeMap 进行存储,comparator 为 String.CASE_INSENSITIVE_ORDER 。
NOTE: d1, ds2, ds3, ds4 是 ReadableDataSource 的名字,可随意编写。后面的 file ,zk ,nacos , apollo 就是对应具体的数据源。 它们后面的配置就是这些具体数据源各自的配置。
每种数据源都有两个共同的配置项: data-type、 converter-class 以及 rule-type。
data-type 配置项表示 Converter 类型,Spring Cloud Alibaba Sentinel 默认提供两种内置的值,分别是 json 和 xml (不填默认是 json)。 如果不想使用内置的 json 或 xml 这两种 Converter,可以填写 custom 表示自定义 Converter,然后再配置 converter-class 配置项,该配置项需要写类的全路径名(比如 spring.cloud.sentinel.datasource.ds1.file.converter-class=org.springframework.cloud.alibaba.cloud.examples.JsonFlowRuleListConverter)。
rule-type 配置表示该数据源中的规则属于哪种类型的规则(flow,degrade,authority, system, param-flow, gw-flow, gw-api-group)。
NOTE: 当某个数据源规则信息加载失败的情况下,不会影响应用的启动,会在日志中打印出错误信息。
NOTE: 默认情况下,xml 格式是不支持的。需要添加 jackson-dataformat-xml 依赖后才会自动生效。
关于 Sentinel 动态数据源的实现原理,参考: 动态规则扩展。
参考 Sentinel 网关限流。
若想跟 Sentinel Starter 配合使用,需要加上 spring-cloud-alibaba-sentinel-gateway 依赖,同时需要添加 spring-cloud-starter-gateway 依赖来让 spring-cloud-alibaba-sentinel-gateway 模块里的 Spring Cloud Gateway 自动化配置类生效:
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-alibaba-sentinel-gateway</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
Sentinel 内部提供了一个 Endpoint, 对应的 endpoint id 为 sentinel。
Endpoint 暴露的 json 中包含了多种属性:
- appName: 应用名
- logDir: 日志所在目录
- logUsePid: 日志文件名是否带上进程 id
- blockPage: 限流 block 之后跳转的页面
- metricsFileSize: metrics 文件的大小
- metricsFileCharset: metrics 文件对应的字符集
- totalMetricsFileCount: metrics 最多保留的文件数
- consoleServer: sentinel dashboard 地址
- clientIp: 客户端 ip
- heartbeatIntervalMs: 客户端跟 dashboard 的心跳间隔时间
- clientPort: 客户端需要暴露的端口跟 dashboard 进行交互
- coldFactor: 冷启动因子
- filter: CommonFilter 相关的属性, 比如 order, urlPatterns 以及 enable
- datasource: 客户端配置的数据源信息
- rules: 客户端生效的规则,内部含有 flowRules, degradeRules, systemRules, authorityRule, paramFlowRule
这是 Endpoint 暴露的 json 示例:
{
"blockPage": null,
"appName": "sentinel-example",
"consoleServer": "localhost:8080",
"coldFactor": "3",
"rules": {
"flowRules": [
{
"resource": "GET:http://www.taobao.com",
"limitApp": "default",
"grade": 1,
"count": 0.0,
"strategy": 0,
"refResource": null,
"controlBehavior": 0,
"warmUpPeriodSec": 10,
"maxQueueingTimeMs": 500,
"clusterMode": false,
"clusterConfig": null
},
{
"resource": "/test",
"limitApp": "default",
"grade": 1,
"count": 0.0,
"strategy": 0,
"refResource": null,
"controlBehavior": 0,
"warmUpPeriodSec": 10,
"maxQueueingTimeMs": 500,
"clusterMode": false,
"clusterConfig": null
},
{
"resource": "/hello",
"limitApp": "default",
"grade": 1,
"count": 1.0,
"strategy": 0,
"refResource": null,
"controlBehavior": 0,
"warmUpPeriodSec": 10,
"maxQueueingTimeMs": 500,
"clusterMode": false,
"clusterConfig": null
}
]
},
"metricsFileCharset": "UTF-8",
"filter": {
"order": -2147483648,
"urlPatterns": ["/*"],
"enabled": true
},
"totalMetricsFileCount": 6,
"datasource": {
"ds1": {
"file": {
"dataType": "json",
"ruleType": "FLOW",
"converterClass": null,
"file": "...",
"charset": "utf-8",
"recommendRefreshMs": 3000,
"bufSize": 1048576
},
"nacos": null,
"zk": null,
"apollo": null,
"redis": null
}
},
"clientIp": "30.5.121.91",
"clientPort": "8719",
"logUsePid": false,
"metricsFileSize": 52428800,
"logDir": "...",
"heartbeatIntervalMs": 10000
}
下表显示当应用的 ApplicationContext 中存在对应的 Bean 的类型时,会进行自动化设置:
存在 Bean 的类型 | 操作 | 作用 |
---|---|---|
UrlCleaner | WebCallbackManager.setUrlCleaner(urlCleaner) | 资源清理(资源(比如将满足 /foo/:id 的 URL 都归到 /foo/* 资源下)) |
UrlBlockHandler | WebCallbackManager.setUrlBlockHandler(urlBlockHandler) | 自定义限流处理逻辑 |
RequestOriginParser | WebCallbackManager.setRequestOriginParser(requestOriginParser) | 设置来源信息 |
Spring Cloud Alibaba Sentinel 提供了这些配置选项:
配置项 | key | 默认值 | 说明 |
---|---|---|---|
项目名 | spring.application.name or project.name | application | Sentinel 项目名称 |
自动化配置 | spring.cloud.sentinel.enabled | true | Sentinel 是否生效 |
Sentinel 初始化 | spring.cloud.sentinel.eager | false | 是否提前触发 Sentinel 初始化 |
Sentinel 控制台交互端口 | spring.cloud.sentinel.transport.port | 8719 | 应用与 Sentinel 控制台交互的端口,应用本地会起一个该端口占用的 HttpServer |
控制台地址 | spring.cloud.sentinel.transport.dashboard | 8719 | Sentinel 控制台地址 |
心跳间隔时间 | spring.cloud.sentinel.transport.heartbeat-interval-ms | 应用与 Sentinel 控制台的心跳间隔时间 | |
注册 IP | spring.cloud.sentinel.transport.client-ip | 此配置的客户端 IP 将被注册到 Sentinel Server 端 | |
过滤器加载顺序 | spring.cloud.sentinel.filter.order | Servlet Filter 的加载顺序。Starter 内部会构造这个 filter | |
url pattern 集合 | spring.cloud.sentinel.filter.url-patterns | 数据类型是数组。表示 Servlet Filter 的 url pattern 集合 | |
是否开启 CommonFilter | spring.cloud.sentinel.filter.enabled | true | Enable to instance CommonFilter |
metric 文件字符集 | spring.cloud.sentinel.metric.charset | metric 文件字符集 | |
metric 单个文件的大小 | spring.cloud.sentinel.metric.file-single-size | Sentinel metric 单个文件的大小 | |
metric 总文件数量 | spring.cloud.sentinel.metric.file-total-count | metric 总文件数量 | |
日志文件路径 | spring.cloud.sentinel.log.dir | Sentinel 日志文件所在的目录 | |
是否追加日志 PID | spring.cloud.sentinel.log.switch-pid | false | Sentinel 日志文件名是否需要带上 pid |
跳转 URL | spring.cloud.sentinel.servlet.block-page | 自定义的跳转 URL,当请求被限流时会自动跳转至设定好的 URL | |
冷启动因子 | spring.cloud.sentinel.flow.cold-factor | 冷启动因子 | |
熔断后的响应模式 | spring.cloud.sentinel.scg.fallback.mode | Spring Cloud Gateway 熔断后的响应模式(选择 redirect or response) | |
为 redirect 时重定向的 URL | spring.cloud.sentinel.scg.fallback.redirect | Spring Cloud Gateway 响应模式为 redirect 模式对应的重定向 URL | |
为 response 时重定向的响应内容 | spring.cloud.sentinel.scg.fallback.response-body | Spring Cloud Gateway 响应模式为 response 模式对应的响应内容 | |
为 response 时重定向的响应码 | spring.cloud.sentinel.scg.fallback.response-status | 429 | Spring Cloud Gateway 响应模式为 response 模式对应的响应码 |
为 response 时重定向的 Content-Type | spring.cloud.sentinel.scg.fallback.content-type | application/json | Spring Cloud Gateway 响应模式为 response 模式对应的 content-type |
NOTE: 请注意。这些配置只有在 Servlet 环境下才会生效,RestTemplate 和 OpenFeign 针对这些配置都无法生效。