Mastering Alibaba Sentinel: From Setup to Advanced Flow Control, Degradation, and Persistence

1. Introduction

This article introduces Alibaba's open‑source traffic guard Sentinel, a highly mature product proven by nearly ten years of Double‑11 traffic spikes.

Table of contents:

2. What is Sentinel?

Sentinel, literally "sentinel", is called "Sentinel" in Redis for master‑slave monitoring, but in microservices it is a "traffic guard".

Sentinel protects service stability from multiple dimensions such as flow control , circuit breaking , and system load .

Key features:

Rich application scenarios : Sentinel handles Alibaba's core Double‑11 traffic, including flash sales (burst traffic control), message smoothing, cluster flow control, real‑time circuit breaking of downstream unavailable services, etc.

Comprehensive real‑time monitoring : The console shows per‑machine second‑level data and aggregated statistics for clusters up to 500 nodes.

Broad open‑source ecosystem : Ready‑to‑use integrations with Spring Cloud, Apache Dubbo, gRPC, Quarkus, and native implementations for Java, Go, C++.

Extensible SPI mechanism : Implement custom extensions for rule management, dynamic data source adaptation, and more.

Sentinel's main components are shown below:

Sentinel consists of two parts:

Core library (Java client) that has no external dependencies and runs on any Java runtime, with good support for Dubbo and Spring Cloud.

Dashboard (Spring Boot) that can be packaged and run directly without an external servlet container.

In short: Sentinel is awesome and outperforms Hystrix.

3. Sentinel vs. Hystrix

Bottom line: Stop using Hystrix and switch to Sentinel.

See the comparison chart:

4. Choosing Sentinel Version

Because this series uses the Spring Cloud Advanced aggregation project, keep the version consistent with previous articles. See the referenced article for details.

We use the spring-cloud-alibaba-dependencies version 2.2.1.RELEASE, so Sentinel version is 1.7.1. The version mapping is illustrated below:

Note: Follow the official recommended version mapping, otherwise you may encounter unexpected bugs.

5. Installing the Sentinel Dashboard

Sentinel, like Nacos, provides a dashboard. You can download the appropriate JAR from the official GitHub tags page.

Select version 1.7.1 and download the JAR:

Alternatively, you can build from source: mvn clean package

JDK version must be >=1.8.

Run the dashboard with the following command:

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

Parameter meanings: -Dserver.port: startup port, default

8080

-Dproject.name

: service name -Dcsp.sentinel.dashboard.server: address of the dashboard for self‑registration

After startup, open http://localhost:8080. Default credentials are sentinel/sentinel.

Login screen:

Only one service sentinel-dashboard is monitored, which is the current application.

Note: All parameters are optional; you can omit them if unnecessary.

6. How to Connect a Microservice to the Sentinel Dashboard?

Why integrate the dashboard when Sentinel already provides APIs? Following Spring Boot's "convention > configuration > code" principle, this article focuses on dashboard integration; API usage is covered in the official docs.

1) Register a microservice module with Nacos

Refer to the first Nacos article for details.

Create a module named sentinel-service9008 . Code is omitted for brevity.

Configuration:

server:
  port: 9008
spring:
  application:
    name: sentinel-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
management:
  endpoints:
    web:
      exposure:
        include: '*'

All source code will be uploaded; see the end of the article.

2) Add Sentinel dependency

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

Only the Sentinel dependency is shown; Nacos dependency is omitted.

3) Add configuration to integrate the dashboard

spring:
  cloud:
    sentinel:
      transport:
        ## Specify dashboard address, default port 8080
        dashboard: localhost:8080

4) Create a test endpoint

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

5) Start the microservice

Run on port 9008 and access http://localhost:9008/sentinel/test. The dashboard will show the sentinel-service being monitored.

Note: Sentinel uses lazy loading; only resources accessed at least once are monitored.

You can disable lazy loading so the service connects to the dashboard at startup:

spring:
  sentinel:
    eager: true

7. Flow Control Configuration

Flow control monitors QPS or concurrent thread count for a resource. When the threshold is reached, traffic is limited to ensure high availability.

QPS: Requests per second that the server can handle.

Concurrent threads: Number of simultaneous requests.

A flow rule consists of:

resource : the target name.

count : threshold value.

grade : type (1 for QPS, 0 for threads), default QPS.

limitApp : source identifier; default means all sources.

strategy : 0 (self), 1 (related), 2 (chain), default self.

controlBehavior : 0 (reject), 1 (warm‑up), 2 (queue), default reject.

The corresponding class is com.alibaba.csp.sentinel.slots.block.flow.FlowRule. See the diagram:

