alibaba/Sentinel: Flow Control and Circuit Breaking for JVM Microservices

What Sentinel solves and who it is for

A microservice that calls a downstream dependency has no natural ceiling on how many requests it sends. When the downstream slows down, threads pile up, latency climbs, and the caller fails too. Sentinel puts a decision point in front of that call: a resource name, a rule, and a block result. The README frames the project around "flow" as the breakthrough point and lists flow control, traffic shaping, concurrency limiting, circuit breaking and system adaptive overload protection as the fields it works on.

The intended user is a JVM service owner. The README states Sentinel requires JDK 1.8 or later, and the quick start is a Maven dependency plus a Java code change. The project also lists native support for Go, C++ and Rust, so the model travels, but the core, the adapters and the dashboard in this repository are Java. If your service is not on the JVM and not on one of those ports, this repository is not the thing you install.

Resources, entries and the block path

The mechanism is an entry around a code block. You wrap a snippet in SphU.entry(resourceName), and Sentinel records the call against that resource. If a rule rejects it, Sentinel throws BlockException instead of running the body. The README's example uses try-with-resources, and the comment notes that the entry is exited automatically. That detail matters: an entry that is never exited corrupts the concurrency and QPS accounting for that resource, so the try-with-resources form is the safe default rather than a style preference.

Rules are objects loaded into a manager. A FlowRule carries a resource name, a count and a grade; the README sets the grade to RuleConstant.FLOW_GRADE_QPS with a count of 20, and loads the list through FlowRuleManager.loadRules(rules). Nothing in that path requires a network call. Rules live in the process unless you attach a data source, which is why the same API works in a unit test and in production.

Observability is file-based by default. The README points to ~/logs/csp/${appName}-metrics.log.{date} when the default DateFileLogHandler is used, and shows a pipe-delimited record with columns for timestamp, date time, resource, p, block, s, e, rt and occupied. The legend in the README defines p as incoming requests, block as requests blocked by rules, s as successes handled by Sentinel, e as exception count, and rt as average response time in milliseconds. That file is the ground truth when a rule behaves unexpectedly.

Installing Sentinel and limiting a method to 20 QPS

Add the core dependency to pom.xml. The README uses version 1.8.10 and notes that the comment should be replaced with the latest version. The same README says Sentinel requires JDK 1.8 or later, so check the compiler target before you add it.

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-core</artifactId>
    <version>1.8.10</version>
</dependency>

Wrap the call you want to protect. The README's example uses the resource name HelloWorld and prints inside the entry. If the rule rejects the call, the catch block receives BlockException.

try (Entry entry = SphU.entry("HelloWorld")) {
    System.out.println("hello world");
} catch (BlockException e) {
    e.printStackTrace();
}

Define the rule. This loads one QPS rule for HelloWorld with a count of 20, meaning at most 20 accesses per second according to the README.

List<FlowRule> rules = new ArrayList<>();
FlowRule rule = new FlowRule();
rule.setResource("HelloWorld");
rule.setCount(20);
rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
rules.add(rule);
FlowRuleManager.loadRules(rules);

Run the demo for a while and read the metrics log. In the README's sample output the p column stays at 20 while block climbs into the thousands on later seconds, which is what a working 20 QPS limit looks like under load. If block stays at zero while p exceeds 20, your rule did not load. If p itself never exceeds 20, your load generator, not Sentinel, is the limit.

The dashboard, transport and cluster pieces are separate installs

The quick start says it also shows how to monitor the demo using the dashboard, but the dashboard is a separate module in this repository, sentinel-dashboard, and the client side needs a transport module. The top-level layout separates sentinel-core, sentinel-transport, sentinel-cluster, sentinel-adapter, sentinel-extension, sentinel-logging, sentinel-dashboard, sentinel-demo and sentinel-benchmark. That split is honest about scope, and it is also the first place a new user gets stuck: adding sentinel-core alone gives you rules and local metrics files, not a UI.

The README claims real-time monitoring of a single machine and aggregated runtime information for a cluster with fewer than 500 nodes. Treat that number as a documented boundary rather than a performance guarantee. It is the point at which the project itself stops describing the aggregation as the supported case, and the cluster module is where the aggregated path lives. If your fleet is larger, that is a design question you have to answer before rollout, not after.

