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 <yaohai...@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-------
```
-
-
-
