diff --git a/README.md b/README.md index 68725af974..54e6af3102 100755 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ # Sentinel: Sentinel of Your Application [![Travis Build Status](https://travis-ci.org/alibaba/Sentinel.svg?branch=master)](https://travis-ci.org/alibaba/Sentinel) +[![Maven Central](https://img.shields.io/maven-central/v/com.alibaba.csp/sentinel-core.svg?label=Maven%20Central)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.alibaba.csp%22%20a%3A%22sentinel-core%22) [![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) [![Gitter](https://badges.gitter.im/alibaba/Sentinel.svg)](https://gitter.im/alibaba/Sentinel) diff --git a/sentinel-adapter/sentinel-dubbo-adapter/README.md b/sentinel-adapter/sentinel-dubbo-adapter/README.md index a897de5b48..a49a90209d 100755 --- a/sentinel-adapter/sentinel-dubbo-adapter/README.md +++ b/sentinel-adapter/sentinel-dubbo-adapter/README.md @@ -1,5 +1,7 @@ # Sentinel Dubbo Adapter +> Note: 中文文档请见[此处](https://github.com/alibaba/Sentinel/wiki/%E4%B8%BB%E6%B5%81%E6%A1%86%E6%9E%B6%E7%9A%84%E9%80%82%E9%85%8D#dubbo)。 + Sentinel Dubbo Adapter provides service consumer filter and provider filter for [Dubbo](http://dubbo.io/) services. @@ -50,4 +52,14 @@ If `limitApp` of a flow rule is configured with a caller, then the corresponding 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`. \ No newline at end of file +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`. + +## Global fallback + +Since version 0.1.1, 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 `DubboFallbackRegistry`. If no fallback is configured, Sentinel will wrap the `BlockException` +then directly throw it out. + +Besides, we can also leverage [Dubbo mock mechanism](http://dubbo.apache.org/#!/docs/user/demos/local-mock.md?lang=en-us) to provide fallback implementation of degraded Dubbo services. \ No newline at end of file diff --git a/sentinel-demo/README.md b/sentinel-demo/README.md index 1849b835ff..4ddf454b3a 100755 --- a/sentinel-demo/README.md +++ b/sentinel-demo/README.md @@ -2,8 +2,8 @@ The examples demonstrate: -- How to use basic functions (e.g. flow control, circuit breaking, load protection) of Sentinel -- How to use file as the dynamic datasource of the rules in Sentinel +- How to leverage basic features (e.g. flow control, circuit breaking, load protection) of Sentinel +- How to use various data source extensions of Sentinel (e.g. file, Nacos, ZooKeeper) - How to use Dubbo with Sentinel - How to use Apache RocketMQ client with Sentinel diff --git a/sentinel-demo/sentinel-demo-dubbo/README.md b/sentinel-demo/sentinel-demo-dubbo/README.md index 920afa3300..2a9fc3ea3d 100644 --- a/sentinel-demo/sentinel-demo-dubbo/README.md +++ b/sentinel-demo/sentinel-demo-dubbo/README.md @@ -12,6 +12,8 @@ Sentinel 提供了与 Dubbo 整合的模块 - Sentinel Dubbo Adapter,主要包 引入此依赖后,Dubbo 的服务接口和方法(包括调用端和服务端)就会成为 Sentinel 中的资源,在配置了规则后就可以自动享受到 Sentinel 的防护能力。 +> **注:若希望接入 Dashboard,请参考后面接入控制台的步骤。只引入 Sentinel Dubbo Adapter 无法接入控制台!** + 若不希望开启 Sentinel Dubbo Adapter 中的某个 Filter,可以手动关闭对应的 Filter,比如: ```java @@ -56,12 +58,26 @@ Demo 1 演示了此限流场景,我们看一下这种模式的限流产生的 ## Service Consumer +> 对服务提供方的流量控制可分为**控制并发线程数**和**服务降级**两个维度。 + +### 并发线程数限流 + Service Consumer 作为客户端去调用远程服务。每一个服务都可能会依赖几个下游服务,若某个服务 A 依赖的下游服务 B 出现了不稳定的情况,服务 A 请求 服务 B 的响应时间变长,从而服务 A 调用服务 B 的线程就会产生堆积,最终可能耗尽服务 A 的线程数。我们通过用并发线程数来控制对下游服务 B 的访问,来保证下游服务不可靠的时候,不会拖垮服务自身。基于这种场景,推荐给 Consumer 配置**线程数模式**的限流,来保证自身不被不稳定服务所影响。限流粒度同样可以是服务接口和服务方法两种粒度。 采用基于线程数的限流模式后,我们不需要再显式地去进行线程池隔离,Sentinel 会控制资源的线程数,超出的请求直接拒绝,直到堆积的线程处理完成。 Demo 2 演示了此限流场景,我们看一下这种模式的效果。假设当前服务 A 依赖两个远程服务方法 `sayHello(java.lang.String)` 和 `doAnother()`。前者远程调用的响应时间 为 1s-1.5s之间,后者 RT 非常小(30 ms 左右)。服务 A 端设两个远程方法 thread count 为 5。然后每隔 50 ms 左右向线程池投入两个任务,作为消费者分别远程调用对应方法,持续 10 次。可以看到 `sayHello` 方法被限流 5 次,因为后面调用的时候前面的远程调用还未返回(RT 高);而 `doAnother()` 调用则不受影响。线程数目超出时快速失败能够有效地防止自己被慢调用所影响。 +### 服务降级 + +当服务依赖于多个下游服务,而某个下游服务调用非常慢时,会严重影响当前服务的调用。这里我们可以利用 Sentinel 熔断降级的功能,为调用端配置基于平均 RT 的[降级规则](https://github.com/alibaba/Sentinel/wiki/%E7%86%94%E6%96%AD%E9%99%8D%E7%BA%A7)。这样当调用链路中某个服务调用的平均 RT 升高,在一定的次数内超过配置的 RT 阈值,Sentinel 就会对此调用资源进行降级操作,接下来的调用都会立刻拒绝,直到过了一段设定的时间后才恢复,从而保护服务不被调用端短板所影响。同时可以配合 fallback 功能使用,在被降级的时候提供相应的处理逻辑。 + +## Fallback + +从 0.1.1 版本开始,Sentinel Dubbo Adapter 还支持配置全局的 fallback 函数,可以在 Dubbo 服务被限流/降级/负载保护的时候进行相应的 fallback 处理。用户只需要实现自定义的 [`DubboFallback`](https://github.com/alibaba/Sentinel/blob/master/sentinel-adapter/sentinel-dubbo-adapter/src/main/java/com/alibaba/csp/sentinel/adapter/dubbo/fallback/DubboFallback.java) 接口,并通过 `DubboFallbackRegistry` 注册即可。默认情况会直接将 `BlockException` 包装后抛出。同时,我们还可以配合 [Dubbo 的 fallback 机制](http://dubbo.apache.org/#!/docs/user/demos/local-mock.md?lang=zh-cn) 来为降级的服务提供替代的实现。 + +Demo 2 的 Consumer 端提供了一个简单的 fallback 示例。 + ## Sentinel Dashboard Sentinel 还提供 API 用于获取实时的监控信息,对应文档见[此处](https://github.com/alibaba/Sentinel/wiki/%E5%AE%9E%E6%97%B6%E7%9B%91%E6%8E%A7)。为了便于使用,Sentinel 还提供了一个控制台(Dashboard)用于配置规则、查看监控、机器发现等功能。 diff --git a/sentinel-transport/README.md b/sentinel-transport/README.md new file mode 100644 index 0000000000..a8d5da2c35 --- /dev/null +++ b/sentinel-transport/README.md @@ -0,0 +1,4 @@ +# Sentinel Transport + +The Sentinel transport module provides basic interfaces about Sentinel monitoring API server and client +(`CommandCenter` and `HeartbeatSender`) as well implementations using different libraries or protocols. \ No newline at end of file