Where Sentinel is the wrong tool

Sentinel is in-process. The rule is evaluated inside your JVM, against counters your JVM owns. That is a strength for latency and a limitation for governance: two replicas of the same service each enforce the limit independently unless you move to the cluster module, and a limit expressed per instance is not the same as a limit expressed for the service. Teams that expect a single global budget from the simple FlowRule example will be surprised.

The second limitation is rule persistence. The README's quick start loads rules from Java code. Rules loaded that way are gone on restart unless your application loads them again, and the README's example does not show a data source or a persistence layer. Sentinel provides SPI extension interfaces for custom rule management and adapting data sources, and the README names those as extension points, so the wiring is deliberate work rather than a default.

The third is language. The README lists native support for Java, Go, C++ and Rust, and the integration list covers Spring Cloud, Apache Dubbo, gRPC, Quarkus, Spring WebFlux and Reactor. A polyglot estate can use Sentinel, but it will run several implementations and several dashboards unless something else unifies them. The README points to OpenSergo for the community's work on a traffic governance and fault-tolerance specification, which is a signal that cross-language governance is not what this repository ships.

Sentinel compared with a service mesh sidecar

The closest alternative in approach is a service mesh: move the traffic decision out of the application and into a sidecar proxy, so the application code has no SphU.entry call at all. The difference is where the counter lives and who owns the policy. With a sidecar, the proxy sees the request and the platform owns the rules; the application does not need a Java dependency and a non-JVM service is covered by the same mechanism. With Sentinel, the application owns the entry, the rule objects and the block handling, which means the policy can be written in the same language as the business logic and can key on things a proxy cannot see, such as a specific method or a business identifier.

That trade goes the other way too. A sidecar can rate-limit traffic that never reaches your process, including malformed requests; Sentinel only sees calls that enter a resource. If your problem is protecting a service from traffic before it is parsed, Sentinel is downstream of where you want the decision. If your problem is protecting a specific downstream call from a specific caller inside the process, the sidecar has no visibility and Sentinel does. The two are not substitutes so much as different placement, and the README's own framing around resources and entries makes the placement explicit.

Maintenance, versioning and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-05-27. The most recent release is 1.8.10 from 2026-05-21, preceded by 1.8.9 on 2025-10-17 and 1.8.8 on 2024-06-05. The gap between 1.8.8 and 1.8.9 is over a year, and the gap between 1.8.9 and 1.8.10 is about seven months. That cadence is steady rather than fast, and it means the version you pin is likely to stay pinned for a while. The default branch is 1.8, so the development line and the release line share a number.

Upgrade cost is concentrated in the adapter layer. The core API in the README (SphU.entry, FlowRule, FlowRuleManager.loadRules) is stable across the 1.8.x releases shown, but the integration modules for Spring Cloud, Dubbo, gRPC and Quarkus track those frameworks' own versions, so a framework upgrade can force a Sentinel adapter upgrade even when sentinel-core has not changed. Plan the two together.

Sentinel is licensed under Apache-2.0, which permits commercial use and modification and requires that the licence and notices be preserved. That is a permissive licence, but it is not legal advice, and if you redistribute a modified Sentinel inside a product, the notice obligations are yours to check with counsel.

Editorial conclusion

Sentinel fits JVM teams that want QPS limits, circuit breaking and system adaptive overload protection defined in process and visible in a dashboard, and it fits them best when the rules are already expressed in Java or loaded from a data source. Teams running non-JVM services, or teams that want traffic policy owned by a sidecar or a control plane, should look at a mesh or at the OpenSergo specification instead, because Sentinel's native support is Java, Go, C++ and Rust but its rule model and dashboard are JVM-centric. Before adopting it, verify that the version you pin, currently 1.8.10, matches the JDK you build with, that the transport module you choose matches the dashboard you run, and that your rule source survives a restart, because the README's rule example loads rules from Java code only.

Frequently asked questions

Official sources

1. alibaba/Sentinel on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases