spring-cloud-alibaba/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example

Sentinel Example

Project Instruction

This example illustrates how to use Sentinel starter to implement flow control for Spring Cloud applications.

Sentinel is an open-source project of Alibaba. Sentinel takes "traffic flow" as the breakthrough point, and provides solutions in areas such as flow control, concurrency, circuit breaking, and load protection to protect service stability.

Demo

Connect to Sentinel

Before we start the demo, let's learn how to connect Sentinel to a Spring Cloud application. Note: This section is to show you how to connect to Sentinel. The configurations have been completed in the following example, so you don't need modify the code any more.

1. Add dependency spring-cloud-starter-alibaba-sentinel in the pom.xml file in your Spring Cloud project.

    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
    </dependency>
   

2. Define Resources

   1. Define HTTP Resources
      Sentinel starter defines all HTTP URLS as resources by relative paths. If you only want to add flow control for your HTTP services, you do not need to modify your code.

   2. Define Custom Resources
      If you want to implement flow control or degradation for a specific method, you can add an @SentinelResource annotation to the method, as shown in the code below.

       @SentinelResource("resource")
       public String hello() {
       	return "Hello";
       }
      

3. Configure flow control rules

   Sentinel provides two ways to configure flow control rules, init from code or configure by dashboard.

   1. Init rule from code: See the code below for a simple flow rule. See Sentinel Docs for more information about flow rules.

       List<FlowRule> rules = new ArrayList<FlowRule>();
       FlowRule rule = new FlowRule();
       rule.setResource(str);
       // set limit qps to 10
       rule.setCount(10);
       rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
       rule.setLimitApp("default");
       rules.add(rule);
       FlowRuleManager.loadRules(rules);
      

   2. Config by dashboard: See the following section.

Start Sentinel Dashboard

1. Install Sentinel dashboard by downloading a fatjar or build from source code.

   1. Download: Download Sentinel Dashboard
   2. Build from source code: Get source code by git clone git@github.com:alibaba/Sentinel.git from Github Sentinel and build your code. See build reference for details.

2. Start the dashboard by running the java -jar sentinel-dashboard.jar command. The default port of Sentinel dashboard is 8080. Sentinel dashboard is a Spring Boot project. If you want to use another port, see Spring Boot Reference.

Start Application

1. Add necessary configurations to file /src/main/resources/application.properties.

    spring.application.name=sentinel-example
    server.port=18083
    spring.cloud.sentinel.transport.dashboard=localhost:8080
   

2. Start the application in IDE or by building a fatjar.

   1. Start in IDE: Find main class ServiceApplication, and execute the main method.
   2. Build a fatjar：Execute command mvn clean package to build a fatjar, and run command java -jar sentinel-core-example.jar to start the application.

Invoke Service

Execute command curl http://127.0.0.1:18083/hello
Execute command curl http://127.0.0.1:18083/test

The screenshot belows shows invoke success:

Configure Flow Control

1. Open http://localhost:8080 in browser, and you can find a Sentinel-Example Application has been registered to the dashboard.

   Note: If you can't find your application in the dashboard, invoke a method that has been defined as a Sentinel Resource, for Sentinel uses lazy load strategy.

2. Configure HTTP Resource Flow Rule：Click 流控规则(Flow Rule) on the left-side navigation pane and 新增流控规则(Create Flow Rule). On the Create Flow Rule dialogbox, type the URL relative path in the 资源名(Resource Name) field , enter 单机阈值(Threshold) value, then click 新增(OK). Here we set threshold to 1 for demonstration purpose.

3. Configure Custom Resource Flow Rule：Click 流控规则(Flow Rule) on the left-side navigation pane and 新增流控规则(Create Flow Rule). type the value() of @SentinelResource in the 资源名(Resource Name) field , enter 单机阈值(Threshold) value, then click 新增(OK).Here we set threshold to 1 for demonstration purpose.

4. Visit the URL in your browser again. When QPS is more than 1, we can see that flow control takes effect.

Customize Flow Control Logic

• Flow control exception handle by default

When a URL resource is blocked by Sentinel, the default logic is return HTTP response "Blocked by Sentinel (flow limiting)".

If you want to customize your flow control logic, see the code below:

	public class CustomUrlBlockHandler implements UrlBlockHandler {
		@Override
		public void blocked(HttpServletRequest httpServletRequest,
		HttpServletResponse httpServletResponse) throws IOException {
			// todo add your logic
		}
	}
	
	WebCallbackManager.setUrlBlockHandler(new CustomUrlBlockHandler());

• Flow control exception handle by using @SentinelResource

When a custom resource is blocked by Sentinel, the default logic is throw BlockException.

If you want to customize your flow control logic, implement interface `SentinelExceptionHandler`, set @SentinelResource's blockHandler() and blockHandlerClass(). See the code below:

    @SentinelResource(value = "resource", blockHandler = "", blockHandlerClass = ExceptionUtil.class)
    public String hello() {
        return "Hello";
    }
    
    // ExceptionUtil.java
    public class ExceptionUtil {
        public static void handleException(BlockException ex) {
            System.out.println("Oops: " + ex.getClass().getCanonicalName());
        }
    }

Endpoint

Sentinel starter also supports the implementation of Spring Boot actuator endpoints.

Prerequisite:

Add dependency spring-boot-starter-actuator to your pom.xml file, and configure your endpoint security strategy.

• Spring Boot1.x: Add configuration management.security.enabled=false
• Spring Boot2.x: Add configuration management.endpoints.web.exposure.include=*

To view the endpoint information, visit the following URLS:

• Spring Boot1.x: Sentinel Endpoint URL is http://127.0.0.1:18083/sentinel.
• Spring Boot2.x: Sentinel Endpoint URL is http://127.0.0.1:18083/actuator/sentinel.

Metrics

You can view metrics information on Sentinel Dashboard.

To see the metrics, click 实时监控(Real-time Monitoring) in the left-side navigation pane.

p_qps stands for passed requests per second, b_qps stands for blocked requests per second.

ReadableDataSource

Sentinel provide ReadableDataSource to manage dynamic rules.

Sentinel starter integrated 4 DataSources provided by Sentinel. It will be register into Spring Context if you write some configs in application.properties.

If you want to define FileRefreshableDataSource and NacosDataSource, see the code below:

spring.cloud.sentinel.datasource.ds1.file.file=classpath: degraderule.json
spring.cloud.sentinel.datasource.ds1.file.data-type=json

spring.cloud.sentinel.datasource.ds2.nacos.server-addr=localhost:8848
spring.cloud.sentinel.datasource.ds2.nacos.dataId=sentinel
spring.cloud.sentinel.datasource.ds2.nacos.groupId=DEFAULT_GROUP
spring.cloud.sentinel.datasource.ds2.nacos.data-type=json

ds1 and ds2 means the name of ReadableDataSource, you can write whatever you want. The file and nacos after name ds1 and ds2 means the type of ReadableDataSource.

Now ReadableDataSource type support 5 categories: file, nacos, zk, apollo and redis.

If you want to use nacos, zk, apollo or redis ReadableDataSource, you could add sentinel-datasource-nacos, sentinel-datasource-zookeeper,sentinel-datasource-apollo or sentinel-datasource-redis dependency.

When ReadableDataSource load rule data successfully, console will print some logs:

[Sentinel Starter] DataSource ds1-sentinel-file-datasource load 3 DegradeRule
[Sentinel Starter] DataSource ds2-sentinel-nacos-datasource load 2 FlowRule

Warning

You should use file ReadableDataSource in a fatjar carefully or you may get error like this below

java.lang.RuntimeException: [Sentinel Starter] DataSource ds1 handle file [classpath: flowrule.json] error: class path resource [flowrule.json] cannot be resolved to absolute file path because it does not reside in the file system: jar:file:xxx/xxx.jar!/BOOT-INF/classes!/flowrule.jso

You could use absolute path when you use File datasource & fat jar. It is recommended to use Nacos/Apollo/Zookeeper/Redis datasource to store rules.

https://github.com/alibaba/spring-cloud-alibaba/issues/428

More

For more information about Sentinel, see Sentinel Project.

If you have any ideas or suggestions for Spring Cloud Sentinel starter, please don't hesitate to tell us by submitting github issues.