Note: Remember the values and defaults; they will be used later.

Flow control UI in the dashboard:

1) Three Flow Control Effects

Corresponding to controlBehavior:

Fast Fail

When QPS exceeds the threshold, new requests are immediately rejected with a FlowException.

Warm Up

For low‑load periods, the system gradually ramps up traffic to the threshold over a configured warm‑up period, preventing sudden overload. Implemented via token‑bucket algorithm in WarmUpController.

Note: Warm‑up only works for QPS, not thread‑based flow control.

Cold factor (default 3) determines the initial rate: threshold/3.

Example: QPS threshold 3, warm‑up 5 seconds. Initial rate is 1 QPS, reaching 3 QPS after 5 seconds.

Animation shows the ramp‑up behavior.

Queue Waiting

Uniform queuing uses a leaky‑bucket algorithm to control request spacing. Implemented in RateLimiterController.

Note: This effect only applies to QPS flow control.

Analogy: a single server at a cafeteria serves one person at a time; others wait in line. Sentinel adds a timeout—if waiting exceeds the timeout, the request is rejected.

This mode is suitable for bursty traffic where you want to smooth the flow instead of rejecting everything.

Example: QPS threshold 1, timeout 10 seconds.

Result shows requests are queued rather than rejected.

Only requests that exceed the timeout are limited.

2) Three Flow Control Modes

Direct reject: limit when the resource itself reaches the threshold.

Related: limit when a related resource reaches its threshold.

Chain: limit based on the entry resource of a specific call chain.

Examples:

Direct Reject

Default mode; when QPS exceeds the threshold, a FlowException is thrown.

Related

Typical scenario: payment interface reaches its limit, then the order interface should be limited to avoid poor user experience.

In short: A is related to B; if B is limited, A is limited.

Demo code (order and pay endpoints) and rule configuration are shown in the article.

Result: order interface is limited after pay reaches its threshold.

3) Two Statistic Types

Flow control can be based on QPS or concurrent thread count. Example analogy with a bank: security guard limits entry (QPS) while tellers limit concurrent processing (threads).

8. Degradation Rules Configuration

Degradation (circuit breaking) scenarios include stock market halts, fuse protection, etc. In distributed systems, a downstream service may become unavailable, cause retries, or exhaust threads, leading to overall service failure.

Degradation rules are configured in the dashboard as shown:

Key attributes are displayed in a table (image omitted for brevity). The corresponding class is com.alibaba.csp.sentinel.slots.block.degrade.DegradeRule.

Three Degradation Strategies

Average response time (DEGRADE_GRADE_RT) : If the average RT over 1 second for 5 requests exceeds the threshold, the method is circuit‑broken for the configured time window.

Exception ratio (DEGRADE_GRADE_EXCEPTION_RATIO) : When request count ≥ 5 /s and exception ratio exceeds the threshold, the method is degraded for the time window.

Exception count (DEGRADE_GRADE_EXCEPTION_COUNT) : If the number of exceptions in the last minute exceeds the threshold, the method is degraded.

Demo: a test endpoint sleeps 3 seconds, average RT > 200 ms, causing degradation.

@RestController
@RequestMapping("/sentinel/provider")
@Slf4j
public class FlowLimitController {
    @GetMapping("/test")
    public String test() throws InterruptedException {
        Thread.sleep(3000);
        log.info("Received a message----test");
        return "Received a message--------";
    }
}

Dashboard configuration sets RT threshold 200 ms, window 1 s. Load test with JMeter shows the endpoint is degraded.

9. Hotspot Parameter Flow Control

Hotspot parameters (e.g., product IDs in flash‑sale) need per‑parameter limiting. Sentinel uses LRU to track recent hot keys and token‑bucket algorithm for limiting.

Configuration UI shown below:

The rule class is

com.alibaba.csp.sentinel.slots.block.flow.param.ParamFlowRule

. Example: limit the first parameter (p1) to 1 QPS.

Test: accessing .../order/query?p1=22&p2=1222 repeatedly triggers degradation, while changing to p2 does not.

Exception items can whitelist specific parameter values (e.g., p1=100 gets a higher threshold).

10. System Adaptive Flow Control

System‑level adaptive flow control monitors load, CPU usage, average RT, inbound QPS, and concurrent threads to keep the whole system stable.

Dashboard UI shows five threshold types: Load, CPU usage, average RT, concurrent threads, and inbound QPS.

Example: setting an inbound QPS rule limits all interfaces when the threshold is exceeded.

Warning: configuring inbound QPS may render the service unusable.

11. Customizing Flow‑Limit Exception Messages

