Advanced Guide
Sentinel Console
Sentinel provides out-of-the-box consoles:
There are 3 steps to enable this feature:
Get console
You can download the latest version of the console jar package from the Release page.
You can also build Sentinel Console yourself from the latest version of the source code:
Download Dashboard project.
Package the code into a fat jar with the following command:
$ mvn clean package
Start the console
The Sentinel console is a standard Spring Boot application, just run the jar package in the Spring Boot way.
$ java -Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080 -Dproject.name=sentinel-dashboard -jar sentinel-dashboard.jar
If port 8080 conflicts, use -Dserver.port=new port to set it.
In the application configuration file, add the following console configuration information:
spring:
cloud:
sentinel:
transport:
port: 8719
dashboard: localhost:8080
The spring.cloud.sentinel.transport.port port configuration here will start an Http Server on the machine corresponding to the application, which will interact with the Sentinel console. For example, if a current limiting rule is added to the Sentinel console, the rule data will be pushed to the Http Server for reception, and the Http Server will then register the rule in Sentinel.
For more usage and problems of Sentinel console, please refer to Sentinel Console.
Client support
The Sentinel-related Starter provided by Spring Cloud Alibaba provides adaptation support for mainstream client components such as OpenFeign and RestTemplate in the Spring Cloud ecosystem.
OpenFeign
spring-cloud-starter-alibaba-sentinel is adapted to the OpenFeign component. If you want to use it, in addition to introducing the necessary Starter dependencies, you also need to enable sentinel's support for feign in the configuration file: feign.sentinel.enabled=true.
Here is a simple usage example of 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: The resource name policy definition in the interface corresponding to Feign: httpmethod:protocol://requesturl. All attributes in the @FeignClient annotation are compatible with Sentinel.
The name of the resource corresponding to the method echo in the EchoService interface is GET:http://service-provider/echo/{str}.
RestTemplate
spring-cloud-starter-alibaba-sentinel supports using Sentinel to protect RestTemplate service calls. When constructing a RestTemplate bean, you need to add the @SentinelRestTemplate annotation.
@Bean
@SentinelRestTemplate(blockHandler = "handleException", blockHandlerClass = ExceptionUtil.class)
public RestTemplate restTemplate() {
return new RestTemplate();
}
The properties of the @SentinelRestTemplate annotation support the processing of current limiting (blockHandler, blockHandlerClass) and degradation (fallback, fallbackClass).
The method corresponding to the blockHandler or fallback attribute must be a static method in the corresponding blockHandlerClass or fallbackClass attribute.
The parameters and return value of this method are consistent with the org.springframework.http.client.ClientHttpRequestInterceptor#interceptor method, and the parameter has an additional BlockException parameter to obtain the exception caught by Sentinel.
For example, the method declaration corresponding to the handleException attribute of ExceptionUtil in the above @SentinelRestTemplate annotation is as follows:
public class ExceptionUtil {
public static ClientHttpResponse handleException(HttpRequest request, byte[] body, ClientHttpRequestExecution execution, BlockException exception) {
...
}
}
NOTE: When the application starts, it will check whether the current limiting or downgrading method corresponding to the @SentinelRestTemplate annotation exists, and an exception will be thrown if it does not exist
The current limiting (blockHandler, blockHandlerClass) and downgrading (fallback, fallbackClass) attributes of the @SentinelRestTemplate annotation are not mandatory.
When the RestTemplate call is broken by Sentinel, it will return the RestTemplate request block by sentinel information, or you can write the corresponding method to process the returned information by yourself. SentinelClientHttpResponse is provided here for constructing return information.
The resource rules of Sentinel RestTemplate current limiting provide two granularities:
httpmethod:schema://host:port/path: protocol, host, port and path
httpmethod:schema://host:port: protocol, host and port
NOTE: Take the url https://www.taobao.com/test and use the GET method as an example. The corresponding resource names have two granularities, namely GET:https://www.taobao.com and GET:https://www.taobao.com/test.
Dynamic data source support
SentinelProperties internally provides the datasource property of TreeMap type for configuring data source information.
For example, configure 4 data sources:
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
This configuration method refers to the configuration of Spring Cloud Stream Binder, which uses TreeMap for storage internally, and the comparator is String.CASE_INSENSITIVE_ORDER.
NOTE: d1, ds2, ds3, ds4 are the names of ReadableDataSource and can be freely written. The following file, zk, nacos, and apollo correspond to specific data sources. The configuration behind them is the respective configuration of these specific data sources.
Each data source has two common configuration items: data-type, converter-class and rule-type.
The data-type configuration item indicates the Converter type. Spring Cloud Alibaba Sentinel provides two built-in values by default, namely json and xml (if not filled, the default is json). If you don't want to use the built-in json or xml Converter, you can fill in custom to represent the custom Converter, and then configure the converter-class configuration item, which needs to write the full path name of the class (such as spring.cloud.sentinel.datasource. ds1.file.converter-class=org.springframework.cloud.alibaba.cloud.examples.JsonFlowRuleListConverter).
The rule-type configuration indicates which type of rules the rules in the data source belong to (flow, degrade, authority, system, param-flow, gw-flow, gw-api-group).
NOTE: When a data source rule information fails to load, it will not affect the startup of the application, and an error message will be printed in the log.
NOTE: By default, xml format is not supported. It will take effect automatically after adding jackson-dataformat-xml dependency.
For the implementation principle of Sentinel dynamic data source, refer to: [Dynamic rule extension](https://github.com/alibaba/Sentinel/wiki/%E5%8A%A8%E6%80%81%E8%A7%84% E5%88%99%E6%89%A9%E5%B1%95).
Spring Cloud Gateway support
Refer to Sentinel Gateway Current Limiting.
If you want to use it with Sentinel Starter, you need to add the spring-cloud-alibaba-sentinel-gateway dependency, and you need to add the spring-cloud-starter-gateway dependency to make the Spring Cloud Gateway in the spring-cloud-alibaba-sentinel-gateway module The automatic configuration class takes effect:
<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>
Externally exposed Endpoint
Sentinel provides an Endpoint internally, and the corresponding endpoint id is sentinel.
The json exposed by Endpoint contains various properties:
- appName: application name
- logDir: the directory where the log is located
- logUsePid: whether to carry the process id in the log file name
- blockPage: The page to be redirected after the current limiting block
- metricsFileSize: The size of the metrics file
- metricsFileCharset: the character set corresponding to the metrics file
- totalMetricsFileCount: the maximum number of files retained by metrics
- consoleServer: sentinel dashboard address
- clientIp: client ip
- heartbeatIntervalMs: heartbeat interval between client and dashboard
- clientPort: The port that the client needs to expose to interact with the dashboard
- coldFactor: cold start factor
- filter: CommonFilter related attributes, such as order, urlPatterns and enable
- datasource: the data source information configured by the client
- rules: rules that take effect on the client side, including flowRules, degradeRules, systemRules, authorityRule, paramFlowRule
Here is an example of json exposed by Endpoint:
{
"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
}
More configuration items
The following table shows that when there is a corresponding bean type in the ApplicationContext of the application, automatic settings will be performed:
Type of Bean | Operation | Function |
---|---|---|
UrlCleaner | WebCallbackManager.setUrlCleaner(urlCleaner) | Resource cleaning (resources (for example, all URLs satisfying /foo/:id are grouped under /foo/* resources)) |
UrlBlockHandler | WebCallbackManager.setUrlBlockHandler(urlBlockHandler) | Custom flow limit processing logic |
RequestOriginParser | WebCallbackManager.setRequestOriginParser(requestOriginParser) | Set source information |
Spring Cloud Alibaba Sentinel provides these configuration options:
Configuration Item | key | Default Value | Description |
---|---|---|---|
project name | spring.application.name or project.name | application | Sentinel project name |
Automatic configuration | spring.cloud.sentinel.enabled | true | Whether Sentinel is effective |
Sentinel initialization | spring.cloud.sentinel.eager | false | Whether to trigger Sentinel initialization in advance |
Sentinel Console Interaction Port | spring.cloud.sentinel.transport.port | 8719 | The port used by the application to interact with the Sentinel console, the application will locally start a HttpServer occupied by this port |
Console address | spring.cloud.sentinel.transport.dashboard | 8719 | Sentinel console address |
Heartbeat interval | spring.cloud.sentinel.transport.heartbeat-interval-ms | Heartbeat interval between application and Sentinel console | |
Registration IP | spring.cloud.sentinel.transport.client-ip | The client IP of this configuration will be registered to the Sentinel Server | |
Filter Loading Order | spring.cloud.sentinel.filter.order | The loading order of Servlet Filter. The filter will be constructed inside the Starter | |
url pattern collection | spring.cloud.sentinel.filter.url-patterns | The data type is an array. Represents the url pattern collection of Servlet Filter | |
Whether to enable CommonFilter | spring.cloud.sentinel.filter.enabled | true | Enable to instance CommonFilter |
metric file character set | spring.cloud.sentinel.metric.charset | metric file character set | |
metric single file size | spring.cloud.sentinel.metric.file-single-size | Sentinel metric single file size | |
metric total file count | spring.cloud.sentinel.metric.file-total-count | metric total file count | |
Log file path | spring.cloud.sentinel.log.dir | Directory where Sentinel log files are located | |
Whether to append the log PID | spring.cloud.sentinel.log.switch-pid | false | Whether the Sentinel log file name needs to carry the pid |
Redirect URL | spring.cloud.sentinel.servlet.block-page | Customized redirect URL, when the request is limited, it will automatically redirect to the set URL | |
Cold start factor | spring.cloud.sentinel.flow.cold-factor | [Cold start factor](https://github.com/alibaba/Sentinel/wiki/%E9%99%90%E6%B5%81 ---%E5%86%B7%E5%90%AF%E5%8A%A8) | |
Response mode after fuse | spring.cloud.sentinel.scg.fallback.mode | Response mode after Spring Cloud Gateway fuse (choose redirect or response) | |
Redirect URL when it is redirect | spring.cloud.sentinel.scg.fallback.redirect | Spring Cloud Gateway response mode is the redirect URL corresponding to redirect mode | |
Response content redirected when it is response | spring.cloud.sentinel.scg.fallback.response-body | The response mode of Spring Cloud Gateway is the response content corresponding to the response mode | |
Response code for redirection when it is response | spring.cloud.sentinel.scg.fallback.response-status | 429 | The response mode of Spring Cloud Gateway is the response code corresponding to response mode |
Content-Type redirected when it is response | spring.cloud.sentinel.scg.fallback.content-type | application/json | Spring Cloud Gateway response mode is the content-type corresponding to response mode |
NOTE: Please note. These configurations will only take effect in the Servlet environment, and neither RestTemplate nor OpenFeign will take effect for these configurations.