## File: README.md # Sentinel: The Sentinel of Your Microservices [](https://github.com/alibaba/Sentinel/actions/workflows/ci.yml) [](https://codecov.io/gh/alibaba/Sentinel) [](https://search.maven.org/search?q=g:com.alibaba.csp%20AND%20a:sentinel-core) [](https://www.apache.org/licenses/LICENSE-2.0.html) [](https://gitter.im/alibaba/Sentinel) [](https://opensource.alibaba.com/contribution_leaderboard/details?projectValue=sentinel) ## Introduction As distributed systems become increasingly popular, the reliability between services is becoming more important than ever before. 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. Sentinel has the following features: - **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. - **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). - **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. Features overview: The community is also working on **the specification of traffic governance and fault-tolerance**. Please refer to [OpenSergo](https://opensergo.io/) for details. ## Documentation See the [Sentinel Website](https://sentinelguard.io/) for the official website of Sentinel. See the [中文文档](https://sentinelguard.io/zh-cn/docs/introduction.html) for document in Chinese. See the [Wiki](https://github.com/alibaba/Sentinel/wiki) for full documentation, examples, blog posts, operational details and other information. Sentinel provides integration modules for various open-source frameworks (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. 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). ## Ecosystem Landscape ## 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. ### 1. Add Dependency **Note:** Sentinel requires JDK 1.8 or later. If you're using Maven, just add the following dependency in `pom.xml`. ```xml com.alibaba.csp sentinel-core 1.8.10 ``` If not, you can download JAR in [Maven Center Repository](https://mvnrepository.com/artifact/com.alibaba.csp/sentinel-core). ### 2. Define Resource Wrap your code snippet via Sentinel API: `SphU.entry(resourceName)`. In below example, it is `System.out.println("hello world");`: ```java try (Entry entry = SphU.entry("HelloWorld")) { // Your business logic here. System.out.println("hello world"); } catch (BlockException e) { // Handle rejected request. e.printStackTrace(); } // try-with-resources auto exit ``` 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. ### 3. Define Rules 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. ```java List rules = new ArrayList<>(); FlowRule rule = new FlowRule(); rule.setResource("HelloWorld"); // set limit qps to 20 rule.setCount(20); rule.setGrade(RuleConstant.FLOW_GRADE_QPS); rules.add(rule); FlowRuleManager.loadRules(rules); ``` For more information, please refer to [How To Use](https://sentinelguard.io/en-us/docs/basic-api-resource-rule.html). ### 4. Check the Result 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`). ```plaintext |--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 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. ``` This shows that the demo can print "hello world" 20 times per second. More examples and information can be found in the [How To Use](https://sentinelguard.io/en-us/docs/basic-api-resource-rule.html) section. The working principles of Sentinel can be found in [How it works](https://sentinelguard.io/en-us/docs/basic-implementation.html) section. Samples can be found in the [sentinel-demo](https://github.com/alibaba/Sentinel/tree/master/sentinel-demo) module. ### 5. Start Dashboard > Note: Java 8 is required for building or running the dashboard. Sentinel also provides a simple dashboard application, on which you can monitor the clients and configure the rules in real time. For details please refer to [Dashboard](https://github.com/alibaba/Sentinel/wiki/Dashboard). ## Trouble Shooting and Logs Sentinel will generate logs for troubleshooting and real-time monitoring. All the information can be found in [logs](https://sentinelguard.io/en-us/docs/logs.html). ## Bugs and Feedback For bug report, questions and discussions please submit [GitHub Issues](https://github.com/alibaba/sentinel/issues). Contact us via [Gitter](https://gitter.im/alibaba/Sentinel) or [Email](mailto:sentinel@linux.alibaba.com). ## Contributing Contributions are always welcomed! Please refer to [CONTRIBUTING](./CONTRIBUTING.md) for detailed guidelines. 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). ## 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). ## 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! ## Who is using 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 :) --- ## File: doc/awesome-sentinel.md # Awesome Sentinel [](https://awesome.re) A curated list of awesome things (e.g. samples, third-party extensions, blog posts) for [Sentinel](https://github.com/alibaba/Sentinel). If you want your component to appear here, feel free to submit a pull request to this repository to add it. You can refer to the [awesome contribution guidelines](https://github.com/sentinel-group/sentinel-awesome/blob/master/CONTRIBUTING.md). You can also add to [sentinel-group/sentinel-awesome](https://github.com/sentinel-group/sentinel-awesome). ## Contents - [Presentations](#presentations) - [Tutorials](#tutorialssamples) - [Demos](../demos) - [Extensions / Integrations](#extensions--integrations) - [Blog Posts](#blog-posts) ## Presentations - Sentinel 1.6.0 网关流控新特性介绍-Eric Zhao (Dubbo Tech Day-201905-Beijing): [PDF](https://github.com/sentinel-group/sentinel-awesome/blob/master/slides/Sentinel%201.6.0%20网关流控新特性介绍-Eric%20Zhao-DTED-201905.pdf) - Sentinel 微服务流控降级实践-Eric Zhao (Dubbo Tech Day-201907-Shenzhen): [PDF](https://github.com/sentinel-group/sentinel-awesome/blob/master/slides/Sentinel%20微服务流控降级实践-Eric%20Zhao-DTED-201907.pdf) - Sentinel 1.7.0 新特性展望-Eric Zhao (Dubbo Tech Day-201910-Chengdu): [PDF](https://github.com/sentinel-group/sentinel-awesome/blob/master/slides/Sentinel%201.7.0%20新特性展望-Eric%20Zhao-DTED-201910.pdf) - 《微服务容易挂？Sentinel Go 让微服务稳如磐石》-Eric Zhao (Spring Cloud Alibaba Meetup 1205 杭州站): [PDF](https://github.com/sentinel-group/sentinel-awesome/blob/master/slides/SCA%20Meetup%20Hangzhou-20201205-Sentinel%20Go-Eric%20Zhao.pdf) - Sentinel 2.0 流量治理全面升级-Eric Zhao (2022中间件开发者大会): [PDF](https://github.com/mse-group/Slides/blob/main/中间件开发者大会/10%20-%20赵奕豪(宿何)%20-Sentinel%202.0%20流量治理全面升级.pdf) ## Tutorials/Samples - [Sentinel Guides](https://github.com/sentinel-group/sentinel-guides) ## Polyglot Support - [Sentinel Go](https://github.com/alibaba/sentinel-golang) - [Sentinel C++](https://github.com/alibaba/sentinel-cpp) - [Sentinel Rust](https://github.com/sentinel-group/sentinel-rust) ## Extensions / Integrations - [sentinel-support](https://github.com/cdfive/sentinel-support): A support project for convenient Sentinel integration including properties file configuration, ActiveMQ integration and a JdbcDataSource implementation by [cdfive](https://github.com/cdfive) - [Sentinel dashboard multi-data-source adapter](https://github.com/finefuture/sentinel-dashboard-X): Sentinel dashboard multi-data-source adapter has integrated Apollo and Nacos configuration center for bidirectional modification persistence. Implemented by [finefuture](https://github.com/finefuture) - [Sentinel Rule Annotation Support](https://github.com/code1986/sentinel-lib): A third-party library that supports configuring flow rule and degrade rule using annotation. Implemented by [code1986](https://github.com/code1986) - [sentinel-pigeon-adapter](https://github.com/wchswchs/sentinel-pigeon): A RPC framework Pigeon adapter for Sentinel including provider and invoker rate limiting implementation by [wchswchs](https://github.com/wchswchs) ## Blog Posts - [Sentinel 为 Dubbo 服务保驾护航](https://dubbo.apache.org/zh/blog/2018/07/27/sentinel-为-dubbo-服务保驾护航) by [Eric Zhao](https://github.com/sczyh30) - [在生产环境中使用 Sentinel 控制台](https://github.com/alibaba/Sentinel/wiki/在生产环境中使用-Sentinel) by [Eric Zhao](https://github.com/sczyh30) - [Sentinel 与 Hystrix 的对比](https://sentinelguard.io/zh-cn/blog/sentinel-vs-hystrix.html) by [Eric Zhao](https://github.com/sczyh30) - [Guideline: 从 Hystrix 迁移到 Sentinel](https://sentinelguard.io/zh-cn/blog/guideline-migrate-from-hystrix-to-sentinel.html) by [Eric Zhao](https://github.com/sczyh30) - [Sentinel 控制台监控数据持久化【MySQL】](https://www.cnblogs.com/cdfive2018/p/9838577.html) by [cdfive](https://github.com/cdfive) - [Sentinel 控制台监控数据持久化【InfluxDB】](https://www.cnblogs.com/cdfive2018/p/9914838.html) by [cdfive](https://github.com/cdfive) - [Sentinel 控制台监控数据持久化【Apollo】](https://blog.csdn.net/caodegao/article/details/100009618) by [cookiejoo](https://github.com/cookiejoo) - [Sentinel一体化监控解决方案 CrateDB + Grafana](https://blog.csdn.net/huyong1990/article/details/82392386) by [Young Hu](https://github.com/YoungHu) - Sentinel 源码解析系列 by [houyi](https://github.com/all4you) - [Sentinel 原理-全解析](https://mp.weixin.qq.com/s/7_pCkamNv0269e5l9_Wz7w) - [Sentinel 原理-调用链](https://mp.weixin.qq.com/s/UEzwD22YC6jpp02foNSXnw) - [Sentinel 原理-滑动窗口](https://mp.weixin.qq.com/s/B1_7Kb_CxeKEAv43kdCWOA) - [Sentinel 实战-限流](https://mp.weixin.qq.com/s/rjyU37Dm-sxNln7GUD8tOw) - [Sentinel 实战-控制台](https://mp.weixin.qq.com/s/23EDFHMXLwsDqw-4O5dR5A) - [Sentinel 实战-规则持久化](https://mp.weixin.qq.com/s/twMFiBfRawKLR-1-N-f1yw) - Sentinel 学习笔记 by [ro9er](https://github.com/ro9er) - [Sentinel 学习笔记（1）-- 流量统计代码解析](https://www.jianshu.com/p/7936d7a57924) - [Sentinel 学习笔记（2）-- 流量控制代码分析](https://www.jianshu.com/p/938709e94e43) - [Sentinel 学习笔记（3）-- 上下文统计Node建立分析](https://www.jianshu.com/p/cfdf525248c1) - [大流量下的服务质量治理 Dubbo Sentinel 初涉](https://mp.weixin.qq.com/s/ergr_siI07VwwSRPFgsLvQ) by [RyuGrade](https://github.com/RyuGrade) - Sentinel 深入浅出系列 by [shxz130](https://github.com/shxz130) - [Sentinel 深入浅出之原理篇 SlotChain](https://www.jianshu.com/p/a7a405de3a12) - [Sentinel 深入浅出之原理篇 Context初始化 & Entry初始化](https://www.jianshu.com/p/e39ac47cd893) - [Sentinel 深入浅出之原理篇 NodeSelectorSlot](https://www.jianshu.com/p/9a380ba188ab) - [Sentinel 深入浅出之原理篇 ClusterBuilderSlot](https://www.jianshu.com/p/0b0b5d8888a2) - [Sentinel 深入浅出之原理篇 StatisticSlot&滑动窗口](https://www.jianshu.com/p/9620298fd15a) - [Sentinel 深入浅出之原理篇 SystemSlot](https://www.jianshu.com/p/bfad1b7d0cde) - [Sentinel 深入浅出之原理篇 AuthoritySlot](https://www.jianshu.com/p/c5312c2242b3) - [Sentinel 深入浅出之原理篇 FlowSlot](https://www.jianshu.com/p/53218d0d273e) - [Sentinel 深入浅出之原理篇 DegradeSlot](https://www.jianshu.com/p/e910d4840e4a) - [Alibaba Sentinel RESTful 接口流控处理优化](https://www.jianshu.com/p/96f5980d9798) by [luanlouis](https://github.com/luanlouis) - [Sentinel 控制台前端开发环境搭建](https://www.cnblogs.com/cdfive2018/p/11084001.html) by [cdfive](https://github.com/cdfive) - [Sentinel 如何接入 OpenTracing](https://juejin.im/post/5de32fe46fb9a071a828feeb) by [Zhang Shun](https://github.com/ZShUn) - [阿里 Sentinel 源码解析](https://www.javadoop.com/post/sentinel) by [Javadoop](https://www.javadoop.com) - [阿里巴巴开源限流降级神器 Sentinel 大规模生产级应用实践](https://mp.weixin.qq.com/s/AjHCUmygTr78yo9yMxMEyg) by 步崖 - [Introduction to Alibaba Sentinel](https://www.baeldung.com/java-sentinel-intro) by [Amit Bhave](https://github.com/Amitbhave) - [Sentinel Go 毫秒级统计数据结构揭秘](https://sentinelguard.io/zh-cn/blog/sentinel-go-internal-data-structure.html) by [Binbin Zhang](https://github.com/binbin0325) --- ## File: sentinel-adapter/sentinel-apache-dubbo-adapter/README.md # Sentinel Apache Dubbo Adapter (for 2.7.x+) > Note: 中文文档请见[此处](https://sentinelguard.io/zh-cn/docs/open-source-framework-integrations.html)。 Sentinel Dubbo Adapter provides service consumer filter and provider filter for [Apache Dubbo](https://dubbo.apache.org/en/) services. **Note: This adapter only supports Apache Dubbo 2.7.x and above.** For legacy `com.alibaba:dubbo` 2.6.x, please use `sentinel-dubbo-adapter` module instead. To use Sentinel Dubbo Adapter, you can simply add the following dependency to your `pom.xml`: ```xml com.alibaba.csp sentinel-apache-dubbo-adapter x.y.z ``` The Sentinel filters are **enabled by default**. Once you add the dependency, the Dubbo services and methods will become protected resources in Sentinel, which can leverage Sentinel's flow control and guard ability when rules are configured. Demos can be found in [sentinel-demo-apache-dubbo](https://github.com/alibaba/Sentinel/tree/master/sentinel-demo/sentinel-demo-apache-dubbo). If you don't want the filters enabled, you can manually disable them. For example: ```xml ``` For more details of Dubbo filter, see [Dubbo filter documentation](https://cn.dubbo.apache.org/en/overview/mannual/java-sdk/tasks/extensibility/filter/). ## Dubbo resources The resource for Dubbo services has two granularities: service interface and service method. - Service interface: resourceName format is `interfaceName`, e.g. `com.alibaba.csp.sentinel.demo.dubbo.FooService` - Service method: resourceName format is `interfaceName:methodSignature`, e.g. `com.alibaba.csp.sentinel.demo.dubbo.FooService:sayHello(java.lang.String)` ## Flow control based on caller In many circumstances, it's also significant to control traffic flow based on the **caller**. For example, assuming that there are two services A and B, both of them initiate remote call requests to the service provider. If we want to limit the calls from service B only, we can set the `limitApp` of flow rule as the identifier of service B (e.g. service name). Sentinel Dubbo Adapter will automatically resolve the Dubbo consumer's *application name* as the caller's name (`origin`), and will bring the caller's name when doing resource protection. If `limitApp` of flow rules is not configured (`default`), flow control will take effects on all callers. If `limitApp` of a flow rule is configured with a caller, then the corresponding flow rule will only take effect on the specific caller. > Note: Earlier Dubbo 2.7.x consumer does not provide its Dubbo application name when doing RPC, > so developers should manually put the application name into *attachment* at consumer side, > then extract it at provider side. Sentinel Dubbo Adapter has implemented a filter (`DubboAppContextFilter`) > where consumer can carry application name information to provider automatically. > If the consumer does not use Sentinel Dubbo Adapter but requires flow control based on caller, > developers can manually put the application name into attachment with the key `dubboApplication`. > > Since 1.8.0, the adapter provides support for customizing origin parsing logic. You may register your own `DubboOriginParser` > implementation to `DubboAdapterGlobalConfig`. ## Global fallback Sentinel Dubbo Adapter supports global fallback configuration. The global fallback will handle exceptions and give replacement result when blocked by flow control, degrade or system load protection. You can implement your own `DubboFallback` interface and then register to `DubboAdapterGlobalConfig`. If no fallback is configured, Sentinel will wrap the `BlockException` as the fallback result. Besides, we can also leverage [Dubbo mock mechanism](http://dubbo.apache.org/en-us/docs/user/demos/local-mock.html) to provide fallback implementation of degraded Dubbo services. --- ## File: sentinel-adapter/sentinel-apache-dubbo3-adapter/README.md # Sentinel Apache Dubbo Adapter (for 3.0.5+) > Note: 中文文档请见[此处](https://sentinelguard.io/zh-cn/docs/open-source-framework-integrations.html)。 Sentinel Dubbo Adapter provides service consumer filter and provider filter for [Apache Dubbo](https://dubbo.apache.org/en/) services. **Note: This adapter only supports Apache Dubbo 3.0.5 and above.** For `org.apache:dubbo` 2.7.x, please use `sentinel-apache-dubbo-adapter` module instead. For legacy `com.alibaba:dubbo` 2.6.x, please use `sentinel-dubbo-adapter` module instead. To use Sentinel Dubbo 3.x Adapter, you can simply add the following dependency to your `pom.xml`: ```xml com.alibaba.csp sentinel-apache-dubbo3-adapter x.y.z ``` The Sentinel filters are **enabled by default**. Once you add the dependency, the Dubbo services and methods will become protected resources in Sentinel, which can leverage Sentinel's flow control and overload protection ability when rules are configured. Demos can be found in [sentinel-demo-apache-dubbo](https://github.com/alibaba/Sentinel/tree/master/sentinel-demo/sentinel-demo-apache-dubbo). If you don't want the filters enabled, you can manually disable them. For example: ```xml ``` For more details of Dubbo filter, see [Dubbo filter documentation](https://cn.dubbo.apache.org/en/overview/mannual/java-sdk/tasks/extensibility/filter/). ## Dubbo resources The resource for Dubbo services has two granularities: service interface and service method. - Service interface: resourceName format is `interfaceName`, e.g. `com.alibaba.csp.sentinel.demo.dubbo.FooService` - Service method: resourceName format is `interfaceName:methodSignature`, e.g. `com.alibaba.csp.sentinel.demo.dubbo.FooService:sayHello(java.lang.String)` > **Note**: Dubbo *group+version+interface* level is also supported in Sentinel Apache Dubbo adapter. > You may just add `-Dcsp.sentinel.dubbo.interface.group.version.enabled=true` JVM property, > then the resource name of the Dubbo interface and method will be prefixed with group and version info. ## Flow control based on caller In many circumstances, it's also significant to control traffic flow based on the **caller**. For example, assuming that there are two services A and B, both of them initiate remote call requests to the service provider. If we want to limit the calls from service B only, we can set the `limitApp` of flow rule as the identifier of service B (e.g. service name). Sentinel Dubbo Adapter will automatically resolve the Dubbo consumer's *application name* as the caller's name (`origin`), and will bring the caller's name when doing resource protection. If `limitApp` of flow rules is not configured (`default`), flow control will take effects on all callers. If `limitApp` of a flow rule is configured with a caller, then the corresponding flow rule will only take effect on the specific caller. > Note: The adapter provides support for customizing origin parsing logic as well. > You may register your own `DubboOriginParser` implementation to `DubboAdapterGlobalConfig`. ## Global fallback Sentinel Dubbo Adapter supports global fallback configuration. The global fallback will handle exceptions and give replacement result when blocked by flow control, degrade or system load protection. You can implement your own `DubboFallback` interface and then register to `DubboAdapterGlobalConfig`. If no fallback is configured, Sentinel will wrap the `BlockException` with a `RuntimeException` as the fallback result. Besides, we can also leverage [Dubbo mock mechanism](https://dubbo.apache.org/zh/docs3-v2/java-sdk/advanced-features-and-usage/service/service-downgrade/) to provide fallback implementation of degraded Dubbo services. --- ## File: sentinel-adapter/sentinel-apache-httpclient-adapter/README.md # Sentinel Apache Httpclient Adapter ## Introduction Sentinel provides integration for OkHttp client to enable flow control for web requests. Add the following dependency in `pom.xml` (if you are using Maven): ```xml com.alibaba.csp sentinel-apache-httpclient-adapter x.y.z ``` We can use the `SentinelApacheHttpClientBuilder` when `CloseableHttpClient` at initialization, for example: ```java CloseableHttpClient httpclient = new SentinelApacheHttpClientBuilder().build(); ``` If we want to add some additional configurations, we can refer to the following code ```java HttpClientBuilder builder = new SentinelApacheHttpClientBuilder(); //builder Other Definitions CloseableHttpClient httpclient = builder.build(); ``` ## Configuration - `SentinelApacheHttpClientConfig` configuration: | name | description | type | default value | |------|------------|------|-------| | prefix | customize resource prefix | `String` | `httpclient:` | | extractor | customize resource extractor | `ApacheHttpClientResourceExtractor` | `DefaultApacheHttpClientResourceExtractor` | | fallback | handle request when it is blocked | `ApacheHttpClientFallback` | `DefaultApacheHttpClientFallback` | ### extractor (resource extractor) We can define `ApacheHttpClientResourceExtractor` to customize resource extractor replace `DefaultApacheHttpClientResourceExtractor` at `SentinelApacheHttpClientBuilder` default config, for example: httpclient:GET:/httpclient/back/1 ==> httpclient:GET:/httpclient/back/{id} ```java SentinelApacheHttpClientConfig config = new SentinelApacheHttpClientConfig(); config.setExtractor(new ApacheHttpClientResourceExtractor() { @Override public String extractor(HttpRequestWrapper request) { String contains = "/httpclient/back/"; String uri = request.getRequestLine().getUri(); if (uri.startsWith(contains)) { uri = uri.substring(0, uri.indexOf(contains) + contains.length()) + "{id}"; } return request.getMethod() + ":" + uri; } }); CloseableHttpClient httpclient = new SentinelApacheHttpClientBuilder(config).build(); ``` ### fallback (Block handling) We can define `ApacheHttpClientFallback` at `SentinelApacheHttpClientBuilder` default config, to handle request is blocked according to the actual scenario, for example: ```java public class DefaultApacheHttpClientFallback implements ApacheHttpClientFallback { @Override public CloseableHttpResponse handle(HttpRequestWrapper request, BlockException e) { // Just wrap and throw the exception. throw new SentinelRpcException(e); } } ``` --- ## File: sentinel-adapter/sentinel-api-gateway-adapter-common/README.md # Sentinel API Gateway Adapter Common The `sentinel-api-gateway-adapter-common` module provides common abstraction for API gateway flow control: - `GatewayFlowRule`: flow control rule specific for route or API defined in API gateway. This can be automatically converted to `FlowRule` or `ParamFlowRule`. - `ApiDefinition`: gateway API definition with a group of predicates --- ## File: sentinel-adapter/sentinel-dubbo-adapter/README.md # Sentinel Dubbo Adapter > Note: 中文文档请见[此处](https://github.com/alibaba/Sentinel/wiki/主流框架的适配#dubbo)。 Sentinel Dubbo Adapter provides service consumer filter and provider filter for [Dubbo](https://dubbo.apache.org/en-us/) services. **Note: This adapter only supports legacy Dubbo 2.6.x version and below.** For new Apache Dubbo 2.7.x or above version, please use `sentinel-apache-dubbo-adapter` module instead. To use Sentinel Dubbo Adapter, you can simply add the following dependency to your `pom.xml`: ```xml com.alibaba.csp sentinel-dubbo-adapter x.y.z ``` The Sentinel filters are **enabled by default**. Once you add the dependency, the Dubbo services and methods will become protected resources in Sentinel, which can leverage Sentinel's flow control and guard ability when rules are configured. Demos can be found in [sentinel-demo-dubbo](https://github.com/alibaba/Sentinel/tree/master/sentinel-demo/sentinel-demo-dubbo). If you don't want the filters enabled, you can manually disable them. For example: ```xml ``` For more details of Dubbo filter, see [here](http://dubbo.apache.org/en-us/docs/dev/impls/filter.html). ## Dubbo resources The resource for Dubbo services has two granularities: service interface and service method. - Service interface：resourceName format is `interfaceName`，e.g. `com.alibaba.csp.sentinel.demo.dubbo.FooService` - Service method：resourceName format is `interfaceName:methodSignature`，e.g. `com.alibaba.csp.sentinel.demo.dubbo.FooService:sayHello(java.lang.String)` ## Flow control based on caller In many circumstances, it's also significant to control traffic flow based on the **caller**. For example, assuming that there are two services A and B, both of them initiate remote call requests to the service provider. If we want to limit the calls from service B only, we can set the `limitApp` of flow rule as the identifier of service B (e.g. service name). Sentinel Dubbo Adapter will automatically resolve the Dubbo consumer's *application name* as the caller's name (`origin`), and will bring the caller's name when doing resource protection. If `limitApp` of flow rules is not configured (`default`), flow control will take effects on all callers. If `limitApp` of a flow rule is configured with a caller, then the corresponding flow rule will only take effect on the specific caller. > Note: Dubbo consumer does not provide its Dubbo application name when doing RPC, > so developers should manually put the application name into *attachment* at consumer side, > then extract it at provider side. Sentinel Dubbo Adapter has implemented a filter (`DubboAppContextFilter`) > where consumer can carry application name information to provider automatically. > If the consumer does not use Sentinel Dubbo Adapter but requires flow control based on caller, > developers can manually put the application name into attachment with the key `dubboApplication`. > > Since 1.8.0, the adapter provides support for customizing origin parsing logic. You may register your own `DubboOriginParser` > implementation to `DubboAdapterGlobalConfig`. ## Global fallback Sentinel Dubbo Adapter supports global fallback configuration. The global fallback will handle exceptions and give replacement result when blocked by flow control, degrade or system load protection. You can implement your own `DubboFallback` interface and then register to `DubboAdapterGlobalConfig`. If no fallback is configured, Sentinel will wrap the `BlockException` as the fallback result. Besides, we can also leverage [Dubbo mock mechanism](http://dubbo.apache.org/en-us/docs/user/demos/local-mock.html) to provide fallback implementation of degraded Dubbo services. --- ## File: sentinel-adapter/sentinel-grpc-adapter/README.md # Sentinel gRPC Adapter Sentinel gRPC Adapter provides client and server interceptor for gRPC services. > Note that currently the interceptor only supports unary methods in gRPC. ## Client Interceptor Example: ```java public class ServiceClient { private final ManagedChannel channel; ServiceClient(String host, int port) { this.channel = ManagedChannelBuilder.forAddress(host, port) .intercept(new SentinelGrpcClientInterceptor()) // Add the client interceptor. .build(); // Init your stub here. } } ``` ## Server Interceptor Example: ```java import io.grpc.Server; Server server = ServerBuilder.forPort(port) .addService(new MyServiceImpl()) // Add your service. .intercept(new SentinelGrpcServerInterceptor()) // Add the server interceptor. .build(); ``` --- ## File: sentinel-adapter/sentinel-jax-rs-adapter/README.md # Sentinel adapter for JAX-RS Sentinel provides integration to enable fault-tolerance and flow control for JAX-RS web requests. Add the following dependency in `pom.xml` (if you are using Maven): ```xml com.alibaba.csp sentinel-jax-rs-adapter x.y.z ``` ## SentinelJaxRsProviderFilter The `SentinelJaxRsProviderFilter` is auto activated in pure JAX-RS application. For Spring web applications you can configure with Spring bean: ```java @Configuration public class FilterConfig { @Bean public SentinelJaxRsProviderFilter sentinelJaxRsProviderFilter() { return new SentinelJaxRsProviderFilter(); } } ``` ## DefaultExceptionMapper Sentinel provides DefaultExceptionMapper to map Throwable to Response (with Status.INTERNAL_SERVER_ERROR), in order to let SentinelJaxRsProviderFilter to be called and exit the Sentinel entry. According to `3.3.4 Exceptions` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf): > Checked exceptions and throwables that have not been mapped and cannot be thrown directly MUST be wrapped in a container-specific exception that is then thrown and allowed to propagate to the underlying container. If WebApplicationException or its subclasses are thrown, they'll be automatically converted to `Response` and can enter response filter. If other kind of exceptions were thrown, and not matched by custom exception mapper, then the response filter cannot be called. For this case, a default exception mapper maybe introduced. According to `4.4 Exception Mapping Providers` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf): > When choosing an exception mapping provider to map an exception, an implementation MUST use the provider whose generic type is the nearest superclass of the exception. If two or more exception providers are applicable, the one with the highest priority MUST be chosen as described in Section 4.1.3. If user also provides customized exception mapper of `Throwable`, then user has the responsibility to convert it to response and then the response filter can be called. As describe in `6.7.1 exceptions` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf): > A response mapped from an exception MUST be processed using the ContainerResponse filter chain and the WriteTo interceptor chain (if an entity is present in the mapped response). ## SentinelJaxRsClientTemplate For jax-rs client, we provide `SentinelJaxRsClientTemplate` you can use it like this: ``` Response response = SentinelJaxRsClientTemplate.execute(resourceName, new Supplier() { @Override public Response get() { return client.target(host).path(url).request() .get(); } }); ``` or executeAsync like this: ``` Future future = SentinelJaxRsClientTemplate.executeAsync(resourceName, new Supplier>() { @Override public Future get() { return client.target(host).path(url).request() .async() .get(); } }); ``` When a request is blocked, Sentinel JAX-RS filter will return Response with status of `TOO_MANY_REQUESTS` indicating the request is rejected. You can customize it by implement your own `SentinelJaxRsFallback` and register to `SentinelJaxRsConfig`.