From 832d6e425df3b6f78dee36cd020db47a9841edfc Mon Sep 17 00:00:00 2001 From: Eric Zhao Date: Sat, 29 Dec 2018 15:23:27 +0800 Subject: [PATCH] Update document to meet Markdown lint Signed-off-by: Eric Zhao --- CODE_OF_CONDUCT.md | 2 +- CONTRIBUTING.md | 24 ++++++++--------- README.md | 27 ++++++++----------- doc/awesome-sentinel.md | 8 +++--- .../sentinel-dubbo-adapter/README.md | 2 +- .../sentinel-grpc-adapter/README.md | 2 +- sentinel-dashboard/README.md | 1 - .../src/main/webapp/resources/README.md | 10 +++---- .../src/main/webapp/resources/README_zh.md | 10 +++---- .../sentinel-annotation-aspectj/README.md | 10 ++----- .../sentinel-datasource-redis/README.md | 5 +--- .../sentinel-parameter-flow-control/README.md | 4 +-- 12 files changed, 43 insertions(+), 62 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index ddd80669..855bd529 100755 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -68,6 +68,6 @@ members of the project's leadership. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html +available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html) [homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4618d955..1fe41821 100755 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,17 +3,17 @@ Welcome to Sentinel! This document is a guideline about how to contribute to Sentinel. If you find something incorrect or missing, please leave comments / suggestions. -# Before you get started +## Before you get started -## Code of Conduct +### Code of Conduct Please make sure to read and observe our [Code of Conduct](./CODE_OF_CONDUCT.md). -## Setting up your development environment +### Setting up your development environment You should have JDK 1.8 or later installed in your system. -# Contributing +## Contributing We are always very happy to have contributions, whether for typo fix, bug fix or big new features. Please do not ever hesitate to ask a question or send a pull request. @@ -21,7 +21,7 @@ Please do not ever hesitate to ask a question or send a pull request. We strongly value documentation and integration with other projects. We are very glad to accept improvements for these aspects. -## GitHub workflow +### GitHub workflow We use the `master` branch as the development branch, which indicates that this is a unstable branch. @@ -44,7 +44,7 @@ The reviewers will review the code. Before merging a PR, squash any fix review feedback, typo, merged, and rebased sorts of commits. The final commit message should be clear and concise. -## Open an issue / PR +### Open an issue / PR We use [GitHub Issues](https://github.com/alibaba/Sentinel/issues) and [Pull Requests](https://github.com/alibaba/Sentinel/pulls) for trackers. @@ -54,12 +54,12 @@ Please follow the guideline message in the issue template. If you want to contribute, please follow the [contribution workflow](#github-workflow) and create a new pull request. If your PR contains large changes, e.g. component refactor or new components, please write detailed documents -about its design and usage. +about its design and usage. Note that a single PR should not be too large. If heavy changes are required, it's better to separate the changes to a few individual PRs. -## Code review +### Code review All code should be well reviewed by one or more committers. Some principles: @@ -67,14 +67,14 @@ All code should be well reviewed by one or more committers. Some principles: - Elegance: New functions, classes or components should be well designed. - Testability: Important code should be well-tested (high unit test coverage). -# Community +## Community -## Contact us +### Contact us -### Mailing list +#### Mailing list If you have any questions or advice, please contact sentinel@linux.alibaba.com. -### Gitter +#### Gitter Our Gitter room: [https://gitter.im/alibaba/Sentinel](https://gitter.im/alibaba/Sentinel). \ No newline at end of file diff --git a/README.md b/README.md index 8c559d45..77351fe4 100755 --- a/README.md +++ b/README.md @@ -8,24 +8,17 @@ [![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) -## What Does It Do? +## 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**, **circuit breaking** and **system adaptive protection**, to guarantee service reliability. 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, Dubbo and gRPC. You can easily use Sentinel by simply add the adapter dependency to your services. - -- **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. +- **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, Dubbo and gRPC. You can easily use Sentinel by simply add the adapter dependency to your services. +- **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. ## Documentation @@ -63,9 +56,9 @@ Wrap code snippet via Sentinel API: `SphU.entry("resourceName")` and `entry.exit ```java Entry entry = null; -try { +try { entry = SphU.entry("HelloWorld"); - + // BIZ logic being protected System.out.println("hello world"); } catch (BlockException e) { @@ -82,7 +75,8 @@ So far the code modification is done. We also provide [annotation support module ### 3. Define Rules -If we want to limit the access times of the resource, we can define rules. The following code defines a rule that limits access to the reource to 20 times per second at the maximum. +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<>(); @@ -112,6 +106,7 @@ After running the demo for a while, you can see the following records in `~/logs p stands for incoming request, block for blocked by rules, success for success handled by Sentinel, e for exception count, rt for average response time (ms) ``` + 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://github.com/alibaba/Sentinel/wiki/How-to-Use) section. @@ -140,7 +135,7 @@ Contact us: sentinel@linux.alibaba.com Contributions are always welcomed! Please see [CONTRIBUTING](./CONTRIBUTING.md) for detailed guidelines. -You can start with the issues labeled with [`good first issue`](https://github.com/alibaba/Sentinel/pulls?q=is%3Apr+is%3Aopen+label%3A%22good+first+issue%22). +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). ## Credits diff --git a/doc/awesome-sentinel.md b/doc/awesome-sentinel.md index e655952f..d871eb2d 100644 --- a/doc/awesome-sentinel.md +++ b/doc/awesome-sentinel.md @@ -18,8 +18,6 @@ You can also add to [sentinel-group/sentinel-awesome](https://github.com/sentine ## Tutorials - - ## Samples / Demos - [sentinel-zuul-example](https://github.com/tigerMoon/sentinel-zuul-sample): A simple project integration Sentinel to Spring Cloud Zuul which provide Service and API Path level flow control management by [tiger](https://github.com/tigerMoon) @@ -31,8 +29,8 @@ You can also add to [sentinel-group/sentinel-awesome](https://github.com/sentine ## Blogs - [Sentinel 为 Dubbo 服务保驾护航](http://dubbo.apache.org/zh-cn/blog/sentinel-introduction-for-dubbo.html) by [Eric Zhao](https://github.com/sczyh30) -- [Sentinel 与 Hystrix 的对比](https://github.com/alibaba/Sentinel/wiki/Sentinel-%E4%B8%8E-Hystrix-%E7%9A%84%E5%AF%B9%E6%AF%94) -- [Guideline: 从 Hystrix 迁移到 Sentinel](https://github.com/alibaba/Sentinel/wiki/Guideline:-%E4%BB%8E-Hystrix-%E8%BF%81%E7%A7%BB%E5%88%B0-Sentinel) +- [Sentinel 与 Hystrix 的对比](https://github.com/alibaba/Sentinel/wiki/Sentinel-%E4%B8%8E-Hystrix-%E7%9A%84%E5%AF%B9%E6%AF%94) by [Eric Zhao](https://github.com/sczyh30) +- [Guideline: 从 Hystrix 迁移到 Sentinel](https://github.com/alibaba/Sentinel/wiki/Guideline:-%E4%BB%8E-Hystrix-%E8%BF%81%E7%A7%BB%E5%88%B0-Sentinel) by [Eric Zhao](https://github.com/sczyh30) - [Sentinel 控制台监控数据持久化【MySQL】(Spring Data JPA)](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一体化监控解决方案 CrateDB+Grafana](https://blog.csdn.net/huyong1990/article/details/82392386) by [Young Hu](https://github.com/YoungHu) +- [Sentinel一体化监控解决方案 CrateDB+Grafana](https://blog.csdn.net/huyong1990/article/details/82392386) by [Young Hu](https://github.com/YoungHu) \ No newline at end of file diff --git a/sentinel-adapter/sentinel-dubbo-adapter/README.md b/sentinel-adapter/sentinel-dubbo-adapter/README.md index 76e5a322..b29e3705 100755 --- a/sentinel-adapter/sentinel-dubbo-adapter/README.md +++ b/sentinel-adapter/sentinel-dubbo-adapter/README.md @@ -3,7 +3,7 @@ > 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. +for [Dubbo](http://dubbo.io/) services. To use Sentinel Dubbo Adapter, you can simply add the following dependency to your `pom.xml`: diff --git a/sentinel-adapter/sentinel-grpc-adapter/README.md b/sentinel-adapter/sentinel-grpc-adapter/README.md index 103f9927..38d60030 100755 --- a/sentinel-adapter/sentinel-grpc-adapter/README.md +++ b/sentinel-adapter/sentinel-grpc-adapter/README.md @@ -3,7 +3,7 @@ Sentinel gRPC Adapter provides client and server interceptor for gRPC services. > Note that currently the interceptor only supports unary methods in gRPC. - In some circumstances (e.g. asynchronous call), the RT metrics might not be accurate. +> In some circumstances (e.g. asynchronous call), the RT metrics might not be accurate. ## Client Interceptor diff --git a/sentinel-dashboard/README.md b/sentinel-dashboard/README.md index e8bf3c4e..321d8e6e 100755 --- a/sentinel-dashboard/README.md +++ b/sentinel-dashboard/README.md @@ -48,5 +48,4 @@ java -Dserver.port=8080 \ 客户端正确配置并启动后，会主动向控制台发送心跳包，汇报自己的存在；控制台收到客户端心跳包之后，会在左侧导航栏中显示该客户端信息。控制台能够看到客户端的机器信息，则表明客户端接入成功了。 - 更多：[控制台功能介绍](./Sentinel_Dashboard_Feature.md)。 \ No newline at end of file diff --git a/sentinel-dashboard/src/main/webapp/resources/README.md b/sentinel-dashboard/src/main/webapp/resources/README.md index b186fd8a..c88ea68c 100755 --- a/sentinel-dashboard/src/main/webapp/resources/README.md +++ b/sentinel-dashboard/src/main/webapp/resources/README.md @@ -1,4 +1,4 @@ -# Sentinel-Dashboard +# Sentinel Dashboard Frontend ## Env Requirement @@ -6,8 +6,8 @@ ## Code Guide -- Code Style Guide for HTML/CSS: https://codeguide.bootcss.com/ -- Airbnb JavaScript Style Guide: https://github.com/airbnb/javascript/tree/es5-deprecated/es5 +- [Code Style Guide for HTML/CSS](https://codeguide.bootcss.com/) +- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript/tree/es5-deprecated/es5) ## Install Packages @@ -27,6 +27,6 @@ npm start npm run build ``` -## CREDIT: +## Credit -- [sb-admin-angular](https://github.com/start-angular/sb-admin-angular) +- [sb-admin-angular](https://github.com/start-angular/sb-admin-angular) \ No newline at end of file diff --git a/sentinel-dashboard/src/main/webapp/resources/README_zh.md b/sentinel-dashboard/src/main/webapp/resources/README_zh.md index c7893ad3..5daf33ef 100644 --- a/sentinel-dashboard/src/main/webapp/resources/README_zh.md +++ b/sentinel-dashboard/src/main/webapp/resources/README_zh.md @@ -1,4 +1,4 @@ -# Sentinel-Dashboard +# Sentinel Dashboard Frontend ## 环境要求 @@ -6,8 +6,8 @@ ## 编码规范 -- HTML/CSS 遵循 Bootstrap 编码规范，参考：https://codeguide.bootcss.com/ -- JavaScript 遵循 Airbnb JavaScript Style Guide，参考：https://github.com/airbnb/javascript/tree/es5-deprecated/es5 +- HTML/CSS 遵循 [Bootstrap 编码规范](https://codeguide.bootcss.com/) +- JavaScript 遵循 [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript/tree/es5-deprecated/es5) 以及最新的 ES 6 标准 ## 安装依赖 @@ -27,6 +27,6 @@ npm start npm run build ``` -## CREDIT: +## Credit -- [sb-admin-angular](https://github.com/start-angular/sb-admin-angular) +- [sb-admin-angular](https://github.com/start-angular/sb-admin-angular) \ No newline at end of file diff --git a/sentinel-extension/sentinel-annotation-aspectj/README.md b/sentinel-extension/sentinel-annotation-aspectj/README.md index 6960ed52..75576460 100644 --- a/sentinel-extension/sentinel-annotation-aspectj/README.md +++ b/sentinel-extension/sentinel-annotation-aspectj/README.md @@ -9,14 +9,8 @@ The `@SentinelResource` annotation indicates a resource definition, including: - `value`: Resource name, required (cannot be empty) - `entryType`: Resource entry type (inbound or outbound), `EntryType.OUT` by default -- `fallback`: Fallback method when degraded (optional). -The fallback method should be located in the same class with original method. -The signature of the fallback method should match the original method (parameter types and return type). -- `blockHandler`: Handler method that handles `BlockException` when blocked. -The signature should match original method, with the last additional parameter type `BlockException`. -The block handler method should be located in the same class with original method by default. -If you want to use method in other classes, you can set the `blockHandlerClass` with corresponding `Class` -(Note the method in other classes must be *static*). +- `fallback`: Fallback method when degraded (optional). The fallback method should be located in the same class with original method. The signature of the fallback method should match the original method (parameter types and return type). +- `blockHandler`: Handler method that handles `BlockException` when blocked. The signature should match original method, with the last additional parameter type `BlockException`. The block handler method should be located in the same class with original method by default. If you want to use method in other classes, you can set the `blockHandlerClass` with corresponding `Class` (Note the method in other classes must be *static*). For example: diff --git a/sentinel-extension/sentinel-datasource-redis/README.md b/sentinel-extension/sentinel-datasource-redis/README.md index 399057be..2436df04 100644 --- a/sentinel-extension/sentinel-datasource-redis/README.md +++ b/sentinel-extension/sentinel-datasource-redis/README.md @@ -31,8 +31,7 @@ FlowRuleManager.register2Property(redisDataSource.getProperty()); - `ruleKey`: the rule persistence key of a Redis String - `channel`: the channel to subscribe -You can also create multi data sources to subscribe for different rule type. - +You can also create multi data sources to subscribe for different rule type. Note that the data source first loads initial rules from a Redis String (provided `ruleKey`) during initialization. So for consistency, users should publish the value and save the value to the `ruleKey` simultaneously like this (using Redis transaction): @@ -60,7 +59,6 @@ public void pushRules(List rules, Converter, String> encoder) { ## How to build RedisConnectionConfig - ### Build with Redis standalone mode ```java @@ -73,7 +71,6 @@ RedisConnectionConfig config = RedisConnectionConfig.builder() ``` - ### Build with Redis Sentinel mode ```java diff --git a/sentinel-extension/sentinel-parameter-flow-control/README.md b/sentinel-extension/sentinel-parameter-flow-control/README.md index f441df64..bf698a42 100644 --- a/sentinel-extension/sentinel-parameter-flow-control/README.md +++ b/sentinel-extension/sentinel-parameter-flow-control/README.md @@ -56,6 +56,4 @@ The description for fields of `ParamFlowRule`: | paramIdx | the index of provided parameter in `SphU.entry(xxx, args)` (**required**) || | paramFlowItemList | the exception items of parameter; you can set threshold to a specific parameter value || - -Now the parameter flow control rules will take effect. - +Now the parameter flow control rules will take effect. \ No newline at end of file