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/servicecomb-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 86fa6b2 [SCB-1820] add doc of request log and fixes some problems
86fa6b2 is described below
commit 86fa6b261cd3bf04cb9c6bef0359e9266b8f97a1
Author: heyile <[email protected]>
AuthorDate: Tue Mar 24 21:13:51 2020 +0800
[SCB-1820] add doc of request log and fixes some problems
---
.../build-provider/access-log-configuration.md | 212 +++++++++++++++------
.../docs/config-reference/rest-transport-client.md | 3 +-
2 files changed, 160 insertions(+), 55 deletions(-)
diff --git
a/java-chassis-reference/zh_CN/docs/build-provider/access-log-configuration.md
b/java-chassis-reference/zh_CN/docs/build-provider/access-log-configuration.md
index 15f7a64..37ab54c 100644
---
a/java-chassis-reference/zh_CN/docs/build-provider/access-log-configuration.md
+++
b/java-chassis-reference/zh_CN/docs/build-provider/access-log-configuration.md
@@ -1,33 +1,41 @@
## 概念阐述
-ServiceComb提供了基于Vert.x的access log功能。当用户使用REST over
Vertx通信方式时，可以通过简单的配置启用access log打印功能。
+ServiceComb提供了基于Vert.x的access log 和 request log功能。当用户使用REST over
Vertx通信方式时，可以通过简单的配置启用access log打印功能。当用户 client 端进行远程调用时，可以通过简单的配置启用request
log打印功能
## 场景描述
-用户在调试服务时可能需要开启access log。在使用REST over servlet通信方式的情况下，可以使用web容器的access
log功能；而在使用REST over Vertx通信方式的情况下，可以使用ServiceComb提供的一套access log功能。
+1. 用户在调试服务时可能需要开启access log。在使用REST over servlet通信方式的情况下，可以使用web容器的access
log功能；而在使用REST over Vertx通信方式的情况下，可以使用ServiceComb提供的一套access log功能。
+
+2. 用户想要跟踪，记录客户端远程调用信息， 可以开启 request log。request log 同时支持记录 rest 和 highway
远程调用方式。
## 配置说明
-### 启用Access Log
+### 启用Access Log and Request Log
-用户需要在microservice.yaml文件中增加配置以启用access log，配置示例如下：
+用户需要在microservice.yaml文件中增加配置以启用access log 和 request log，配置示例如下：
```yaml
servicecomb:
accesslog:
- enabled: true ## 启用access log
+ enabled: true ## server 端 启用access log
+ pattern: "%h - - %t %r %s %B %D" ## server 端 自定义 access log 日志格式
+ request:
+ enabled: true ## client 端开启 request log
+ pattern: "%h %SCB-transport - - %t %r %s %D" ## client 端自定义 request log
日志格式
```
-_**Access log 配置项说明**_
+_**Access log & Request log 配置项说明**_
| 配置项 | 取值范围 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
-| servicecomb.accesslog.enabled | true/false | false | 如果为true则启用access
log，否则不启用 |
-| servicecomb.accesslog.pattern | 表示打印格式的字符串 | "%h - - %t %r %s %B" |
配置项见_**日志元素说明表**_ |
+| servicecomb.accesslog.enabled | true/false | **false** | 如果为true则启用access
log，否则不启用 |
+| servicecomb.accesslog.pattern | 表示打印格式的字符串 | **"%h - - %t %r %s %B %D"** |
配置项见_**日志元素说明表**_ |
+| servicecomb.accesslog.request.enabled | true/false | **false** |
如果为true则启用request log，否则不启用 |
+| servicecomb.accesslog.request.pattern | 表示打印格式的字符串 | **"%h %SCB-transport -
- %t %r %s %D"** | 配置项见_**日志元素说明表**_ |
> _**说明：**_
>
-> * 以上两个配置项均可省略，若省略则使用默认值。
+> * 以上四个配置项均可省略，若省略则使用默认值。
### 日志格式配置
@@ -64,6 +72,36 @@ _**日志元素说明表(ServiceComb)**_
| :---- | :---------- | :------ |
| TraceId | %SCB-traceId | 打印ServiceComb生成的trace id，找不到则打印"-" |
| Invocation Context | %{VARNAME}SCB-ctx | 打印key为`VARNAME`的invocation
context值，找不到则打印"-" |
+| Transport Method | %SCB-transport | 打印当前调用的 **transport method** 。 `rest` 或者
`highway`|
+
+_**Access log 与 Request log的日志元素对比**_
+
+| 元素名称 | Apache&W3C日志格式 | access log |access log 说明 | request log | request
log说明 |
+| --- | --- | --- | --- | --- | --- |
+| HTTP method | %m & cs-method | support | - | support | - |
+| HTTP status | %s & sc-status | support | - | support | - |
+| Duration in second | %T | support | - | support | - |
+| Duration in millisecond | %D | support | - | support | - |
+| Remote hostname | %h | support | - | support | - |
+| Local hostname | %v | support | - | support | - |
+| Local port | %p | support | - | support | - |
+| Size of response | %B | support | 如果消息体长度为零则打印"0" | unsupported| - |
+| Size of response | %b | support | 如果消息体长度为零则打印"-" | unsupported| - |
+| First line of request | %r | support | 包含HTTP Method、Uri、Http版本三部分内容|
support | 包含HTTP Method、Uri、Http版本三部分内容|
+|URI path| %U & cs-uri-stem | support | - | support | - |
+|Query string | %q & cs-uri-query | support | - | support | - |
+|URI path and query string | cs-uri | support | - | support | - |
+| Request protocol | %H | support | - | support | - |
+| Datetime of the request | %t | support | 收到请求的时间。默认格式为"EEE, dd MMM yyyy
HH:mm:ss zzz"，语言为英文，时区为GMT | support | 发送请求的时间。默认格式为"EEE, dd MMM yyyy HH:mm:ss
zzz"，语言为英文，时区为GMT|
+|Configurable datetime the request of the request | %{PATTERN}t | support |
收到请求的时间。按照指定的格式打印时间戳，语言为英文，时区为GMT | support | 发送请求的时间。按照指定的格式打印时间戳，语言为英文，时区为GMT|
+|Configurable datetime the request of the request |
%{PATTERN|TIMEZONE|LOCALE}t | support |
收到请求的时间。按照指定的格式、语言、时区打印时间戳。允许省略其中的某部分配置（但两个分隔符号"|"不可省略）。| support |
发送请求的时间。按照指定的格式、语言、时区打印时间戳。允许省略其中的某部分配置（但两个分隔符号"|"不可省略）。|
+|Request header | %{VARNAME}i | support | 如果没有找到指定的header，则打印"-" | support |
如果没有找到指定的header，则打印"-" |
+|Response header | %{VARNAME}o | support | 如果没有找到指定的header，则打印"-"| support |
如果没有找到指定的header，则打印"-" |
+|Cookie | %{VARNAME}C | support | 如果没有找到指定的cookie，则打印"-" | support |
如果没有找到指定的cookie，则打印"-" |
+|TraceId | %SCB-traceId | support |打印ServiceComb生成的trace id，找不到则打印"-" |
support |打印ServiceComb生成的trace id，找不到则打印"-" |
+|Invocation Context | %{VARNAME}SCB-ctx | support | 打印key为`VARNAME`的invocation
context值，找不到则打印"-" |support | 打印key为`VARNAME`的invocation context值，找不到则打印"-" |
+|transport method | %SCB-transport | unsupported | 只支持 rest 形式调用 | support |
调用使用的transport method|
+
### 日志输出文件配置
@@ -78,6 +116,11 @@ _**日志文件配置项**_
| log4j.appender.access.MaxBackupIndex | 10 | 最大保存的日志滚动文件个数 | - |
| log4j.appender.access.MaxFileSize | 20MB | 日志文件最大体积 | 正在记录的文件达到此大小时触发日志滚动存储 |
| log4j.appender.access.logPermission | rw------- | 日志文件权限 | - |
+| paas.logs.requestlog.dir | ${paas.logs.dir} | 日志文件输出目录 | 与普通日志输出到同一个目录中 |
+| paas.logs.requestlog.file | request.log | 日志文件名 | - |
+| log4j.appender.request.MaxBackupIndex | 10 | 最大保存的日志滚动文件个数 | - |
+| log4j.appender.request.MaxFileSize | 20MB | 日志文件最大体积 | 正在记录的文件达到此大小时触发日志滚动存储
|
+| log4j.appender.request.logPermission | rw------- | 日志文件权限 | - |
> _**注意：**_
> 由于ServiceComb的日志打印功能只依赖slf4j的接口，因此用户可以选择其他日志打印框架，选择其他日志打印框架时需要用户自行配置日志文件输出选项。
@@ -116,9 +159,9 @@ _**日志文件配置项**_
</dependency>
```
-#### 3. 配置access log组件的logger
+#### 3. 配置access log & request log 组件的logger
-由于ServiceComb提供的日志打印组件是获取名为`accesslog`的logger来打印access
log的，因此将日志实现框架从Log4j切换为logback的关键就是提供一个名为`accesslog`，并为其配置好日志输出文件。以下是access
log在logback配置文件中的配置示例（本示例仅展示access log相关的配置，其他日志配置均省略）：
+由于ServiceComb提供的日志打印组件是获取名为`accesslog` & `requestlog` 的logger来打印access log 和
request log ，因此将日志实现框架从Log4j切换为logback的关键就是提供一个名为`accesslog` & `requestlog` 的
Logger，并为其配置好日志输出文件。以下是 **access log** & **request log**
在logback配置文件中的配置示例（本示例仅展示access log & request log相关的配置，其他日志配置均省略）：
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -134,34 +177,57 @@ _**日志文件配置项**_
<pattern>%msg%n</pattern>
</encoder>
</appender>
+ <appender name="REQUESTLOG"
class="ch.qos.logback.core.rolling.RollingFileAppender">
+ <file>./logs/request.log</file>
+ <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+ <fileNamePattern>./logs/access-%d{yyyy-MM-dd}.log</fileNamePattern>
+ </rollingPolicy>
+ <!-- 注意：由于request log的内容是在代码中完成格式化的，因此这里只需输出message即可，无需添加额外的格式 -->
+ <encoder>
+ <pattern>%msg%n</pattern>
+ </encoder>
+ </appender>
<!-- 提供一个名为"accesslog"的logger供access log打印组件使用 -->
<logger name="accesslog" level="INFO" additivity="false">
<appender-ref ref="ACCESSLOG" />
</logger>
+ <!-- 提供一个名为"requestlog"的logger供request log打印组件使用 -->
+ <logger name="requestlog" level="INFO" additivity="false">
+ <appender-ref ref="REQUESTLOG" />
+ </logger>
+
</configuration>
```
-### 自定义扩展Access Log
+### 自定义扩展Access Log & Request Log
-用户可以利用ServiceComb提供的AccessLogItem扩展机制，定制自己的AccessLogItem。
+用户可以利用ServiceComb提供的AccessLogItem扩展机制，定制自己的AccessLogItem， 我们把 Request Log
也当做一种 Access Log。
#### 相关类说明
-1. `AccessLogItem`
+1. **AccessLogItem**
- ```java
- public interface AccessLogItem<T> {
- /**
- * 从accessLogParam中获取特定的内容,组装成access log的打印内容并返回
- */
- String getFormattedItem(AccessLogParam<T> accessLogParam);
+```java
+public interface AccessLogItem<T> {
+ // 从Server端获取信息，打印 Access Log 日志
+ default void appendServerFormattedItem(ServerAccessLogEvent accessLogEvent,
StringBuilder builder) {
}
- ```
- `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`
+ // 从Client 端获取信息， 打印 Request Log
+ default void appendClientFormattedItem(InvocationFinishEvent clientLogEvent,
StringBuilder builder) {
+ }
+}
+```
+
+> **AccessLogItem** 的定义如上所示
+>
+> * **Server 端** 每收到一个请求，会触发一次 Access Log 日志打印。**Client 端** 每次对外远程调用结束，会触发一次
Request Log 日志打印。
+>
+> * 每次日志打印，SDK 都会遍历有效的 `AccessLogItem`
，调用对应的方法获取此Item生成的Log片段，并将全部片段拼接成一条Log打印到日志文件中。
+
+
+2. **VertxRestAccessLogItemMeta**
```java
// pattern占位符前缀
@@ -173,13 +239,16 @@ _**日志文件配置项**_
// 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`
包含如上属性，它定义了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`
+3. **AccessLogItemCreator**
```java
public interface AccessLogItemCreator<T> {
@@ -193,16 +262,20 @@ _**日志文件配置项**_
#### AccessLogItemMeta的匹配规则
AccessLogItemMeta加载进Parser后，会进行一次排序。Parser解析pattern串时会从前到后匹配meta list，总的匹配规则如下：
+
1. 优先匹配高优先级的meta。
+
2. 优先匹配有后缀的meta，当匹配上多个有后缀meta时，取前后缀相距最小的一个。
+
3. 优先匹配占位符长的meta，例如有两个meta，"%abc"和"%a"，如果匹配中了"%abc"则直接返回，不再匹配"%a"。
#### 示例说明
1. 扩展自定义AccessLogItem
- 首先用户需要`AccessLogItem`接口实现自己的item：
- ```java
+首先用户需要`AccessLogItem`接口实现自己的item：
+
+```java
public class UserDefinedAccessLogItem implements
AccessLogItem<RoutingContext> {
private String config;
@@ -211,38 +284,60 @@ AccessLogItemMeta加载进Parser后，会进行一次排序。Parser解析patter
}
@Override
- public String getFormattedItem(AccessLogParam<RoutingContext>
accessLogParam) {
- // 此处是用户自定义的逻辑，需要从AccessLogParam或其他地方取相关数据，生成并返回access log片段
- return "user-defined-[" + config + "]-[" +
accessLogParam.getStartMillisecond() + "]";
+ public void appendServerFormattedItem(ServerAccessLogEvent accessLogEvent,
StringBuilder builder) {
+ builder.append("user-defined--server-")
+ .append(accessLogEvent.getRoutingContext().response().getStatusCode())
+ .append("-")
+ .append(config);
+ }
+
+ @Override
+ public void appendClientFormattedItem(InvocationFinishEvent
clientLogEvent, StringBuilder builder) {
+ builder.append("user-server-defined-")
+ .append(clientLogEvent.getResponse().getStatus())
+ .append("-")
+ .append(config);
}
}
- ```
+ ```
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;
- }
- }
- ```
+
+```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
+4. 配置 Access Log的 pattern
+
+```yaml
+# 服务端配置
+servicecomb:
+ accesslog:
+ enabled: true ## 应用作为服务端，开启 Access log
+ pattern: "%{param}user-defined" ## Access log 日志格式
+ request:
+ enabled: true ## 应用作为客户端，开启 Request log
+ pattern: "%{param}user-defined" ## Request log 日志格式
+```
- 在microservice.yaml文件中的配置pattern，假设为"%{test-config}user-defined"，运行服务触发Access
Log打印，假设请求开始时间为1，则可以看到Access Log打印内容为"user-defined-[test-config]-[1]"。
+以服务端为例， 运行服务触发Access Log打印，假设请求返回状态码是 200，则可以看到Access Log打印内容为
"`user-defined--server-200-param`"。
## 示例代码
@@ -252,18 +347,27 @@ AccessLogItemMeta加载进Parser后，会进行一次排序。Parser解析patter
## other configurations omitted
servicecomb:
accesslog:
- enabled: true ## 启用access log
- pattern: "%h - - %t %r %s %B" ## 自定义日志格式
+ enabled: true ## 应用作为服务端，开启 Access log
+ pattern: "%h - - %t %r %s %B %D" ## Access log 日志格式
+ request:
+ enabled: true ## 应用作为客户端，开启 Request log
+ pattern: "%h %SCB-transport - - %t %r %s %D" ## Request log 日志格式
+
```
### log4j.properties文件中的配置
```properties
-# access log configuration item
-paas.logs.accesslog.dir=../logs/
+# log configuration item
+paas.logs.dir=../logs/
paas.logs.accesslog.file=access.log
+paas.logs.requestlog.file=request.log
# access log File appender
log4j.appender.access.MaxBackupIndex=10
log4j.appender.access.MaxFileSize=20MB
log4j.appender.access.logPermission=rw-------
+# request log File appender
+log4j.appender.request.MaxBackupIndex=10
+log4j.appender.request.MaxFileSize=20MB
+log4j.appender.request.logPermission=rw-------
```
diff --git
a/java-chassis-reference/zh_CN/docs/config-reference/rest-transport-client.md
b/java-chassis-reference/zh_CN/docs/config-reference/rest-transport-client.md
index b2acc79..8a7d5f8 100644
---
a/java-chassis-reference/zh_CN/docs/config-reference/rest-transport-client.md
+++
b/java-chassis-reference/zh_CN/docs/config-reference/rest-transport-client.md
@@ -17,7 +17,8 @@
**备注**:
-1. 如果没有配置，或者配置的值小于8，为CPU的核数。 如果CPU核数小于8， 取8。
+1. 如果没有配置，为CPU的核数，如果CPU核数小于8，则取8。
+
2. java-chassis 默认采用 vert.x 的 HTTP Client 功能，这个配置项对应的是 verticle instances 数量。
verticle instances 数量
会影响并发资源分配。比如： 如果 verticle instances 为 2， maxPoolSize 为 5， 那么实际创建的连接数为
2*5=10。
