2019-07-30 09:53:45 +08:00
# Sentinel: The Sentinel of Your Microservices
2018-07-23 15:51:05 +08:00
2024-02-21 17:05:29 +08:00
< img src = "https://user-images.githubusercontent.com/9434884/43697219-3cb4ef3a-9975-11e8-9a9c-73f4f537442d.png" alt = "Sentinel Logo" width = "50%" >
2021-06-02 19:15:26 +08:00
[](https://github.com/alibaba/Sentinel/actions/workflows/ci.yml)
2018-10-30 19:07:18 +08:00
[](https://codecov.io/gh/alibaba/Sentinel)
2018-08-12 13:29:10 +08:00
[](https://search.maven.org/search?q=g:com.alibaba.csp%20AND%20a:sentinel-core)
2018-07-23 15:51:05 +08:00
[](https://www.apache.org/licenses/LICENSE-2.0.html)
[](https://gitter.im/alibaba/Sentinel)
2023-02-03 16:49:20 +08:00
[](https://opensource.alibaba.com/contribution_leaderboard/details?projectValue=sentinel)
2018-07-23 15:51:05 +08:00
2018-12-29 15:23:27 +08:00
## Introduction
2018-07-23 15:51:05 +08:00
2018-12-17 14:51:09 +08:00
As distributed systems become increasingly popular, the reliability between services is becoming more important than ever before.
2022-11-03 16:33:05 +08:00
Sentinel takes "flow" as breakthrough point, and works on multiple fields including **flow control** , **traffic shaping** ,
**concurrency limiting**, **circuit breaking** and **system adaptive overload protection** ,
to guarantee reliability and resilience for microservices.
2018-07-23 15:51:05 +08:00
Sentinel has the following features:
2018-12-29 15:23:27 +08:00
- **Rich applicable scenarios**: Sentinel has been wildly used in Alibaba, and has covered almost all the core-scenarios in Double-11 (11.11) Shopping Festivals in the past 10 years, such as “Second Kill” which needs to limit burst flow traffic to meet the system capacity, message peak clipping and valley fills, circuit breaking for unreliable downstream services, cluster flow control, etc.
- **Real-time monitoring**: Sentinel also provides real-time monitoring ability. You can see the runtime information of a single machine in real-time, and the aggregated runtime info of a cluster with less than 500 nodes.
2022-11-03 16:33:05 +08:00
- **Widespread open-source ecosystem**: Sentinel provides out-of-box integrations with commonly-used frameworks and libraries such as Spring Cloud, gRPC, Apache Dubbo and Quarkus. You can easily use Sentinel by simply add the adapter dependency to your services.
- **Polyglot support**: Sentinel has provided native support for Java, [Go ](https://github.com/alibaba/sentinel-golang ), [C++ ](https://github.com/alibaba/sentinel-cpp ) and [Rust ](https://github.com/sentinel-group/sentinel-rust ).
2018-12-29 15:23:27 +08:00
- **Various SPI extensions**: Sentinel provides easy-to-use SPI extension interfaces that allow you to quickly customize your logic, for example, custom rule management, adapting data sources, and so on.
2018-07-23 15:51:05 +08:00
2019-03-20 10:31:09 +08:00
Features overview:
2022-11-03 16:33:05 +08:00
The community is also working on **the specification of traffic governance and fault-tolerance** .
2022-08-08 21:29:40 +08:00
Please refer to [OpenSergo ](https://opensergo.io/ ) for details.
2018-07-23 15:51:05 +08:00
## Documentation
2022-08-08 21:29:40 +08:00
See the [Sentinel Website ](https://sentinelguard.io/ ) for the official website of Sentinel.
2021-02-27 13:37:10 +08:00
2022-11-03 16:33:05 +08:00
See the [中文文档 ](https://sentinelguard.io/zh-cn/docs/introduction.html ) for document in Chinese.
2018-07-23 15:51:05 +08:00
2018-10-30 19:07:18 +08:00
See the [Wiki ](https://github.com/alibaba/Sentinel/wiki ) for full documentation, examples, blog posts, operational details and other information.
2018-07-23 15:51:05 +08:00
2019-12-24 20:05:23 +08:00
Sentinel provides integration modules for various open-source frameworks
2022-08-08 21:29:40 +08:00
(e.g. Spring Cloud, Apache Dubbo, gRPC, Quarkus, Spring WebFlux, Reactor) and service mesh.
You can refer to [the document ](https://sentinelguard.io/en-us/docs/open-source-framework-integrations.html ) for more information.
2019-03-27 17:48:03 +08:00
2018-12-28 14:23:34 +08:00
If you are using Sentinel, please [**leave a comment here** ](https://github.com/alibaba/Sentinel/issues/18 ) to tell us your scenario to make Sentinel better.
It's also encouraged to add the link of your blog post, tutorial, demo or customized components to [**Awesome Sentinel** ](./doc/awesome-sentinel.md ).
2018-08-01 10:18:50 +08:00
2019-03-20 10:31:09 +08:00
## Ecosystem Landscape
2018-07-23 15:51:05 +08:00
## Quick Start
Below is a simple demo that guides new users to use Sentinel in just 3 steps. It also shows how to monitor this demo using the dashboard.
2018-10-30 19:07:18 +08:00
### 1. Add Dependency
2018-07-23 15:51:05 +08:00
2021-02-01 09:53:32 +08:00
**Note:** Sentinel requires JDK 1.8 or later.
2018-07-23 15:51:05 +08:00
2021-02-01 09:53:32 +08:00
If you're using Maven, just add the following dependency in `pom.xml` .
2018-07-23 15:51:05 +08:00
```xml
2019-03-20 10:31:09 +08:00
<!-- replace here with the latest version -->
2018-07-23 15:51:05 +08:00
< dependency >
< groupId > com.alibaba.csp< / groupId >
< artifactId > sentinel-core< / artifactId >
2025-10-16 20:26:58 +08:00
< version > 1.8.9< / version >
2018-07-23 15:51:05 +08:00
< / dependency >
```
If not, you can download JAR in [Maven Center Repository ](https://mvnrepository.com/artifact/com.alibaba.csp/sentinel-core ).
2018-10-30 19:07:18 +08:00
### 2. Define Resource
2018-07-23 15:51:05 +08:00
2019-03-20 10:31:09 +08:00
Wrap your code snippet via Sentinel API: `SphU.entry(resourceName)` .
In below example, it is `System.out.println("hello world");` :
2018-07-23 15:51:05 +08:00
```java
2019-03-20 10:31:09 +08:00
try (Entry entry = SphU.entry("HelloWorld")) {
// Your business logic here.
System.out.println("hello world");
2018-07-23 15:51:05 +08:00
} catch (BlockException e) {
2019-03-20 10:31:09 +08:00
// Handle rejected request.
e.printStackTrace();
2018-07-23 15:51:05 +08:00
}
2019-11-12 10:20:46 +08:00
// try-with-resources auto exit
2018-07-23 15:51:05 +08:00
```
2020-04-07 14:37:33 +08:00
So far the code modification is done. We've also provided [annotation support module ](https://github.com/alibaba/Sentinel/blob/master/sentinel-extension/sentinel-annotation-aspectj/README.md ) to define resource easier.
2018-07-23 15:51:05 +08:00
2018-10-30 19:07:18 +08:00
### 3. Define Rules
2018-07-23 15:51:05 +08:00
2018-12-29 15:23:27 +08:00
If we want to limit the access times of the resource, we can **set rules to the resource** .
The following code defines a rule that limits access to the resource to 20 times per second at the maximum.
2018-07-23 15:51:05 +08:00
```java
2018-12-17 14:51:09 +08:00
List< FlowRule > rules = new ArrayList< >();
2018-07-23 15:51:05 +08:00
FlowRule rule = new FlowRule();
2018-07-27 16:53:57 +08:00
rule.setResource("HelloWorld");
2018-07-23 15:51:05 +08:00
// set limit qps to 20
rule.setCount(20);
2018-07-27 16:53:57 +08:00
rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
2018-07-23 15:51:05 +08:00
rules.add(rule);
FlowRuleManager.loadRules(rules);
```
2022-08-08 21:29:40 +08:00
For more information, please refer to [How To Use ](https://sentinelguard.io/en-us/docs/basic-api-resource-rule.html ).
2018-12-03 15:13:14 +08:00
2018-07-23 15:51:05 +08:00
### 4. Check the Result
2019-06-17 10:16:48 +08:00
After running the demo for a while, you can see the following records in `~/logs/csp/${appName}-metrics.log.{date}` (When using the default `DateFileLogHandler` ).
2018-07-23 15:51:05 +08:00
2024-02-21 17:05:29 +08:00
```plaintext
2019-06-17 10:16:48 +08:00
|--timestamp-|------date time----|-resource-|p |block|s |e|rt |occupied
1529998904000|2018-06-26 15:41:44|HelloWorld|20|0 |20|0|0 |0
1529998905000|2018-06-26 15:41:45|HelloWorld|20|5579 |20|0|728 |0
1529998906000|2018-06-26 15:41:46|HelloWorld|20|15698|20|0|0 |0
1529998907000|2018-06-26 15:41:47|HelloWorld|20|19262|20|0|0 |0
1529998908000|2018-06-26 15:41:48|HelloWorld|20|19502|20|0|0 |0
1529998909000|2018-06-26 15:41:49|HelloWorld|20|18386|20|0|0 |0
2020-12-21 19:46:17 +08:00
p stands for incoming request, block for blocked by rules, s for success handled by Sentinel, e for exception count, rt for average response time (ms), occupied stands for occupiedPassQps since 1.5.0 which enable us booking more than 1 shot when entering.
2018-07-23 15:51:05 +08:00
```
2018-12-29 15:23:27 +08:00
2018-07-23 15:51:05 +08:00
This shows that the demo can print "hello world" 20 times per second.
2022-08-08 21:29:40 +08:00
More examples and information can be found in the [How To Use ](https://sentinelguard.io/en-us/docs/basic-api-resource-rule.html ) section.
2018-07-23 15:51:05 +08:00
2022-08-08 21:29:40 +08:00
The working principles of Sentinel can be found in [How it works ](https://sentinelguard.io/en-us/docs/basic-implementation.html ) section.
2018-07-23 15:51:05 +08:00
Samples can be found in the [sentinel-demo ](https://github.com/alibaba/Sentinel/tree/master/sentinel-demo ) module.
2018-10-30 19:07:18 +08:00
### 5. Start Dashboard
2018-07-23 15:51:05 +08:00
2020-04-07 14:37:33 +08:00
> Note: Java 8 is required for building or running the dashboard.
2018-07-23 15:51:05 +08:00
Sentinel also provides a simple dashboard application, on which you can monitor the clients and configure the rules in real time.
2019-07-30 09:53:45 +08:00
2018-07-23 15:51:05 +08:00
For details please refer to [Dashboard ](https://github.com/alibaba/Sentinel/wiki/Dashboard ).
## Trouble Shooting and Logs
2019-07-30 09:53:45 +08:00
Sentinel will generate logs for troubleshooting and real-time monitoring.
2022-08-08 21:29:40 +08:00
All the information can be found in [logs ](https://sentinelguard.io/en-us/docs/logs.html ).
2018-07-23 15:51:05 +08:00
## Bugs and Feedback
For bug report, questions and discussions please submit [GitHub Issues ](https://github.com/alibaba/sentinel/issues ).
2020-04-07 14:37:33 +08:00
Contact us via [Gitter ](https://gitter.im/alibaba/Sentinel ) or [Email ](mailto:sentinel@linux.alibaba.com ).
2018-07-23 15:51:05 +08:00
## Contributing
2020-04-07 14:37:33 +08:00
Contributions are always welcomed! Please refer to [CONTRIBUTING ](./CONTRIBUTING.md ) for detailed guidelines.
2018-11-14 09:44:53 +08:00
2018-12-29 15:23:27 +08:00
You can start with the issues labeled with [`good first issue` ](https://github.com/alibaba/Sentinel/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 ).
2018-12-28 14:23:34 +08:00
2023-02-10 21:01:37 +08:00
## Enterprise Service
If you need Sentinel enterprise service support (Sentinel 企业版), or purchase cloud product services,
you can join the discussion by the DingTalk group (34754806). It can also be directly activated
and used through the [microservice engine (MSE 微服务引擎) provided by Alibaba Cloud ](https://cn.aliyun.com/product/aliware/mse?spm=sentinel-github.index.0.0.0 ).
2018-12-17 14:51:09 +08:00
## Credits
Thanks [Guava ](https://github.com/google/guava ), which provides some inspiration on rate limiting.
And thanks for all [contributors ](https://github.com/alibaba/Sentinel/graphs/contributors ) of Sentinel!
2018-11-14 09:44:53 +08:00
## Who is using
2020-04-07 14:37:33 +08:00
These are only part of the companies using Sentinel, for reference only.
If you are using Sentinel, please [add your company here ](https://github.com/alibaba/Sentinel/issues/18 ) to tell us your scenario to make Sentinel better :)
2018-11-14 09:44:53 +08:00
2020-08-20 19:50:54 +08:00
2018-11-14 09:44:53 +08:00
2020-08-20 19:50:54 +08:00
2018-11-14 14:14:51 +08:00
2018-12-03 15:13:14 +08:00
2020-08-20 19:50:54 +08:00
2018-12-03 15:13:14 +08:00
