Comprehensive Guide to Alibaba Sentinel: Installation, Dashboard Setup, Flow Control, Degrade Rules, Hotspot Parameters, Persistence, and Cluster Flow Control

Sentinel is an open‑source flow‑control and circuit‑breaker component from Alibaba, proven in massive traffic scenarios such as Double‑11 sales, offering rich application scenarios, real‑time monitoring, extensive ecosystem integration, and a flexible SPI extension mechanism.

Compared with Hystrix, Sentinel provides more powerful flow‑control, warm‑up, and queue‑waiting strategies, and is recommended as the default solution for Spring Cloud projects.

Version selection : For the Spring Cloud Alibaba stack, use spring-cloud-alibaba-dependencies 2.2.1.RELEASE and Sentinel version 1.7.1.

Dashboard installation : Download the matching JAR from the Sentinel GitHub releases and start it with:

java -Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080 -Dproject.name=sentinel-dashboard -jar sentinel-dashboard-1.7.1.jar

The default login is sentinel/sentinel. You can customize the username and password from Sentinel 1.6.0 onward, e.g.:

java -Dsentinel.dashboard.auth.username=admin -Dsentinel.dashboard.auth.password=123 -jar sentinel-dashboard-1.7.1.jar

Microservice integration : Create a Spring Boot service (e.g., sentinel-service9008) and add the Sentinel starter dependency:

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

Configure the dashboard address in application.yml:

spring:
  cloud:
    sentinel:
      transport:
        dashboard: localhost:8080

Define a test controller:

@RestController
@RequestMapping("/sentinel")
public class FlowLimitController {
    @GetMapping("/test")
    public String test() { return "Received a message"; }
}

When the service starts, access http://localhost:9008/sentinel/test and you will see the service registered in the Sentinel console.

Flow control configuration : Sentinel supports three control behaviors – fast‑fail, warm‑up, and queue‑waiting – and three strategies – direct, associated, and chain. Example rule JSON (wrapped in ...) for a direct fast‑fail rule:

[
  {
    "resource": "/test",
    "limitApp": "default",
    "grade": 1,
    "count": 1,
    "clusterMode": false,
    "controlBehavior": 0,
    "strategy": 0,
    "warmUpPeriodSec": 10,
    "maxQueueingTimeMs": 500,
    "refResource": ""
  }
]

Warm‑up uses

com.alibaba.csp.sentinel.slots.block.flow.controller.WarmUpController

with a default cold factor of 3. Queue‑waiting uses RateLimiterController and works like a token‑bucket.

Associated flow control example: limit the /sentinel/order endpoint based on the QPS of /sentinel/pay by setting limitApp to the pay resource.

Degrade (circuit‑breaker) rules are configured via DegradeRule and support three strategies – average response time, exception ratio, and exception count. Example JSON:

[
  {
    "resource": "/test1",
    "limitApp": "default",
    "grade": 0,
    "count": 200,
    "slowRatioThreshold": 0.2,
    "minRequestAmount": 5,
    "statIntervalMs": 1000,
    "timeWindow": 10
  }
]

Hotspot parameter limiting targets frequently accessed parameters (e.g., product IDs). Example JSON for limiting the first parameter of OrderQuery to 1 QPS, with an exception for p1=100:

[
  {
    "resource": "OrderQuery",
    "grade": 1,
    "paramIdx": 0,
    "count": 1,
    "durationInSec": 1,
    "burstCount": 0,
    "controlBehavior": 0,
    "limitApp": "default",
    "paramFlowItemList": [
      {"classType": "int", "count": 100, "object": "100"}
    ]
  }
]

System adaptive flow control protects the whole machine based on load, CPU usage, average RT, thread count, or entry QPS. Example rule types are shown in the console screenshots.

Custom block handlers using @SentinelResource:

@SentinelResource(value = "sentinel-test", blockHandler = "handleBlock")
public String test() { return "ok"; }
public String handleBlock(BlockException ex) { return "blocked"; }

Handlers can be placed in a separate class via blockHandlerClass and must be static.

Fallback handling for exceptions uses fallback or defaultFallback attributes of @SentinelResource. Example:

@SentinelResource(value = "createOrder", fallback = "fallbackCreate", blockHandler = "blockCreate")
public String createOrder() { int i = 1/0; return "order"; }
public String fallbackCreate(Throwable t) { return "fallback"; }
public String blockCreate(BlockException e) { return "blocked"; }

If both blockHandler and fallback are defined, blockHandler takes precedence for flow‑control blocks.

Blacklist/whitelist (authority) rules control access based on request origin (e.g., IP). Example JSON:

[
  {
    "resource": "sentinel_spring_web_context",
    "limitApp": "127.0.0.1",
    "strategy": 1
  }
]

Implement RequestOriginParser to extract the origin, such as the client IP.

Rule persistence with Nacos (Push mode) : Add the sentinel-datasource-nacos dependency and configure datasource in application.yml:

spring:
  cloud:
    sentinel:
      datasource:
        ds-flow:
          nacos:
            server-addr: 127.0.0.1:8848
            dataId: ${spring.application.name}-flow
            groupId: DEFAULT_GROUP
            data-type: json
            rule-type: flow
        ds-degrade:
          nacos:
            server-addr: 127.0.0.1:8848
            dataId: ${spring.application.name}-degrade
            groupId: DEFAULT_GROUP
            data-type: json
            rule-type: degrade

Push the JSON rule definitions (as shown earlier) to Nacos; the Sentinel dashboard will automatically pull them, and any changes in the dashboard will be pushed back to Nacos after customizing the dashboard source code.

Cluster flow control (embedded mode): Deploy multiple instances (e.g., ports 9009, 9011, 9013), designate one as the token server in the Sentinel console, and configure cluster rules via the console or Nacos. The cluster rule JSON looks like:

[
  {
    "resource": "/test",
    "clusterMode": true,
    "threshold": 100,
    "strategy": 0,
    "controlBehavior": 0,
    "clusterConfig": {"flowId": 1, "sampleCount": 10, "windowIntervalMs": 1000}
  }
]

After publishing, the dashboard shows the rule applied across all instances.

Gateway flow control is covered in Sentinel’s gateway module documentation and follows similar rule definitions.

OpenFeign integration for circuit breaking is described in the previous article "openFeign nine‑question series"; Sentinel can be used as the fallback provider for Feign clients.

Finally, the author encourages readers to like, share, and bookmark the article, and provides a QR code for obtaining the source code via the public account "码猿技术专栏".