Default message is "Blocked by Sentinel (flow limiting)". To provide business‑specific messages, use @SentinelResource with blockHandler (or blockHandlerClass) to define fallback logic.

Example resource OrderQuery with block handler handlerQuery returns a custom message when limited.

@SentinelResource(value = "OrderQuery", blockHandler = "handlerQuery")
public String query(String p1, String p2) {
    log.info("Query product, p1:{}, p2:{}", p1, p2);
    return "Query product: success";
}
public String handlerQuery(String p1, String p2, BlockException ex) {
    log.info("Query product blocked, p1:{}, p2:{}", p1, p2);
    return "Query product: blocked";
}

Block handlers must be in the same class (or static methods in a separate class via blockHandlerClass).

12. Exception Degradation (Fallback)

Use @SentinelResource with fallback (or fallbackClass) to handle business exceptions. fallback processes all exceptions except those listed in exceptionsToIgnore. defaultFallback provides a global fallback.

Example: a method throws 1/0 exception; with a fallback method it returns a friendly message.

@SentinelResource(value = "createOrder", fallback = "fallbackCreateOrder")
public String createOrder() {
    int i = 1 / 0; // exception
    return "order created";
}
public String fallbackCreateOrder(Throwable ex) {
    return "order creation failed, fallback executed";
}

If both blockHandler and fallback are configured, blockHandler handles flow‑limit exceptions, while fallback handles business exceptions.

Conclusion: BlockException triggers blockHandler; otherwise fallback or defaultFallback is used.

13. Black‑White List Configuration

Sentinel can whitelist or blacklist request origins. The rule class is com.alibaba.csp.sentinel.slots.block.authority.AuthorityRule with fields resource, limitApp, and strategy (white or black).

Implement RequestOriginParser to extract origin (e.g., IP address).

public class IpRequestOriginParser implements RequestOriginParser {
    @Override
    public String parseOrigin(HttpServletRequest request) {
        return request.getRemoteAddr();
    }
}

Configure a blacklist entry for 127.0.0.1 and test; the request is blocked.

14. Persisting Flow Rules

By default Sentinel stores rules in memory; they disappear after restart. Persistence can be achieved via Nacos using the Push mode.

Dependency:

<dependency>
  <groupId>com.alibaba.csp</groupId>
  <artifactId>sentinel-datasource-nacos</artifactId>
</dependency>

Configuration in application.yml defines Nacos datasource for flow and degrade rules (JSON format, groupId, dataId, etc.).

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

After publishing JSON configurations to Nacos, the dashboard automatically loads them.

Flow rule JSON example:

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

Degrade rule JSON example:

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

15. Pushing Dashboard Changes Back to Nacos

Sentinel’s default Push mode only pushes Nacos → dashboard. To achieve bidirectional sync, modify the Sentinel dashboard source code: replace the test‑scope Nacos dependency, copy the Nacos rule package from src/test/java/com/alibaba/csp/sentinel/dashboard/rule/nacos to src/main/java/com/alibaba/csp/sentinel/dashboard/rule/nacos, and adjust FlowControllerV1 to use the Nacos provider/publisher beans (qualified as flowRuleNacosProvider and flowRuleNacosPublisher).

Update NacosConfigUtil and NacosConfig to match your Nacos address and group/data IDs.

Rebuild the dashboard:

mvn clean install -DskipTests=true -pl sentinel-dashboard -am

After restart, any rule change in the dashboard will be pushed to Nacos.

16. Cluster Flow Control

Cluster flow control centralizes token distribution to a Token Server, allowing precise control over the total request volume of a service cluster.

Two roles:

Token Client: requests tokens from the server.

Token Server: decides whether to grant tokens based on cluster rules.

Deployment modes:

Alone (stand‑alone server).

Embedded (server runs inside each instance; one instance acts as server).

Example: three instances (ports 9009, 9011, 9013) with one designated as token server via the dashboard UI.

After configuring the token server, add a cluster flow rule (via Nacos or dashboard). The rule appears in the dashboard and takes effect across all instances.

17. Gateway Flow Control

Gateway integration is covered in the gateway chapter of the official Sentinel documentation.

Official docs: https://github.com/alibaba/Sentinel/wiki/%E7%BD%91%E5%85%B3%E9%99%90%E6%B5%81

18. Integrating OpenFeign for Degradation

OpenFeign degradation is explained in the previous article "OpenFeign 9‑question series". Refer to that article for details.

Source code is available on GitHub; reply with keyword 9528 to the public account to receive the link.

---

If this article helped you, please like, follow, share, and bookmark. Your support motivates me to keep writing.

Join our high‑quality technical community for deeper discussions and occasional job referrals. Scan the QR code below and reply "Add group" to join.