Skip to content

Commit

Permalink
Update documents
Browse files Browse the repository at this point in the history
- Add Maven Central badge

Signed-off-by: Eric Zhao <sczyh16@gmail.com>
  • Loading branch information
sczyh30 committed Aug 9, 2018
1 parent 227776a commit b42a930
Show file tree
Hide file tree
Showing 5 changed files with 36 additions and 3 deletions.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
14 changes: 13 additions & 1 deletion sentinel-adapter/sentinel-dubbo-adapter/README.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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`.
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.
4 changes: 2 additions & 2 deletions sentinel-demo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

16 changes: 16 additions & 0 deletions sentinel-demo/sentinel-demo-dubbo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ Sentinel 提供了与 Dubbo 整合的模块 - Sentinel Dubbo Adapter,主要包

引入此依赖后,Dubbo 的服务接口和方法(包括调用端和服务端)就会成为 Sentinel 中的资源,在配置了规则后就可以自动享受到 Sentinel 的防护能力。

> **注:若希望接入 Dashboard,请参考后面接入控制台的步骤。只引入 Sentinel Dubbo Adapter 无法接入控制台!**
若不希望开启 Sentinel Dubbo Adapter 中的某个 Filter,可以手动关闭对应的 Filter,比如:

```java
Expand Down Expand Up @@ -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)用于配置规则、查看监控、机器发现等功能。
Expand Down
4 changes: 4 additions & 0 deletions sentinel-transport/README.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit b42a930

Please sign in to comment.