You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2018/06/19 03:26:37 UTC
[incubator-servicecomb-docs] branch master updated (e16a491 ->
160b4d3)
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git.
from e16a491 解决表格显示不全的问题CSS错误
new cca6915 增加AccessLog自定义扩展的说明
new 160b4d3 更新负载均衡配置项的说明，细化provider端限流策略注意事项的说明
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../build-provider/access-log-configuration.md | 161 +++++++++++++++++----
.../build-provider/configuration/lb-strategy.md | 27 ++--
.../configuration/ratelimite-strategy.md | 3 +-
3 files changed, 148 insertions(+), 43 deletions(-)
[incubator-servicecomb-docs] 02/02: 更新负载均衡配置项的说明，细化provider端限流策略注意事项的说明
Posted by li...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git
commit 160b4d3a48676113d4b580d6a70f0ace8d302e2a
Author: yaohaishi <ya...@huawei.com>
AuthorDate: Wed Jun 13 12:59:09 2018 +0800
更新负载均衡配置项的说明，细化provider端限流策略注意事项的说明
---
.../build-provider/configuration/lb-strategy.md | 27 +++++++++++-----------
.../configuration/ratelimite-strategy.md | 3 +--
2 files changed, 15 insertions(+), 15 deletions(-)
diff --git a/java-chassis-reference/zh_CN/build-provider/configuration/lb-strategy.md b/java-chassis-reference/zh_CN/build-provider/configuration/lb-strategy.md
index 27a53b6..9028584 100644
--- a/java-chassis-reference/zh_CN/build-provider/configuration/lb-strategy.md
+++ b/java-chassis-reference/zh_CN/build-provider/configuration/lb-strategy.md
@@ -10,19 +10,20 @@ ServiceComb提供了基于Ribbon的负载均衡方案，用户可以通过配置
| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
| :--- | :--- | :--- | :--- | :--- | :--- |
-| servicecomb.loadbalance.strategy.name | RoundRobin | RoundRobin（轮询）<br/>Random（随机）<br/>WeightedResponse（服务器响应时间权值）<br/>SessionStickiness（会话保持） | 否 | 负载均衡路由策略 | - |
-| servicecomb.loadbalance.SessionStickinessRule.sessionTimeoutInSeconds | 30 | Integer | 否 | 客户端闲置时间，超过限制后选择后面的服务器。 | 暂不支持微服务配置。e.g. servicecomb.loadbalance.SessionStickinessRule.sessionTimeoutInSeconds，不能配置为servicecomb.loadbalance.DemoService.SessionStickinessRule.sessionTimeoutInSeconds |
-| servicecomb.loadbalance.SessionStickinessRule.successiveFailedTimes | 5 | Integer | 否 | 客户端失败次数，超过后会切换服务器 | 暂不支持微服务配置 |
-| servicecomb.loadbalance.retryEnabled | FALSE | Boolean | 否 | 负载均衡捕获到服务调用异常，是否进行重试 | - |
-| servicecomb.loadbalance.retryOnNext | 0 | Integer | 否 | 尝试新的服务器的次数 | - |
-| servicecomb.loadbalance.retryOnSame | 0 | Integer | 否 | 同一个服务器尝试的次数 | - |
-| servicecomb.loadbalance.isolation.enabled | FALSE | Boolean | 否 | 是否开启故障实例隔离功能 | - |
-| servicecomb.loadbalance.isolation.enableRequestThreshold | 20 | Integer | 否 | 当实例的调用总次数达到该值时开始进入隔离逻辑门槛 | - |
-| servicecomb.loadbalance.isolation.continuousFailureThreshold | - | Integer | 否 | 当请求实例连续出错达到此阈值时触发实例隔离 | 若配置了此项则覆盖实例故障百分比的配置，否则按照实例故障百分比触发隔离。<br/>由于按请求错误率触发实例隔离在请求次数较多时不易触发也不易恢复，因此建议使用此配置项代替实例故障百分比配置。<br/>请求实例成功时会将连续错误次数请零以保证实例快速恢复。 |
-| servicecomb.loadbalance.isolation.errorThresholdPercentage | 20 | Integer，区间为\(0,100\] | 否 | 实例故障隔离错误百分比 | - |
-| servicecomb.loadbalance.isolation.singleTestTime | 10000 | Integer | 否 | 故障实例单点测试时间 | 单位为ms |
-| servicecomb.loadbalance.transactionControl.policy | org.apache.servicecomb.loadbalance.filter.SimpleTransactionControlFilter | - | 否 | 动态路由分流策略 | 框架提供了简单的分流机制，开发者也可以实现自定义的分流过滤策略 |
-| servicecomb.loadbalance.transactionControl.options | - | key/value pairs | 否 | 针对SimpleTransactionControlFilter分流策略的配置项，可添加任意项过滤标签 | - |
+| servicecomb.loadbalance.\[服务名\].strategy.name | RoundRobin | RoundRobin（轮询）<br/>Random（随机）<br/>WeightedResponse（服务器响应时间权值）<br/>SessionStickiness（会话保持） | 否 | 负载均衡路由策略 | - |
+| servicecomb.loadbalance.\[服务名\].SessionStickinessRule.sessionTimeoutInSeconds | 30 | Integer | 否 | 客户端闲置时间，超过限制后选择后面的服务器。 | - |
+| servicecomb.loadbalance.\[服务名\].SessionStickinessRule.successiveFailedTimes | 5 | Integer | 否 | 客户端失败次数，超过后会切换服务器 | - |
+| servicecomb.loadbalance.\[服务名\].retryEnabled | FALSE | Boolean | 否 | 负载均衡捕获到服务调用异常，是否进行重试 | - |
+| servicecomb.loadbalance.\[服务名\].retryOnNext | 0 | Integer | 否 | 尝试新的服务器的次数 | - |
+| servicecomb.loadbalance.\[服务名\].retryOnSame | 0 | Integer | 否 | 同一个服务器尝试的次数 | - |
+| servicecomb.loadbalance.\[服务名\].isolation.enabled | FALSE | Boolean | 否 | 是否开启故障实例隔离功能 | - |
+| servicecomb.loadbalance.\[服务名\].isolation.enableRequestThreshold | 20 | Integer | 否 | 当实例的调用总次数达到该值时开始进入隔离逻辑门槛 | - |
+| servicecomb.loadbalance.\[服务名\].isolation.continuousFailureThreshold | - | Integer | 否 | 当请求实例连续出错达到此阈值时触发实例隔离 | 若配置了此项则覆盖实例故障百分比的配置，否则按照实例故障百分比触发隔离。<br/>由于按请求错误率触发实例隔离在请求次数较多时不易触发也不易恢复，因此建议使用此配置项代替实例故障百分比配置。<br/>请求实例成功时会将连续错误次数请零以保证实例快速恢复。 |
+| servicecomb.loadbalance.\[服务名\].isolation.errorThresholdPercentage | 20 | Integer，区间为\(0,100\] | 否 | 实例故障隔离错误百分比 | - |
+| servicecomb.loadbalance.\[服务名\].isolation.singleTestTime | 10000 | Integer | 否 | 故障实例单点测试时间 | 单位为ms |
+
+**说明**：
+- 以上配置项都支持全局和微服务两个粒度的配置。例如：servicecomb.loadbalance.strategy.name是全局的负载均衡路由策略；servicecomb.loadbalance.DemoService.strategy.name是仅在调用DemoService服务时生效的负载均衡路由策略。
## 示例代码
diff --git a/java-chassis-reference/zh_CN/build-provider/configuration/ratelimite-strategy.md b/java-chassis-reference/zh_CN/build-provider/configuration/ratelimite-strategy.md
index b503f04..5d4dca5 100644
--- a/java-chassis-reference/zh_CN/build-provider/configuration/ratelimite-strategy.md
+++ b/java-chassis-reference/zh_CN/build-provider/configuration/ratelimite-strategy.md
@@ -6,7 +6,7 @@
1. 限流策略的控制并不是绝对精确的，可能会有少量误差。
2. provider端的流量控制是业务层面的功能，不是安全意义上的流量控制，如需防止DDoS攻击，需要结合其他的一系列措施。
-3. 流量控制是微服务级的，不是进程级的。
+3. 流量控制是微服务级的，不是实例级的。例如一个consumer服务有三个实例，当对它们依赖的provider实例配置限流策略后，provider不会区分consumer的请求具体是由哪个实例发出的，而是汇总成微服务级的统计数据进行限流判断。
## 配置说明
@@ -39,4 +39,3 @@
> **注意：**
> provider端限流策略配置中的`ServiceName`指的是调用该provider的consumer，而`shema`、`operation`指的是provider自身的。即provider端限流配置的含义是，限制指定consumer调用本provider的某个schema、operation的流量。
-
[incubator-servicecomb-docs] 01/02: 增加AccessLog自定义扩展的说明
Posted by li...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git
commit cca6915f707d34f6dade06d51c72492668edd513
Author: yaohaishi <ya...@huawei.com>
AuthorDate: Tue Jun 12 21:18:36 2018 +0800
增加AccessLog自定义扩展的说明
---
.../build-provider/access-log-configuration.md | 161 +++++++++++++++++----
1 file changed, 133 insertions(+), 28 deletions(-)
diff --git a/java-chassis-reference/zh_CN/build-provider/access-log-configuration.md b/java-chassis-reference/zh_CN/build-provider/access-log-configuration.md
index 775b945..15f7a64 100644
--- a/java-chassis-reference/zh_CN/build-provider/access-log-configuration.md
+++ b/java-chassis-reference/zh_CN/build-provider/access-log-configuration.md
@@ -31,33 +31,39 @@ _**Access log 配置项说明**_
### 日志格式配置
-目前可用的日志元素配置项见_**日志元素说明表**_。
+目前可用的日志元素配置项见 ***日志元素说明表(Apache & W3C)*** 和 ***日志元素说明表(ServiceComb)*** 。
-_**日志元素说明表**_
+_**日志元素说明表 (Apache & W3C)**_
| 元素名称 | Apache日志格式 | W3C日志格式 | 说明 |
| :--- | :--- | :--- | :--- |
-| Method | %m | cs-method | |
-| Status | %s | sc-status | |
-| Duration s | %T | - | |
-| Duration ms | %D | - | |
-| Remote Host | %h | - | |
-| Local Host | %v | - | |
-| Local port | %p | - | |
-| Bytes Written v1 | %B | - | 如果消息体长度为零则打印"0" |
-| Bytes Written v2 | %b | - | 如果消息体长度为零则打印"-" |
+| HTTP method | %m | cs-method | - |
+| HTTP status | %s | sc-status | - |
+| Duration in second | %T | - | - |
+| Duration in millisecond | %D | - | - |
+| Remote hostname | %h | - | - |
+| Local hostname | %v | - | - |
+| Local port | %p | - | - |
+| Size of response | %B | - | 如果消息体长度为零则打印"0" |
+| Size of response | %b | - | 如果消息体长度为零则打印"-" |
| First line of request | %r | - | 包含HTTP Method、Uri、Http版本三部分内容 |
-| URI path only | %U | cs-uri-stem | |
-| Query only | %q | cs-uri-query | |
-| URI path incl query | - | cs-uri | |
-| Version / Protocol | %H | - | |
-| Datetime Apache | %t | - | 按照默认设置打印时间戳，格式为"EEE, dd MMM yyyy HH:mm:ss zzz"，语言为英文，时区为GMT |
-| Datetime Apache Configurable v1 | %{PATTERN}t | - | 按照指定的格式打印时间戳，语言为英文，时区为GMT |
-| Datetime Apache Configurable v2 | %{PATTERN|TIMEZONE|LOCALE}t | - | 按照指定的格式、语言、时区打印时间戳。允许省略其中的某部分配置（但两个分隔符号"|"不可省略）。 |
-| Incoming Headers | %{IDENTIFIER}i | - | 如果没有找到指定的header，则打印"-" |
-| Outgoing Response Headers | %{IDENTIFIER}o | - | 如果没有找到指定的header，则打印"-" |
-| Cookie | %{IDENTIFIER}c | - | 如果没有找到指定的cookie，则打印"-" |
-| TraceId | - | - | ServiceComb框架提供的TraceId打印元素，占位符格式为"%SCB-traceId" |
+| URI path | %U | cs-uri-stem | - |
+| Query string | %q | cs-uri-query | - |
+| URI path and query string | - | cs-uri | - |
+| Request protocol | %H | - | - |
+| Datetime the request is received | %t | - | 按照默认设置打印时间戳，格式为"EEE, dd MMM yyyy HH:mm:ss zzz"，语言为英文，时区为GMT |
+| Configurable datetime the request is received | %{PATTERN}t | - | 按照指定的格式打印时间戳，语言为英文，时区为GMT |
+| Configurable datetime the request is received | %{PATTERN|TIMEZONE|LOCALE}t | - | 按照指定的格式、语言、时区打印时间戳。允许省略其中的某部分配置（但两个分隔符号"|"不可省略）。 |
+| Request header | %{VARNAME}i | - | 如果没有找到指定的header，则打印"-" |
+| Response header | %{VARNAME}o | - | 如果没有找到指定的header，则打印"-" |
+| Cookie | %{VARNAME}C | - | 如果没有找到指定的cookie，则打印"-" |
+
+_**日志元素说明表(ServiceComb)**_
+
+| Element | Placeholder | Comment |
+| :---- | :---------- | :------ |
+| TraceId | %SCB-traceId | 打印ServiceComb生成的trace id，找不到则打印"-" |
+| Invocation Context | %{VARNAME}SCB-ctx | 打印key为`VARNAME`的invocation context值，找不到则打印"-" |
### 日志输出文件配置
@@ -68,10 +74,10 @@ _**日志文件配置项**_
| 配置项 | 默认值 | 含义 | 说明 |
| :--- | :--- | :--- | :--- |
| paas.logs.accesslog.dir | ${paas.logs.dir} | 日志文件输出目录 | 与普通日志输出到同一个目录中 |
-| paas.logs.accesslog.file | access.log | 日志文件名 | |
-| log4j.appender.access.MaxBackupIndex | 10 | 最大保存的日志滚动文件个数 | |
+| paas.logs.accesslog.file | access.log | 日志文件名 | - |
+| log4j.appender.access.MaxBackupIndex | 10 | 最大保存的日志滚动文件个数 | - |
| log4j.appender.access.MaxFileSize | 20MB | 日志文件最大体积 | 正在记录的文件达到此大小时触发日志滚动存储 |
-| log4j.appender.access.logPermission | rw------- | 日志文件权限 | |
+| log4j.appender.access.logPermission | rw------- | 日志文件权限 | - |
> _**注意：**_
> 由于ServiceComb的日志打印功能只依赖slf4j的接口，因此用户可以选择其他日志打印框架，选择其他日志打印框架时需要用户自行配置日志文件输出选项。
@@ -136,6 +142,108 @@ _**日志文件配置项**_
</configuration>
```
+### 自定义扩展Access Log
+
+用户可以利用ServiceComb提供的AccessLogItem扩展机制，定制自己的AccessLogItem。
+
+#### 相关类说明
+
+1. `AccessLogItem`
+
+ ```java
+ public interface AccessLogItem<T> {
+ /**
+ * 从accessLogParam中获取特定的内容,组装成access log的打印内容并返回
+ */
+ String getFormattedItem(AccessLogParam<T> accessLogParam);
+ }
+ ```
+ `AccessLogItem`的定义如上所示，每一次请求触发Access Log打印时，ServiceComb的Access Log机制都会遍历有效的`AccessLogItem`，调用`getFormattedItem`方法获取此Item生成的Access Log片段，并将全部片段拼接成一条Access Log打印到日志文件中。
+ 参数`AccessLogParam<T>`包含请求开始时间、结束时间以及类型为`T`的请求上下文信息，在REST over Vertx通信方式中，类型`T`为Vert.x的`RoutingContext`。
+
+2. `VertxRestAccessLogItemMeta`
+
+ ```java
+ // pattern占位符前缀
+ protected String prefix;
+ // pattern占位符后缀
+ protected String suffix;
+ // 优先级序号
+ protected int order;
+ // AccessLogItem构造器
+ protected AccessLogItemCreator<RoutingContext> accessLogItemCreator;
+ ```
+ `VertxRestAccessLogItemMeta`包含如上属性，它定义了ServiceComb如何解析pattern字符串以获得特定的AccessLogItem。
+ - 如果用户想要定义一个占位符为`%user-defined`的`AccessLogItem`，则需要声明一个`VertxRestAccessLogItemMeta`的子类，设置prefix="%user-defined"，suffix=null，当`AccessLogPatternParser`解析到"%user-defined"时，从此meta类中取得`AccessLogItemCreator`创建对应的`AccessLogItem`。**注意**：由于"%user-defined"占位符中没有变量部分，因此调用`AccessLogItemCreator`传入的配置参数为null。
+ - 如果用户想要定义一个占位符为`%{VARNAME}user-defined`的`AccessLogItem`，则声明的`VertxRestAccessLogItemMeta`子类中，设置prefix="%{"，suffix="}user-defined"，当`AccessLogPatternParser`解析到"%{VARNAME}user-defined"时，会截取出"VARNAME"作为配置参数传入`AccessLogItemCreator`，创建一个`AccessLogItem`。
+
+ `VertxRestAccessLogItemMeta`有一个子类`CompositeVertxRestAccessLogItemMeta`，当用户需要定义多个AccessLogItem时，可以将多个`VertxRestAccessLogItemMeta`聚合到`CompositeVertxRestAccessLogItemMeta`中。Parser加载到类型为`CompositeVertxRestAccessLogItemMeta`的AccessLogItemMeta时，会调用其`getAccessLogItemMetas()`方法获得一组AccessLogItemMeta。`VertxRestAccessLogItemMeta`使用SPI机制加载，而`CompositeVertxRestAccessLogItemMeta`可以让用户只在SPI配置文件中配置一条记录就加载多条meta信息，给了用户更灵活的选择。
+
+3. `AccessLogItemCreator`
+
+ ```java
+ public interface AccessLogItemCreator<T> {
+ // 接收配置值，返回一个AccessLogItem。如果AccessLogItem的占位符没有可变的配置值部分，则此方法会接收到null。
+ AccessLogItem<T> createItem(String config);
+ }
+ ```
+
+ 用户通过设置在自定义的`VertxRestAccessLogItemMeta`中的`AccessLogItemCreator`实例化自己的`AccessLogItem`。由于这是一个函数式接口，当`AccessLogItem`的初始化方式较简单时，可以直接使用Lambda表达式定义Creator，以简化开发。
+
+#### AccessLogItemMeta的匹配规则
+
+AccessLogItemMeta加载进Parser后，会进行一次排序。Parser解析pattern串时会从前到后匹配meta list，总的匹配规则如下：
+1. 优先匹配高优先级的meta。
+2. 优先匹配有后缀的meta，当匹配上多个有后缀meta时，取前后缀相距最小的一个。
+3. 优先匹配占位符长的meta，例如有两个meta，"%abc"和"%a"，如果匹配中了"%abc"则直接返回，不再匹配"%a"。
+
+#### 示例说明
+
+1. 扩展自定义AccessLogItem
+
+ 首先用户需要`AccessLogItem`接口实现自己的item：
+ ```java
+ public class UserDefinedAccessLogItem implements AccessLogItem<RoutingContext> {
+ private String config;
+
+ public UserDefinedAccessLogItem(String config) {
+ this.config = config;
+ }
+
+ @Override
+ public String getFormattedItem(AccessLogParam<RoutingContext> accessLogParam) {
+ // 此处是用户自定义的逻辑，需要从AccessLogParam或其他地方取相关数据，生成并返回access log片段
+ return "user-defined-[" + config + "]-[" + accessLogParam.getStartMillisecond() + "]";
+ }
+ }
+ ```
+
+2. 定义AccessLogItem的meta类
+
+ 继承`VertxRestAccessLogItemMeta`或`CompositeVertxRestAccessLogItemMeta`类，定义AccessLogItem的前后缀等信息：
+ ```java
+ public class UserDefinedCompositeExtendedAccessLogItemMeta extends CompositeVertxRestAccessLogItemMeta {
+ private static final List<VertxRestAccessLogItemMeta> META_LIST = new ArrayList<>();
+
+ static {
+ META_LIST.add(new VertxRestAccessLogItemMeta("%{", "}user-defined", UserDefinedAccessLogItem::new));
+ }
+
+ @Override
+ public List<VertxRestAccessLogItemMeta> getAccessLogItemMetas() {
+ return META_LIST;
+ }
+ }
+ ```
+
+3. 配置SPI加载文件
+
+ 在`resources/META-INF/services/`目录下定义一个名为"org.apache.servicecomb.transport.rest.vertx.accesslog.parser.VertxRestAccessLogItemMeta"的文件，将上一步中定义的meta类完整类名填写到该文件中，供Parser加载meta类。
+
+4. 配置Access Log的pattern
+
+ 在microservice.yaml文件中的配置pattern，假设为"%{test-config}user-defined"，运行服务触发Access Log打印，假设请求开始时间为1，则可以看到Access Log打印内容为"user-defined-[test-config]-[1]"。
+
## 示例代码
### microservice.yaml文件中的配置
@@ -159,6 +267,3 @@ log4j.appender.access.MaxBackupIndex=10
log4j.appender.access.MaxFileSize=20MB
log4j.appender.access.logPermission=rw-------
```
-
-
-